<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8" xml:lang="en"><title>Pre-Conditions

and Post-Conditions for Kernel APIs</title><shortdesc>Reference documentation for kernel side function APIs, specifies

a wide variety of pre-conditions and post-conditions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<ul>

<li id="GUID-C8EAD446-F9B7-50A3-8A7C-FA45487287BA"><p>A <i>pre-condition</i> is

something that must be true before using the function. </p> </li>

<li id="GUID-0360AD60-7A36-5949-AFF8-6649619F9F6A"><p>A <i>post-condition</i> is

something that is true on return from the function. </p> </li>

</ul>

<p>Such conditions are expressed using a standard phrase, wherever possible,

and this section explains what those conditions mean. </p>

<p>Where more than one pre-condition is stated for a given function, then

you can assume that all pre-conditions apply. In this sense, there is an implied

AND relation between conditions. For example, in the description of the function <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita#GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497/GUID-9DF684E6-F367-3A3B-BA02-301297607160"><apiname>DObject::AppendFullName()</apiname></xref>,

the following pre-conditions apply: </p>

<codeblock id="GUID-A81563CA-D72C-5B9F-820E-1AA1623E75F7" xml:space="preserve">No fast mutex can be held.

Call in a thread context.</codeblock>

<p>Both conditions must be true before calling the functions. </p>

<p>There are exceptions to this rule, where a precondition applies only if

some other factor is true. For example, in the description of the function <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita#GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497/GUID-3120933C-095D-3D20-A024-148BA0D473EB"><apiname>DObject::TraceAppendName()</apiname></xref>,

you will find the following pre-conditions: </p>

<codeblock id="GUID-3BC88AB3-DBCD-5F4A-9E5E-14B5C711F604" xml:space="preserve">Call either in a thread or an IDFC context, if aLock=TRUE

Call in any context, if aLock=FALSE.</codeblock>

<p>Clearly, only one pre-condition will apply, depending on the supplied value

of the <codeph>aLock</codeph> argument. </p>

<p>A few conditions are self-explanatory, and these are not included in these

lists. </p>

<p>NOTE that some familiarity with kernel side programming is assumed. </p>

<ul>

<li id="GUID-331B0761-C3D7-517F-872E-97E5E11A1E3C"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-5F986149-D75B-5B3F-92F3-7B4FB89F4718">Pre-conditions</xref>  </p> </li>

<li id="GUID-080AD617-2744-556C-AF4E-7FF8AB0B7091"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-F2DE76D5-0970-584F-9526-52E85932ACE8">Post-conditions</xref>  </p> </li>

</ul>

<section id="GUID-5F986149-D75B-5B3F-92F3-7B4FB89F4718"><title>Pre-conditions</title> <p>This

describes the meaning of each precondition, and tries to provide insight as

to why it needs to be satisfied, and explains what you need to do to ensure

that the preconditions are met. </p> <ul>

<li id="GUID-AB16CE53-001A-51C9-B6EE-CDCC74B034A6"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-B0F8E686-A86D-5A99-8560-7D591CE84BD0">Calling thread must be in a critical section</xref>  </p> </li>

<li id="GUID-2EC96768-6346-50E1-BA85-81F0D27444BE"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-3EE55520-0F0D-508B-A384-55082ED10D72">Calling thread must not be in a critical section</xref>  </p> </li>

<li id="GUID-AACA75DB-5494-536B-ABF5-CA3ACF5351D6"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-09CB97CE-8DAF-58FA-B240-5B396ABC9614">Calling thread can either be in a critical section or not</xref>  </p> </li>

<li id="GUID-88BB1943-77A6-5AA1-805A-FADF0C56880F"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-EDA4EF5D-B6CB-5446-AEBD-A9888C86FBA1">No fast mutex can be held</xref>  </p> </li>

<li id="GUID-C683D62F-7918-54C6-A184-32A2B64F9D58"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-B6943D58-99B9-5A4B-A1DD-577B6197F274">Kernel must be locked</xref>  </p> </li>

<li id="GUID-668F8DB9-5FB1-5DC3-B1F2-4BD9C3F5B4F9"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-8027AB9A-858F-5945-A75B-E817AD76DEC3">Kernel must be unlocked</xref>  </p> </li>

<li id="GUID-0B48309C-E7C9-5857-BA1F-731D69E73118"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-F80292D9-E3C8-5466-ABD3-0416CDE2BD00">Kernel can be locked or unlocked</xref>  </p> </li>

<li id="GUID-7F1C7BE6-1B5E-5800-8B9F-30279A24727E"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-EC063E55-66F7-52E9-AF47-F981B63E446E">Kernel must be locked, with lock count 1</xref>  </p> </li>

<li id="GUID-8AEFABE4-320E-5AF8-89F8-6402EE9BBCE6"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-A55086AA-382B-5F93-9CE0-42C6FB428A19">Interrupts must be enabled</xref>  </p> </li>

<li id="GUID-B56F2B78-49D8-5B51-BA27-F8BC07DA948C"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-9384C08B-D56F-5284-BA4B-4CF6C85E06E4">Interrupts must be disabled</xref>  </p> </li>

<li id="GUID-8113FADD-4E41-5589-9CBD-3B63B9231A19"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-E1A36F24-AC68-58AF-B344-A59111F621FA">Interrupts can either be enabled or disabled</xref>  </p> </li>

<li id="GUID-C8FF141B-C104-5B4A-9F3C-7857B20ABEC1"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-1E584D23-5233-5A38-A629-FBFE834F8248">System lock must be held</xref>  </p> </li>

<li id="GUID-43383A78-182B-5F42-8458-FAD5DB768ACB"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-74F93316-0DAC-5F4F-A307-C0C15B14E794">System lock must not be held</xref>  </p> </li>

<li id="GUID-AB5BDF10-F90A-5ECB-AF56-FE4A06038271"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-BA42435C-85B9-5A86-B875-50FE69B99B48">Call in a thread context</xref>  </p> </li>

<li id="GUID-BBE5C5FC-9497-5FEB-8FCF-B43F0800FBBF"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-3FE5AA98-FD6C-528D-9DF2-7C50BE7FEF8E">Call in an IDFC contex</xref>  </p> </li>

