<?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>