<li id="GUID-102DFFA4-D584-54D0-BF4A-FB5CC3F622BB"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-6957D624-5176-591C-A667-4DF78B29F271">Call either in a thread or an IDFC context</xref>  </p> </li>

<li id="GUID-2530C61A-5997-5BB8-B7BC-E249F2C32A6C"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-A45A1D39-8C76-5E14-8DCF-FCE0A26758CE">Call in any context</xref>  </p> </li>

<li id="GUID-0FFD6392-52C4-5403-81A5-35ADC75B5A0A"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-0DCAE842-45E1-5F5F-BC68-121775D0B702">Do not call from an ISR</xref>  </p> </li>

<li id="GUID-F018CCD9-7FEC-5CD7-A424-B4F1B874938D"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-F17D0FE5-BA42-575B-8971-C5B034CF404E">The calling thread must own the semaphore</xref>  </p> </li>

<li id="GUID-A9B993F9-A833-56CE-A3AE-D7CBF749A002"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-8D9D08F5-0CBD-52BB-B416-636516982D47">The calling thread must not be explicitly suspended</xref>  </p> </li>

<li id="GUID-561FCAEF-10F5-52A0-B84D-0B10C6E6F051"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-910660F9-F30F-5725-981D-52F65F7FDB81">The calling thread must hold the mutex</xref>  </p> </li>

<li id="GUID-F20B2CE8-975E-55FE-9994-7920E106209B"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-DDEB4D47-04F5-5736-A8BE-3F1AC543F9D7">Call only from ISR, IDFC or thread with the kernel locked</xref>  </p> </li>

<li id="GUID-AB365D33-E6D5-544C-8A85-13635F7D8A46"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-3D8578BC-86EE-5E64-9C1E-CCD512A344D1">Call only from IDFC or thread with the kernel locked</xref>  </p> </li>

<li id="GUID-DDDF61AA-0B7B-5862-B854-A776F5375D3E"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-2147A0B6-365A-5AC3-8EBE-AC0D89ED0C70">Do not call from thread with the kernel unlocked</xref>  </p> </li>

<li id="GUID-416323F1-316F-5F91-9210-5B7B02D5214A"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-7E26E475-5D7E-5C68-B3A4-BC9EC6D29D98">Do not call from ISR or thread with the kernel unlocked</xref>  </p> </li>

<li id="GUID-107003E0-BBAF-5408-AEE8-6B285A2D44D6"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-6C17250C-4FD0-5A2E-B448-BC08504F4FE4">Thread must not already be exiting</xref>  </p> </li>

<li id="GUID-7598A74D-A7C3-544A-A856-A95639CC874B"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-021E54DB-7F22-5ADB-A80D-CAFBB08596A2">Property has not been opened</xref>  </p> </li>

<li id="GUID-F8900E2C-BB1C-547F-8945-269D8FCE6D99"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-D924E37C-300A-58FF-890B-F1FA5349FA05">Property has been opened</xref>  </p> </li>

<li id="GUID-DFDC1EB0-72CE-5C6D-BDBB-69160E8D6CFD"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-F1485BCB-8384-518B-AE5B-F8387DF0C8F4">Must be called under an XTRAP harness or calling thread must not be in a

critical section</xref>  </p> </li>

<li id="GUID-0E1D40B1-C88B-5EE8-BDB7-A5897900444F"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-4D6B9502-0F88-5E0E-8E92-5783FE76555A">DObject::Lock fast mutex held</xref>  </p> </li>

<li id="GUID-E766DB63-A091-5577-8FA3-6AC8D3E36A4E"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-D6BB3BE3-E0DD-50B9-B9D1-275E51CE7FC6">DCodeSeg::CodeSegLock mutex held</xref>  </p> </li>

<li id="GUID-8DCD023D-BC60-5FCE-B3E2-FB9BD98360C2"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-9A82D0DD-7599-5511-AD9E-2930ADC99AC0">Any kind of lock can be held</xref>  </p> </li>

<li id="GUID-66EB3E8B-19F1-5189-A029-1AF10FCCE787"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-F9800056-B5E5-576D-B440-544AE067D4DC">Call only from Init1() in base port</xref>  </p> </li>

<li id="GUID-83F3A08D-0A58-58C3-99C0-AC976FC376C6"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-6122C9C6-05EB-508C-8C9A-45B6A8DAB42C">The various parameters must be valid. The PIL or PSL will fault the kernel

if not</xref>  </p> </li>

<li id="GUID-E6325367-1F64-53AF-B992-D94DC7FD88A5"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-041025B4-95B9-5493-ACC3-649B6683DE0D">The request is not being transferred or pending</xref>  </p> </li>

<li id="GUID-CB33058C-50D1-520B-BB5B-FA723301367F"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-582E833B-C0E9-5986-86C5-24BF15648D61">Wait on TimerMutex before calling this</xref>  </p> </li>

<li id="GUID-A42C4B9A-6B96-51A7-952C-DD3905307B7C"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-98CBADF3-8CD3-54BC-8CB7-C2BD8D48289A">Message must be in ACCEPTED state</xref>  </p> </li>

<li id="GUID-736AEF0F-17DB-5DF4-9236-51D32F51291D"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-B9E940EF-0EC8-5EEB-B29B-B402BFF09350">Queue must not be in asynchronous receive mode</xref>  </p> </li>

<li id="GUID-253F522F-B0BF-5EBC-8EE9-F312807BC432"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-52D720FB-7F57-5340-8C34-F39FE1E50C36">Container mutex must be held</xref>  </p> </li>

<li id="GUID-CBE2383B-2861-50F3-BEE5-0AEDCFEF2AFA"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-52D720FB-7F57-5340-8C34-F39FE1E50C36">Thread container mutex must be held</xref>  </p> </li>

<li id="GUID-3E90CD26-6578-5FE2-904C-8C2E648267F0"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-52D720FB-7F57-5340-8C34-F39FE1E50C36">Process container mutex must be held</xref>  </p> </li>

</ul> <p id="GUID-B0F8E686-A86D-5A99-8560-7D591CE84BD0"><b>Calling thread must be in

a critical section</b> </p> <p>Critical sections are sections of code that

leave the kernel in a compromised state if they cannot complete. A thread

enters a critical section by calling <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-841D587C-E9E6-34EE-8ED0-E9A206F64379"><apiname>NKern::ThreadEnterCS()</apiname></xref> and

leaves it by calling <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-2C897BA5-2BD7-3ABA-9F2B-F0B1AC14D1AE"><apiname>NKern::ThreadLeaveCS()</apiname></xref>. </p> <p>While

in a critical section, the thread cannot be suspended or killed. These actions

are deferred until the end of the critical section. If a thread takes an exception

while inside a critical section, this is treated as fatal to the system, and

cause a <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-45337A03-5893-3D0D-948C-23BDCF8AECBD"><apiname>Kern::Fault()</apiname></xref>. </p> <p>The described function must

be in a critical section when called. </p> <p id="GUID-3EE55520-0F0D-508B-A384-55082ED10D72"><b>Calling thread must not

be in a critical section</b> </p> <p>Critical sections are sections of code

that leave the kernel in a compromised state if they cannot complete. A thread

enters a critical section by calling <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-841D587C-E9E6-34EE-8ED0-E9A206F64379"><apiname>NKern::ThreadEnterCS()</apiname></xref> and

leaves it by calling <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-2C897BA5-2BD7-3ABA-9F2B-F0B1AC14D1AE"><apiname>NKern::ThreadLeaveCS()</apiname></xref>. </p> <p>While

in a critical section, the thread cannot be suspended or killed. These actions

are deferred until the end of the critical section. If a thread takes an exception

while inside a critical section, this is treated as fatal to the system, and

cause a <codeph>Kern::Fault()</codeph>. </p> <p>There are some functions winthin

the system that must <i>NOT</i> be in a critical section when called. This

applies to the described functions. </p> <p id="GUID-09CB97CE-8DAF-58FA-B240-5B396ABC9614"><b>Calling thread can either

be in a critical section or not</b> </p> <p>Critical sections are sections

of code that leave the kernel in a compromised state if they cannot complete.

A thread enters a critical section by calling <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-841D587C-E9E6-34EE-8ED0-E9A206F64379"><apiname>NKern::ThreadEnterCS()</apiname></xref> and

leaves it by calling <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-2C897BA5-2BD7-3ABA-9F2B-F0B1AC14D1AE"><apiname>NKern::ThreadLeaveCS()</apiname></xref>. </p> <p>While

in a critical section, the thread cannot be suspended or killed. These actions

are deferred until the end of the critical section. If a thread takes an exception

while inside a critical section, this is treated as fatal to the system, and

cause a <codeph>Kern::Fault()</codeph>. </p> <p>When this pre-condition applies

to the described function, it means that it does not matter whether the code

is in a critical section or not. </p> <p id="GUID-EDA4EF5D-B6CB-5446-AEBD-A9888C86FBA1"><b>No fast mutex can be held</b> </p> <p>A

thread can hold no more than one fast mutex at any given time. The described

function uses a fast mutex, which means that on entry to the function, the

calling thread must <i>not</i> hold another one. </p> <p id="GUID-B6943D58-99B9-5A4B-A1DD-577B6197F274"><b>Kernel must be locked</b> </p> <p>Many

kernel side functions run with interrupts enabled, including code that manipulates

global structures, such as the thread ready list. To prevent such code from

being reentered and potentially corrupting the structure concerned, a lock

known as the kernel lock (sometimes referred to as the preemption lock) is

used. </p> <p>Sections of code that need to be protected against rescheduling

call <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-7CBBF72B-4519-38DD-92CA-38AF636AFD8A"><apiname>NKern::Lock()</apiname></xref>. Interrupt Service Routines (ISRs) can

still run but no other thread (or IDFC) can run until the kernel is unlocked

by a call to <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-A1A42137-906C-30F1-AF61-4F786FC372DE"><apiname>NKern::Unlock()</apiname></xref>. </p> <p>The pre-condition

means that the kernel lock must be set before calling the described function. </p> <p id="GUID-8027AB9A-858F-5945-A75B-E817AD76DEC3"><b>Kernel must be unlocked</b> </p> <p>Many

kernel side functions run with interrupts enabled, including code that manipulates

global structures, such as the thread ready list. To prevent such code from

being reentered and potentially corrupting the structure concerned, a lock

known as the kernel lock (sometimes referred to as the preemption lock) is

used. </p> <p>Sections of code that need to be protected against rescheduling

call <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-7CBBF72B-4519-38DD-92CA-38AF636AFD8A"><apiname>NKern::Lock()</apiname></xref>. Interrupt Service Routines (ISRs) can

still run but no other thread (or IDFC) can run until the kernel is unlocked

by a call to <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-A1A42137-906C-30F1-AF61-4F786FC372DE"><apiname>NKern::Unlock()</apiname></xref>. </p> <p>The pre-condition

means that the kernel lock must <i>NOT</i> be set when the described function

is called. </p> <p id="GUID-F80292D9-E3C8-5466-ABD3-0416CDE2BD00"><b>Kernel can be locked or

unlocked</b> </p> <p>Many kernel side functions run with interrupts enabled,

including code that manipulates global structures, such as the thread ready

list. To prevent such code from being reentered and potentially corrupting

the structure concerned, a lock known as the kernel lock (sometimes referred

to as the preemption lock) is used. </p> <p>Sections of code that need to

be protected against rescheduling call <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-7CBBF72B-4519-38DD-92CA-38AF636AFD8A"><apiname>NKern::Lock()</apiname></xref>. Interrupt

Service Routines (ISRs) can still run but no other thread (or IDFC) can run

until the kernel is unlocked by a call to <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-A1A42137-906C-30F1-AF61-4F786FC372DE"><apiname>NKern::Unlock()</apiname></xref>. </p> <p>The

pre-condition means that it does not matter whether the kernel lock is set

or unset when the described function is called. </p> <p id="GUID-EC063E55-66F7-52E9-AF47-F981B63E446E"><b>Kernel must be locked, with

lock count 1</b> </p> <p>Many kernel side functions run with interrupts enabled,

including code that manipulates global structures, such as the thread ready

list. To prevent such code from being reentered and potentially corrupting

the structure concerned, a lock known as the kernel lock (sometimes referred

to as the preemption lock) is used. </p> <p>Sections of code that need to

be protected against rescheduling call <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-7CBBF72B-4519-38DD-92CA-38AF636AFD8A"><apiname>NKern::Lock()</apiname></xref>. Interrupt

Service Routines (ISRs) can still run but no other thread (or IDFC) can run

until the kernel is unlocked by a call to <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-A1A42137-906C-30F1-AF61-4F786FC372DE"><apiname>NKern::Unlock()</apiname></xref>. </p> <p>In

addition, calls to <codeph>NKern::Lock()</codeph> and <codeph>NKern::Unlock()</codeph> are

counted. The count value is zero when the kernel is unlocked; a call to <codeph>NKern::Lock()</codeph> adds

one to the count value, and a call to <codeph>NKern::Unlock()</codeph> subtracts

one from the count value. </p> <p>The pre-condition means that there must

be exactly one call to <codeph>Kern::Lock()</codeph> that has not yet had

a matching call to <codeph>Kern::Unlock()</codeph>. </p> <p>See also <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita#GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953/GUID-76E5AE32-9A70-344A-9E6B-5B439622715A"><apiname>NFastMutex::Wait()</apiname></xref>. </p> <p id="GUID-A55086AA-382B-5F93-9CE0-42C6FB428A19"><b>Interrupts must be enabled</b> </p> <p>This

pre-condition states that interrupts must be enabled before calling the described

function. </p> <p>Possible reasons why interrupts may need to be enabled include: </p> <ul>

<li id="GUID-B3D25D93-BDBA-5CFB-98ED-78A4BEF95DF0"><p>the function needs interrupts

to occur; for example, it may wait for timer ticks. </p> </li>

<li id="GUID-1B806059-76C7-5C0F-ADAA-84134217C5A2"><p>the function may take

a long or potentially unbounded time to run, so interrupts need to be enabled

to guarantee bounded interrupt latency. </p> </li>

</ul> <p>See also the function <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-2D328082-3A9F-3467-81CF-B1C68866E163"><apiname>NKern::RestoreInterrupts()</apiname></xref> and

the associated function <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-CA1C36B7-02EE-31D5-B700-27DE4769ECCF"><apiname>NKern::DisableInterrupts()</apiname></xref>. </p> <p id="GUID-9384C08B-D56F-5284-BA4B-4CF6C85E06E4"><b>Interrupts must be disabled</b> </p> <p>This

pre-condition states that interrupts must be disabled before calling the described

function. </p> <p>See also the function <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-CA1C36B7-02EE-31D5-B700-27DE4769ECCF"><apiname>NKern::DisableInterrupts()</apiname></xref> and

the associated function <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-2D328082-3A9F-3467-81CF-B1C68866E163"><apiname>NKern::RestoreInterrupts()</apiname></xref>. </p> <p id="GUID-E1A36F24-AC68-58AF-B344-A59111F621FA"><b>Interrupts can either be

enabled or disabled</b> </p> <p>This pre-condition states that it does not

matter whether interrupts are enabled or disabled before calling the described

function. </p> <p id="GUID-1E584D23-5233-5A38-A629-FBFE834F8248"><b>System lock must be held</b> </p> <p>The

system lock is a specific fast mutex that only provides exclusion against

other threads acquiring the same fast mutex. Setting, and acquiring the system

lock means that a thread enters an implied critical section. </p> <p>The major

items protected by the system lock are: </p> <ul>

<li id="GUID-B5FDF231-881B-5F4C-9FC1-256647FA502A"><p> <codeph>DThread</codeph> member

data related to thread priority and status. </p> </li>

<li id="GUID-E583EC5A-3572-5E83-9B73-724B63853D52"><p>the consistency of the

memory map; on the kernel side, the state of user side memory or the mapping

of a process is not guaranteed unless (a) you are a thread belonging to the

process that owns the memory or (b) you hold the system lock. </p> </li>

<li id="GUID-B65EFDDA-6327-5F6C-91D5-F9C703E1B109"><p>the lifetime of <codeph>DObject</codeph> type

objects and references to them, including handle translation in Exec dispatch. </p> </li>

</ul> <p>Note that the system lock is different from the kernel lock; the

kernel lock protects against any rescheduling. When the system lock is set,

the calling thread can still be pre-empted, even in the locked section. </p> <p>The

system lock is set by a call to <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-B3837744-B8CC-3DC0-BA1D-417016E88EE9"><apiname>NKern::LockSystem()</apiname></xref>. </p> <p>The

pre-condition means that the system lock must be set before calling the described

function. </p> <p id="GUID-74F93316-0DAC-5F4F-A307-C0C15B14E794"><b>System lock must not be

held</b> </p> <p>See the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-1E584D23-5233-5A38-A629-FBFE834F8248">System

lock must be held</xref> for a brief description of the system lock. </p> <p>The

system lock is unset by a call to <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-63B882C8-C5D0-3595-BBF1-74E942A5060A"><apiname>NKern::UnlockSystem()</apiname></xref>. </p> <p>The

pre-condition means that the system lock must not be set before calling the

described function. </p> <p id="GUID-BA42435C-85B9-5A86-B875-50FE69B99B48"><b>Call in a thread context</b> </p> <p>This

pre-condition means that the described function must be called directly, or

indirectly, from a DFC or a thread. The thread can be a user thread or a kernel

thread. </p> <p id="GUID-3FE5AA98-FD6C-528D-9DF2-7C50BE7FEF8E"><b>Call in an IDFC contex</b> </p> <p>This

pre-condition means that the described function must be called directly, or

indirectly, from an IDFC. </p> <p>Note that when calling a function from an

IDFC: </p> <ul>

<li id="GUID-2935ED8F-A340-5718-944C-56B2A8404D95"><p>the kernel is locked,

so pre-emption is disabled </p> </li>

<li id="GUID-ECCD22D2-9504-57EA-9245-5BD071B84694"><p>user memory cannot be

accessed </p> </li>

<li id="GUID-35C14F6F-EAFF-549A-BA2B-7EF5F2B6D093"><p>the function cannot

block or wait. </p> </li>

</ul> <p id="GUID-6957D624-5176-591C-A667-4DF78B29F271"><b>Call either in a thread

or an IDFC context</b> </p> <p>This pre-condition means that the described

function can be called directly, or indirectly, from an IDFC, a DFC or a thread.

The thread can be a user thread or a kernel thread. </p> <p>Note that when

calling a function from an IDFC: </p> <ul>

<li id="GUID-7B6B2A5B-D282-529E-9D6B-7B1E2EC0BE0F"><p>the kernel is locked,

so pre-emption is disabled </p> </li>

<li id="GUID-BDEA9088-1340-59C9-B94F-848AF530F55A"><p>user memory cannot be

accessed </p> </li>

<li id="GUID-2073105B-FFE9-57C0-AB9D-3D3459BCED16"><p>the function cannot

block or wait. </p> </li>

</ul> <p id="GUID-A45A1D39-8C76-5E14-8DCF-FCE0A26758CE"><b>Call in any context</b> </p> <p>This

pre-condition means that the described function can be called directly, or

indirectly, from an IDFC, a DFC or a thread, or it can be called from an Interrupt

Service Routine (ISR). </p> <p>A thread can be a user thread or a kernel thread. </p> <p>Note

that when calling a function from an IDFC: </p> <ul>

<li id="GUID-4E80B3B7-BBBC-51F5-AC6D-996240416B29"><p>the kernel is locked,

so pre-emption is disabled </p> </li>

<li id="GUID-BCF8F1AA-2F70-54BC-9FB6-C5EDD9057C79"><p>user memory cannot be

accessed </p> </li>

<li id="GUID-A7B6B42D-0FDB-589E-860B-F2D1D8892BC7"><p>the function cannot

block or wait. </p> </li>

</ul> <p id="GUID-0DCAE842-45E1-5F5F-BC68-121775D0B702"><b>Do not call from an ISR</b> </p> <p>This

pre-condition means that the described function must not be called from an

Interrupt Service Routine (ISR). </p> <p>Note that ISRs have the following

characteristics: </p> <ul>

<li id="GUID-D773586B-422C-5B03-8588-1A24058A5DD1"><p>they have an unknown

context </p> </li>

<li id="GUID-3BACC342-0768-5D2F-BE53-58C33B74C392"><p>they must not allocate

or free memory </p> </li>

<li id="GUID-DE919B78-9516-5F3D-98B2-3A99D8C3EE15"><p>they cannot access user

memory </p> </li>

<li id="GUID-04AFFA6E-C742-5068-81B7-AFEA47422763"><p>they must not call functions

that interfere with critical sections of code. </p> </li>

</ul> <p id="GUID-F17D0FE5-BA42-575B-8971-C5B034CF404E"><b>The calling thread must

own the semaphore</b> </p> <p>A semaphore can be waited on only by the thread

that owns it. This precondition is needed when the described function calls

a semaphore wait function. </p> <p id="GUID-8D9D08F5-0CBD-52BB-B416-636516982D47"><b>The calling thread must

not be explicitly suspended</b> </p> <p>This refers to nanokernel threads,

not Symbian platform threads. The described function must not be used if the

thread is in the suspended state. One of the possible reasons for this is

that the described function does not check the thread's suspend count. </p> <p>A

thread may be created suspended, or the thread may be put into a suspended

state using <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-FF94D458-C2D0-3D20-ADD6-AAE68A3296C3"><apiname>NThreadBase::Suspend()</apiname></xref>. If you don't know whether

or not the thread is suspended, use <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-82E43D79-721D-31A9-B9ED-1277F2300914"><apiname>NThreadBase::CheckSuspendThenReady()</apiname></xref>. </p> <p>See

also <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-C0A6E734-7DE6-37B9-AAB2-A2A0E2664731"><apiname>NThreadBase::Resume()</apiname></xref> and <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-BE92FBC3-A7D9-3576-A1A9-7BBA6EE64226"><apiname>NThreadBase::ForceResume()</apiname></xref>. </p> <p> <i>Note

that these functions are for use only in an RTOS personality layer.</i>  </p> <p id="GUID-910660F9-F30F-5725-981D-52F65F7FDB81"><b>The calling thread must

hold the mutex</b> </p> <p>The calling thread has waited for a mutex and acquired

it. This precondition is needed when the thread is about to release the mutex,

ie call one of the <codeph>Signal()</codeph> functions. </p> <p id="GUID-DDEB4D47-04F5-5736-A8BE-3F1AC543F9D7"><b>Call only from ISR, IDFC

or thread with the kernel locked</b> </p> <p>See the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-B6943D58-99B9-5A4B-A1DD-577B6197F274">Kernel must be locked</xref>. </p> <p id="GUID-3D8578BC-86EE-5E64-9C1E-CCD512A344D1"><b>Call only from IDFC or thread

with the kernel locked</b> </p> <p>See the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-B6943D58-99B9-5A4B-A1DD-577B6197F274">Kernel must be locked</xref>. </p> <p id="GUID-2147A0B6-365A-5AC3-8EBE-AC0D89ED0C70"><b>Do not call from thread

with the kernel unlocked</b> </p> <p>See the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-8027AB9A-858F-5945-A75B-E817AD76DEC3">Kernel must be unlocked</xref>. </p> <p id="GUID-7E26E475-5D7E-5C68-B3A4-BC9EC6D29D98"><b>Do not call from ISR or

thread with the kernel unlocked</b> </p> <p>See the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-8027AB9A-858F-5945-A75B-E817AD76DEC3">Kernel must be unlocked</xref>. </p> <p id="GUID-6C17250C-4FD0-5A2E-B448-BC08504F4FE4"><b>Thread must not already

be exiting</b> </p> <p>The pre-condition means that the described function

should not be called after the thread has been killed. </p> <p>In EKA2, threads

do not die immediately, they are placed on a queue to be deleted later. </p> <p>Functions

with this pre-condition are not likely to used in a device driver. </p> <p id="GUID-021E54DB-7F22-5ADB-A80D-CAFBB08596A2"><b>Property has not been opened</b> </p> <p>A

property is a single value used by “Publish and Subscribe”. Each property

must be opened before it can be used. To open a property, use either <xref href="GUID-39D6B924-3FA3-39E6-A6EA-88E2D1927AC2.dita#GUID-39D6B924-3FA3-39E6-A6EA-88E2D1927AC2/GUID-DBEDDC3A-AE6F-3CAF-B251-4AA556EAF21C"><apiname>RPropertyRef::Attach()</apiname></xref> or <xref href="GUID-39D6B924-3FA3-39E6-A6EA-88E2D1927AC2.dita#GUID-39D6B924-3FA3-39E6-A6EA-88E2D1927AC2/GUID-6F8EB0AB-C01A-3BFD-B334-D9C9FB923865"><apiname>RPropertyRef::Open()</apiname></xref>. Once opened, the property cannot be opened again. </p> <p>The pre-condition

means that the property must <i>NOT</i> already be open when the described

function is called. </p> <p id="GUID-D924E37C-300A-58FF-890B-F1FA5349FA05"><b>Property has been opened</b> </p> <p>A

property is a single value used by “Publish and Subscribe”. Each property

must be opened before it can be used. To open a property, use either <xref href="GUID-39D6B924-3FA3-39E6-A6EA-88E2D1927AC2.dita#GUID-39D6B924-3FA3-39E6-A6EA-88E2D1927AC2/GUID-DBEDDC3A-AE6F-3CAF-B251-4AA556EAF21C"><apiname>RPropertyRef::Attach()</apiname></xref> or <xref href="GUID-39D6B924-3FA3-39E6-A6EA-88E2D1927AC2.dita#GUID-39D6B924-3FA3-39E6-A6EA-88E2D1927AC2/GUID-6F8EB0AB-C01A-3BFD-B334-D9C9FB923865"><apiname>RPropertyRef::Open()</apiname></xref>. Once opened, the property cannot be opened again. </p> <p>The pre-condition

means that the property must already be open before calling the described

function. </p> <p id="GUID-F1485BCB-8384-518B-AE5B-F8387DF0C8F4"><b>Must be called under an

XTRAP harness or calling thread must not be in a critical section</b> </p> <p>Each

Symbian platform thread can be associated with a kernel-side

exception handler, set using XTRAP(); for example, to detect bad memory accesses. </p> <p>The

described function can legitimately cause an exception, and the pre-condition

means that </p> <p> <i>either</i>: </p> <ul>

<li id="GUID-485A8370-E3D5-5E67-9136-3150EC050DF0"><p>the described function

should be called inside an XTRAP() harness to catch the exception </p> </li>

</ul> <p> <i>or</i>  </p> <ul>

<li id="GUID-BDF6FFE8-E447-5E3D-A809-364A0A515C33"><p>the thread must not

be in a critical section, because exceptions are not allowed inside them.

If a thread takes an exception while inside a critical section, this is treated

as fatal to the system, and causes a <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-45337A03-5893-3D0D-948C-23BDCF8AECBD"><apiname>Kern::Fault()</apiname></xref>. </p> </li>

</ul> <p id="GUID-4D6B9502-0F88-5E0E-8E92-5783FE76555A"><b>DObject::Lock fast mutex

held</b> </p> <p>The described function accesses an object whose internal

data needs to be protected by the specified fast mutex. </p> <p>The operations

of: </p> <ul>

<li id="GUID-B358DA23-F140-5F08-878F-69455A83A729"><p>obtaining an object’s

name </p> </li>

<li id="GUID-3838D839-5210-5FB7-AF0C-3F3C299AA7B8"><p>setting an object's

name </p> </li>

<li id="GUID-2AD3BEC1-E934-513B-BAED-3FF164161F2D"><p>setting an object's

owner </p> </li>

</ul> <p>are all protected by the global fast mutex, <codeph>DObject::Lock</codeph>.

This is done to avoid inconsistent results caused by, for example, one thread

renaming an object while another is reading its name or full name. </p> <p>Setting

the owner is protected as the owner's name is part of the object's full name. </p> <p id="GUID-D6BB3BE3-E0DD-50B9-B9D1-275E51CE7FC6"><b>DCodeSeg::CodeSegLock mutex

held</b> </p> <p>The <codeph>DCodeSeg::CodeSegLock</codeph> mutex protects

the global code graph from simultaneous accesses. Wait on this mutex before

calling the described function, e.g. by calling <codeph>DCodeSeg::Wait()</codeph>. </p> <p id="GUID-9A82D0DD-7599-5511-AD9E-2930ADC99AC0"><b>Any kind of lock can be

held</b> </p> <p>The described function can be called with any kind of lock. </p> <p id="GUID-F9800056-B5E5-576D-B440-544AE067D4DC"><b>Call only from Init1() in

base port</b> </p> <p>The pre-condition means that the described function

can only be called during the first phase of kernel initialisation, i.e. during

execution of the Base Port implementation of <codeph>Asic::Init1()</codeph>.

See the <xref href="GUID-DEB51862-A72B-5FB7-B1BA-F34685E71BFF.dita">Board Support

Packages Quick Start</xref>. </p> <p>This condition may apply because the

described function: </p> <ul>

<li id="GUID-62621625-D712-5F4C-B31D-067E5887D8FD"><p>must be called before

any context switch </p> </li>

<li id="GUID-FB33B022-A388-5508-9C98-33518154BBBA"><p>must be called before

the MMU is turned on. </p> </li>

</ul> <p id="GUID-6122C9C6-05EB-508C-8C9A-45B6A8DAB42C"><b>The various parameters must

be valid. The PIL or PSL will fault the kernel if not</b> </p> <p>This pre-condition

refers to a DMA request. </p> <p>The parameters used when calling the described

function must be as specified. If they are not, the platform independent layer

or the platform specific layer cannot recover and will cause the kernel to

fault, i.e. the device will reset. </p> <p id="GUID-041025B4-95B9-5493-ACC3-649B6683DE0D"><b>The request is not being

transferred or pending</b> </p> <p>This pre-condition refers to a DMA request. </p> <p>The

described function must not be called if a DMA request has already been set

up, or is in progress. A possible reason for this is that the described function

resets parameters that have been already setup. </p> <p id="GUID-582E833B-C0E9-5986-86C5-24BF15648D61"><b>Wait on TimerMutex before

calling this</b> </p> <p>The <codeph>TimerMutex</codeph> mutex protects the

timer queues. Wait and signal operations on the timer mutex are accomplished

with the static functions <xref href="GUID-68509286-C337-3ED1-9162-31507CC564E1.dita#GUID-68509286-C337-3ED1-9162-31507CC564E1/GUID-7E855355-3AC7-3449-B501-C387C4CBA3B9"><apiname>TTickQ::Wait()</apiname></xref> and <xref href="GUID-68509286-C337-3ED1-9162-31507CC564E1.dita#GUID-68509286-C337-3ED1-9162-31507CC564E1/GUID-36F604B8-EBE6-3ED1-B969-F2C4F0975036"><apiname>TTickQ::Signal()</apiname></xref>.

This precondition is necessary when the described function manipulates the

timer queue. </p> <p id="GUID-98CBADF3-8CD3-54BC-8CB7-C2BD8D48289A"><b>Message must be in ACCEPTED

state</b> </p> <p>This pre-condition indicates that the message has been read

by the receiving thread. It is not attached to a message queue but is currently

in use by the receiving thread. </p> <p id="GUID-B9E940EF-0EC8-5EEB-B29B-B402BFF09350"><b>Queue must not be in asynchronous

receive mode</b> </p> <p>This pre-condition refers to kernel side message

queues. A kernel thread can receive messages: </p> <ul>

<li id="GUID-4C36A2DD-3E27-507E-BB18-143AF8B210A2"><p>asynchronously by calling <xref href="GUID-382DD935-E9D7-3E00-88B2-B28A89CAD4FB.dita#GUID-382DD935-E9D7-3E00-88B2-B28A89CAD4FB/GUID-EF06556E-9EC6-3D1C-AEE9-0CDDF6B42A24"><apiname>TMessageQue::Receive()</apiname></xref>  </p> </li>

<li id="GUID-BF8FB0AB-CA7F-5A02-BE61-43AECE226113"><p>by polling, by calling <xref href="GUID-D14B3E02-A9A4-37F8-9638-26C12BF5AFA8.dita#GUID-D14B3E02-A9A4-37F8-9638-26C12BF5AFA8/GUID-D2B157FB-FA55-3F27-A463-691B3B6C5570"><apiname>MessageQue::Poll()</apiname></xref>  </p> </li>

</ul> <p>A possible reason for this precondition is that the queue is about

to be polled. </p> <p>The queue may be polled either: </p> <ul>

<li id="GUID-FD59C03B-1B65-52F6-A1C6-177D48D4CFC2"><p>before the first <codeph>Receive()</codeph> is

issued </p> </li>

<li id="GUID-7551CDCD-67B1-5A1A-B1AA-5F95CF63EBD4"><p>while processing a message

but before <codeph>Receive()</codeph> is called again </p> </li>

</ul> <p id="GUID-52D720FB-7F57-5340-8C34-F39FE1E50C36"><b>Container mutex must be

held / Thread container mutex must be held / Process container mutex must

be held</b> </p> <p>Each of the containers is protected by a mutex. </p> <p>The

pre-condition means that the calling thread must acquire the relevant mutex

before calling the described function. Object containers are <xref href="GUID-7FB9067F-D200-382C-84F7-49F0548D0A7F.dita"><apiname>DObjectCon</apiname></xref> types,

and the relevant mutexes are acquired and freed by calling <codeph>Wait()</codeph> and <codeph>Signal()</codeph> on

the container object. </p> </section>

<section id="GUID-F2DE76D5-0970-584F-9526-52E85932ACE8"><title>Post-conditions</title> <p>A

post condition describes what is true on return from a kernel API function. </p> <ul>

<li id="GUID-018783B2-3BA2-5046-B9EA-7F2CF1485839"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-BCA4F419-3306-5AB4-AA78-451FDA60BB22">Calling thread is in a critical section</xref>  </p> </li>

<li id="GUID-DCB3FFD2-054D-5F14-B846-FE5A00E13756"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-24DFFB87-639C-5D68-BCA0-D78AE870C485">Calling thread is not in a critical section</xref>  </p> </li>

<li id="GUID-8E6C6BCD-C1A5-5433-A0D9-A86962A47A1F"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-47393215-B2A5-5426-A0B6-CDB617218B7D">No fast mutex is held</xref>  </p> </li>

<li id="GUID-3A44F461-F5D6-5E50-9951-4DD97396602B"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-ECEA91E4-EB90-57AE-997E-4C8A95C3C337">Kernel is locked</xref>  </p> </li>

<li id="GUID-DE72541B-3AE6-5F23-A431-8CBDFB92BB81"><p><xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-7A7AC948-D84D-5581-80CE-328F1C6DA89E">Kernel is unlocked</xref></p> </li>

<li id="GUID-CFA7FF52-E930-5074-BABF-5F1148FA9513"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-B7FAE304-FF14-5A43-9ECB-DAD6F33DFDEE">Kernel is locked, with lock count 1</xref>  </p> </li>

<li id="GUID-208AEF9F-3BF5-59B9-A090-9B53BD4A72F1"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-B811C561-CAB3-5B91-9C31-38A228734F46">Interrupts are enabled</xref>  </p> </li>

<li id="GUID-CD794794-94D9-53B8-A96B-C78D6EE274D5"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-298793D0-D6E0-5FE3-84DF-FE0057E83B31">Interrupts are disabled</xref>  </p> </li>

<li id="GUID-1588AEB8-3B08-5659-8B93-DB0F60F038B2"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-236D2CCB-1A32-5B30-A28D-96A9416A62A1">System lock is held</xref>  </p> </li>

<li id="GUID-36D4EC99-5BA4-5510-B15C-DB37BC19D26C"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-53E54EE1-92BF-5E68-8FE4-43EB0AC84F8B">The calling thread holds the mutex</xref>  </p> </li>

<li id="GUID-FF5097D1-680A-578F-A67A-031151D1BE7A"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-C293EDE0-B326-54A2-AB4F-17E9158B67AC">Container mutex is held</xref>  </p> </li>

<li id="GUID-BA3DFAFE-8CAF-567D-B9D3-144DA8AABBAE"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-C293EDE0-B326-54A2-AB4F-17E9158B67AC">Thread container mutex is held</xref>  </p> </li>

<li id="GUID-343FA4B5-9217-5152-BD23-E3BCDACD7E56"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-C293EDE0-B326-54A2-AB4F-17E9158B67AC">Process container mutex is held</xref>  </p> </li>

<li id="GUID-1514A5FA-1B49-5C4A-BC47-36D008282C8D"><p> <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-A5EED271-3A9C-5373-BC84-66546DE4DDD9">DCodeSeg::CodeSegLock mutex held</xref>  </p> </li>

</ul> <p id="GUID-BCA4F419-3306-5AB4-AA78-451FDA60BB22"><b>Calling thread is in a critical

section</b> </p> <p>The code is in a critical section on return from the function. </p> <p>See

also the pre-condition: <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-B0F8E686-A86D-5A99-8560-7D591CE84BD0">Calling

thread must be in a critical section</xref>. </p> <p id="GUID-24DFFB87-639C-5D68-BCA0-D78AE870C485"><b>Calling thread is not in

a critical section</b> </p> <p>The code is <i>NOT</i> in a critical section

on return from the function. </p> <p>See also the pre-condition: <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-3EE55520-0F0D-508B-A384-55082ED10D72">Calling thread must not be in a critical section</xref>. </p> <p id="GUID-47393215-B2A5-5426-A0B6-CDB617218B7D"><b>No fast mutex is held</b> </p> <p>A

thread can hold no more than one fast mutex at any given time. A fast mutex

is <i>NOT</i> held on exit from the function. </p> <p id="GUID-ECEA91E4-EB90-57AE-997E-4C8A95C3C337"><b>Kernel is locked</b> </p> <p>The

post-condition means that, on exit from the described function, the kernel

lock is on. The described function might have explicitly set the kernel lock

or, more commonly, the lock was set before entry to the described function,

and has not been unset by that function. </p> <p>See also the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-B6943D58-99B9-5A4B-A1DD-577B6197F274">Kernel

must be locked</xref>. </p> <p id="GUID-7A7AC948-D84D-5581-80CE-328F1C6DA89E"><b>Kernel is unlocked</b> </p> <p>The

kernel is <i>NOT</i> locked on exit from the described function. The described

function might have explicitly unset the kernel lock or, more commonly, the

lock was not set before entry to the described function, and has not been

set by that function. </p> <p>See also the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-8027AB9A-858F-5945-A75B-E817AD76DEC3">Kernel must be unlocked</xref>. </p> <p id="GUID-B7FAE304-FF14-5A43-9ECB-DAD6F33DFDEE"><b>Kernel is locked, with lock

count 1</b> </p> <p>See the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-EC063E55-66F7-52E9-AF47-F981B63E446E">Kernel

must be locked, with lock count 1</xref>. </p> <p id="GUID-B811C561-CAB3-5B91-9C31-38A228734F46"><b>Interrupts are enabled</b> </p> <p>This

post-condition states that interrupts are enabled on return from the described

function. </p> <p>See the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-A55086AA-382B-5F93-9CE0-42C6FB428A19">Interrupts

must be enabled</xref>  </p> <p id="GUID-298793D0-D6E0-5FE3-84DF-FE0057E83B31"><b>Interrupts are disabled</b> </p> <p>This

post-condition states that interrupts are disabled on return from the described

function. </p> <p>See the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-9384C08B-D56F-5284-BA4B-4CF6C85E06E4">Interrupts

must be disabled</xref>  </p> <p id="GUID-236D2CCB-1A32-5B30-A28D-96A9416A62A1"><b>System lock is held</b> </p> <p>This

post-condition states that the system lock is held on return from the described

function. </p> <p>The system lock is a specific fast mutex that only provides

exclusion against other threads acquiring the same fast mutex. Setting, and

acquiring the system lock means that a thread enters an implied critical section. </p> <p>The

major items protected by the system lock are: </p> <ul>

<li id="GUID-63E77673-0405-5E59-8102-67454FF96D1C"><p> <codeph>DThread</codeph> member

data related to thread priority and status. </p> </li>

<li id="GUID-3A37E1EF-89CF-50DA-B4B4-174A3B307873"><p>the consistency of the

memory map; on the kernel side, the state of user side memory or the mapping

of a process is not guaranteed unless (a) you are a thread belonging to the

process that owns the memory or (b) you hold the system lock. </p> </li>

<li id="GUID-D25EE56D-2FF5-515A-B826-08331B16C72E"><p>the lifetime of <codeph>DObject</codeph> type

objects and references to them, including handle translation in Exec dispatch. </p> </li>

</ul> <p><note> System lock is different from the kernel lock; the kernel

lock protects against any rescheduling. When the system lock is set, the calling

thread can still be pre-empted, even in the locked section.</note> </p> <p>The

system lock is set by a call to <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-B3837744-B8CC-3DC0-BA1D-417016E88EE9"><apiname>NKern::LockSystem()</apiname></xref>, and

unset by call to <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-63B882C8-C5D0-3595-BBF1-74E942A5060A"><apiname>NKern::UnlockSystem()</apiname></xref>. </p> <p id="GUID-53E54EE1-92BF-5E68-8FE4-43EB0AC84F8B"><b>The calling thread holds

the mutex</b> </p> <p>The calling thread has waited for a mutex and acquired

it. On return from the described function, the thread still holds the mutex. </p> <p>See

also the pre-condition <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-910660F9-F30F-5725-981D-52F65F7FDB81">The

calling thread must hold the mutex</xref>. </p> <p id="GUID-C293EDE0-B326-54A2-AB4F-17E9158B67AC"><b>Container mutex is held

/ Thread container mutex is held / Process container mutex is held</b> </p> <p>Each

of the containers is protected by a mutex. </p> <p>The post-condition means

that the calling thread has the relevant mutex on return from the described

function. This is most likely because the mutex was acquired before entering

the described function. </p> <p>Object containers are <xref href="GUID-7FB9067F-D200-382C-84F7-49F0548D0A7F.dita"><apiname>DObjectCon</apiname></xref> types,

and the relevant mutexes are acquired and freed by calling <codeph>Wait()</codeph> and <codeph>Signal()</codeph> on

the container object. </p> <p id="GUID-A5EED271-3A9C-5373-BC84-66546DE4DDD9"><b>DCodeSeg::CodeSegLock mutex

held</b> </p> <p>The <codeph>DCodeSeg::CodeSegLock</codeph> mutex protects

the global code graph from simultaneous accesses. </p> <p>This post condition

means that the mutex is held on exit. The most common situation is that the

mutex was acquired before entry to the described function. Relinquish the

mutex by calling <codeph>DCodeSeg::Signal()</codeph>. </p> </section>

</conbody></concept>