|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8" xml:lang="en"><title>Pre-Conditions |
|
13 and Post-Conditions for Kernel APIs</title><shortdesc>Reference documentation for kernel side function APIs, specifies |
|
14 a wide variety of pre-conditions and post-conditions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <ul> |
|
16 <li id="GUID-C8EAD446-F9B7-50A3-8A7C-FA45487287BA"><p>A <i>pre-condition</i> is |
|
17 something that must be true before using the function. </p> </li> |
|
18 <li id="GUID-0360AD60-7A36-5949-AFF8-6649619F9F6A"><p>A <i>post-condition</i> is |
|
19 something that is true on return from the function. </p> </li> |
|
20 </ul> |
|
21 <p>Such conditions are expressed using a standard phrase, wherever possible, |
|
22 and this section explains what those conditions mean. </p> |
|
23 <p>Where more than one pre-condition is stated for a given function, then |
|
24 you can assume that all pre-conditions apply. In this sense, there is an implied |
|
25 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>, |
|
26 the following pre-conditions apply: </p> |
|
27 <codeblock id="GUID-A81563CA-D72C-5B9F-820E-1AA1623E75F7" xml:space="preserve">No fast mutex can be held. |
|
28 Call in a thread context.</codeblock> |
|
29 <p>Both conditions must be true before calling the functions. </p> |
|
30 <p>There are exceptions to this rule, where a precondition applies only if |
|
31 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>, |
|
32 you will find the following pre-conditions: </p> |
|
33 <codeblock id="GUID-3BC88AB3-DBCD-5F4A-9E5E-14B5C711F604" xml:space="preserve">Call either in a thread or an IDFC context, if aLock=TRUE |
|
34 Call in any context, if aLock=FALSE.</codeblock> |
|
35 <p>Clearly, only one pre-condition will apply, depending on the supplied value |
|
36 of the <codeph>aLock</codeph> argument. </p> |
|
37 <p>A few conditions are self-explanatory, and these are not included in these |
|
38 lists. </p> |
|
39 <p>NOTE that some familiarity with kernel side programming is assumed. </p> |
|
40 <ul> |
|
41 <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> |
|
42 <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> |
|
43 </ul> |
|
44 <section id="GUID-5F986149-D75B-5B3F-92F3-7B4FB89F4718"><title>Pre-conditions</title> <p>This |
|
45 describes the meaning of each precondition, and tries to provide insight as |
|
46 to why it needs to be satisfied, and explains what you need to do to ensure |
|
47 that the preconditions are met. </p> <ul> |
|
48 <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> |
|
49 <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> |
|
50 <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> |
|
51 <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> |
|
52 <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> |
|
53 <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> |
|
54 <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> |
|
55 <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> |
|
56 <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> |
|
57 <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> |
|
58 <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> |
|
59 <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> |
|
60 <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> |
|
61 <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> |
|
62 <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> |
|
63 <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> |
|
64 <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> |
|
65 <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> |
|
66 <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> |
|
67 <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> |
|
68 <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> |
|
69 <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> |
|
70 <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> |
|
71 <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> |
|
72 <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> |
|
73 <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> |
|
74 <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> |
|
75 <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> |
|
76 <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 |
|
77 critical section</xref> </p> </li> |
|
78 <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> |
|
79 <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> |
|
80 <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> |
|
81 <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> |
|
82 <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 |
|
83 if not</xref> </p> </li> |
|
84 <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> |
|
85 <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> |
|
86 <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> |
|
87 <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> |
|
88 <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> |
|
89 <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> |
|
90 <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> |
|
91 </ul> <p id="GUID-B0F8E686-A86D-5A99-8560-7D591CE84BD0"><b>Calling thread must be in |
|
92 a critical section</b> </p> <p>Critical sections are sections of code that |
|
93 leave the kernel in a compromised state if they cannot complete. A thread |
|
94 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 |
|
95 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 |
|
96 in a critical section, the thread cannot be suspended or killed. These actions |
|
97 are deferred until the end of the critical section. If a thread takes an exception |
|
98 while inside a critical section, this is treated as fatal to the system, and |
|
99 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 |
|
100 be in a critical section when called. </p> <p id="GUID-3EE55520-0F0D-508B-A384-55082ED10D72"><b>Calling thread must not |
|
101 be in a critical section</b> </p> <p>Critical sections are sections of code |
|
102 that leave the kernel in a compromised state if they cannot complete. A thread |
|
103 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 |
|
104 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 |
|
105 in a critical section, the thread cannot be suspended or killed. These actions |
|
106 are deferred until the end of the critical section. If a thread takes an exception |
|
107 while inside a critical section, this is treated as fatal to the system, and |
|
108 cause a <codeph>Kern::Fault()</codeph>. </p> <p>There are some functions winthin |
|
109 the system that must <i>NOT</i> be in a critical section when called. This |
|
110 applies to the described functions. </p> <p id="GUID-09CB97CE-8DAF-58FA-B240-5B396ABC9614"><b>Calling thread can either |
|
111 be in a critical section or not</b> </p> <p>Critical sections are sections |
|
112 of code that leave the kernel in a compromised state if they cannot complete. |
|
113 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 |
|
114 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 |
|
115 in a critical section, the thread cannot be suspended or killed. These actions |
|
116 are deferred until the end of the critical section. If a thread takes an exception |
|
117 while inside a critical section, this is treated as fatal to the system, and |
|
118 cause a <codeph>Kern::Fault()</codeph>. </p> <p>When this pre-condition applies |
|
119 to the described function, it means that it does not matter whether the code |
|
120 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 |
|
121 thread can hold no more than one fast mutex at any given time. The described |
|
122 function uses a fast mutex, which means that on entry to the function, the |
|
123 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 |
|
124 kernel side functions run with interrupts enabled, including code that manipulates |
|
125 global structures, such as the thread ready list. To prevent such code from |
|
126 being reentered and potentially corrupting the structure concerned, a lock |
|
127 known as the kernel lock (sometimes referred to as the preemption lock) is |
|
128 used. </p> <p>Sections of code that need to be protected against rescheduling |
|
129 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 |
|
130 still run but no other thread (or IDFC) can run until the kernel is unlocked |
|
131 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 |
|
132 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 |
|
133 kernel side functions run with interrupts enabled, including code that manipulates |
|
134 global structures, such as the thread ready list. To prevent such code from |
|
135 being reentered and potentially corrupting the structure concerned, a lock |
|
136 known as the kernel lock (sometimes referred to as the preemption lock) is |
|
137 used. </p> <p>Sections of code that need to be protected against rescheduling |
|
138 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 |
|
139 still run but no other thread (or IDFC) can run until the kernel is unlocked |
|
140 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 |
|
141 means that the kernel lock must <i>NOT</i> be set when the described function |
|
142 is called. </p> <p id="GUID-F80292D9-E3C8-5466-ABD3-0416CDE2BD00"><b>Kernel can be locked or |
|
143 unlocked</b> </p> <p>Many kernel side functions run with interrupts enabled, |
|
144 including code that manipulates global structures, such as the thread ready |
|
145 list. To prevent such code from being reentered and potentially corrupting |
|
146 the structure concerned, a lock known as the kernel lock (sometimes referred |
|
147 to as the preemption lock) is used. </p> <p>Sections of code that need to |
|
148 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 |
|
149 Service Routines (ISRs) can still run but no other thread (or IDFC) can run |
|
150 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 |
|
151 pre-condition means that it does not matter whether the kernel lock is set |
|
152 or unset when the described function is called. </p> <p id="GUID-EC063E55-66F7-52E9-AF47-F981B63E446E"><b>Kernel must be locked, with |
|
153 lock count 1</b> </p> <p>Many kernel side functions run with interrupts enabled, |
|
154 including code that manipulates global structures, such as the thread ready |
|
155 list. To prevent such code from being reentered and potentially corrupting |
|
156 the structure concerned, a lock known as the kernel lock (sometimes referred |
|
157 to as the preemption lock) is used. </p> <p>Sections of code that need to |
|
158 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 |
|
159 Service Routines (ISRs) can still run but no other thread (or IDFC) can run |
|
160 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 |
|
161 addition, calls to <codeph>NKern::Lock()</codeph> and <codeph>NKern::Unlock()</codeph> are |
|
162 counted. The count value is zero when the kernel is unlocked; a call to <codeph>NKern::Lock()</codeph> adds |
|
163 one to the count value, and a call to <codeph>NKern::Unlock()</codeph> subtracts |
|
164 one from the count value. </p> <p>The pre-condition means that there must |
|
165 be exactly one call to <codeph>Kern::Lock()</codeph> that has not yet had |
|
166 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 |
|
167 pre-condition states that interrupts must be enabled before calling the described |
|
168 function. </p> <p>Possible reasons why interrupts may need to be enabled include: </p> <ul> |
|
169 <li id="GUID-B3D25D93-BDBA-5CFB-98ED-78A4BEF95DF0"><p>the function needs interrupts |
|
170 to occur; for example, it may wait for timer ticks. </p> </li> |
|
171 <li id="GUID-1B806059-76C7-5C0F-ADAA-84134217C5A2"><p>the function may take |
|
172 a long or potentially unbounded time to run, so interrupts need to be enabled |
|
173 to guarantee bounded interrupt latency. </p> </li> |
|
174 </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 |
|
175 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 |
|
176 pre-condition states that interrupts must be disabled before calling the described |
|
177 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 |
|
178 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 |
|
179 enabled or disabled</b> </p> <p>This pre-condition states that it does not |
|
180 matter whether interrupts are enabled or disabled before calling the described |
|
181 function. </p> <p id="GUID-1E584D23-5233-5A38-A629-FBFE834F8248"><b>System lock must be held</b> </p> <p>The |
|
182 system lock is a specific fast mutex that only provides exclusion against |
|
183 other threads acquiring the same fast mutex. Setting, and acquiring the system |
|
184 lock means that a thread enters an implied critical section. </p> <p>The major |
|
185 items protected by the system lock are: </p> <ul> |
|
186 <li id="GUID-B5FDF231-881B-5F4C-9FC1-256647FA502A"><p> <codeph>DThread</codeph> member |
|
187 data related to thread priority and status. </p> </li> |
|
188 <li id="GUID-E583EC5A-3572-5E83-9B73-724B63853D52"><p>the consistency of the |
|
189 memory map; on the kernel side, the state of user side memory or the mapping |
|
190 of a process is not guaranteed unless (a) you are a thread belonging to the |
|
191 process that owns the memory or (b) you hold the system lock. </p> </li> |
|
192 <li id="GUID-B65EFDDA-6327-5F6C-91D5-F9C703E1B109"><p>the lifetime of <codeph>DObject</codeph> type |
|
193 objects and references to them, including handle translation in Exec dispatch. </p> </li> |
|
194 </ul> <p>Note that the system lock is different from the kernel lock; the |
|
195 kernel lock protects against any rescheduling. When the system lock is set, |
|
196 the calling thread can still be pre-empted, even in the locked section. </p> <p>The |
|
197 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 |
|
198 pre-condition means that the system lock must be set before calling the described |
|
199 function. </p> <p id="GUID-74F93316-0DAC-5F4F-A307-C0C15B14E794"><b>System lock must not be |
|
200 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 |
|
201 lock must be held</xref> for a brief description of the system lock. </p> <p>The |
|
202 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 |
|
203 pre-condition means that the system lock must not be set before calling the |
|
204 described function. </p> <p id="GUID-BA42435C-85B9-5A86-B875-50FE69B99B48"><b>Call in a thread context</b> </p> <p>This |
|
205 pre-condition means that the described function must be called directly, or |
|
206 indirectly, from a DFC or a thread. The thread can be a user thread or a kernel |
|
207 thread. </p> <p id="GUID-3FE5AA98-FD6C-528D-9DF2-7C50BE7FEF8E"><b>Call in an IDFC contex</b> </p> <p>This |
|
208 pre-condition means that the described function must be called directly, or |
|
209 indirectly, from an IDFC. </p> <p>Note that when calling a function from an |
|
210 IDFC: </p> <ul> |
|
211 <li id="GUID-2935ED8F-A340-5718-944C-56B2A8404D95"><p>the kernel is locked, |
|
212 so pre-emption is disabled </p> </li> |
|
213 <li id="GUID-ECCD22D2-9504-57EA-9245-5BD071B84694"><p>user memory cannot be |
|
214 accessed </p> </li> |
|
215 <li id="GUID-35C14F6F-EAFF-549A-BA2B-7EF5F2B6D093"><p>the function cannot |
|
216 block or wait. </p> </li> |
|
217 </ul> <p id="GUID-6957D624-5176-591C-A667-4DF78B29F271"><b>Call either in a thread |
|
218 or an IDFC context</b> </p> <p>This pre-condition means that the described |
|
219 function can be called directly, or indirectly, from an IDFC, a DFC or a thread. |
|
220 The thread can be a user thread or a kernel thread. </p> <p>Note that when |
|
221 calling a function from an IDFC: </p> <ul> |
|
222 <li id="GUID-7B6B2A5B-D282-529E-9D6B-7B1E2EC0BE0F"><p>the kernel is locked, |
|
223 so pre-emption is disabled </p> </li> |
|
224 <li id="GUID-BDEA9088-1340-59C9-B94F-848AF530F55A"><p>user memory cannot be |
|
225 accessed </p> </li> |
|
226 <li id="GUID-2073105B-FFE9-57C0-AB9D-3D3459BCED16"><p>the function cannot |
|
227 block or wait. </p> </li> |
|
228 </ul> <p id="GUID-A45A1D39-8C76-5E14-8DCF-FCE0A26758CE"><b>Call in any context</b> </p> <p>This |
|
229 pre-condition means that the described function can be called directly, or |
|
230 indirectly, from an IDFC, a DFC or a thread, or it can be called from an Interrupt |
|
231 Service Routine (ISR). </p> <p>A thread can be a user thread or a kernel thread. </p> <p>Note |
|
232 that when calling a function from an IDFC: </p> <ul> |
|
233 <li id="GUID-4E80B3B7-BBBC-51F5-AC6D-996240416B29"><p>the kernel is locked, |
|
234 so pre-emption is disabled </p> </li> |
|
235 <li id="GUID-BCF8F1AA-2F70-54BC-9FB6-C5EDD9057C79"><p>user memory cannot be |
|
236 accessed </p> </li> |
|
237 <li id="GUID-A7B6B42D-0FDB-589E-860B-F2D1D8892BC7"><p>the function cannot |
|
238 block or wait. </p> </li> |
|
239 </ul> <p id="GUID-0DCAE842-45E1-5F5F-BC68-121775D0B702"><b>Do not call from an ISR</b> </p> <p>This |
|
240 pre-condition means that the described function must not be called from an |
|
241 Interrupt Service Routine (ISR). </p> <p>Note that ISRs have the following |
|
242 characteristics: </p> <ul> |
|
243 <li id="GUID-D773586B-422C-5B03-8588-1A24058A5DD1"><p>they have an unknown |
|
244 context </p> </li> |
|
245 <li id="GUID-3BACC342-0768-5D2F-BE53-58C33B74C392"><p>they must not allocate |
|
246 or free memory </p> </li> |
|
247 <li id="GUID-DE919B78-9516-5F3D-98B2-3A99D8C3EE15"><p>they cannot access user |
|
248 memory </p> </li> |
|
249 <li id="GUID-04AFFA6E-C742-5068-81B7-AFEA47422763"><p>they must not call functions |
|
250 that interfere with critical sections of code. </p> </li> |
|
251 </ul> <p id="GUID-F17D0FE5-BA42-575B-8971-C5B034CF404E"><b>The calling thread must |
|
252 own the semaphore</b> </p> <p>A semaphore can be waited on only by the thread |
|
253 that owns it. This precondition is needed when the described function calls |
|
254 a semaphore wait function. </p> <p id="GUID-8D9D08F5-0CBD-52BB-B416-636516982D47"><b>The calling thread must |
|
255 not be explicitly suspended</b> </p> <p>This refers to nanokernel threads, |
|
256 not Symbian platform threads. The described function must not be used if the |
|
257 thread is in the suspended state. One of the possible reasons for this is |
|
258 that the described function does not check the thread's suspend count. </p> <p>A |
|
259 thread may be created suspended, or the thread may be put into a suspended |
|
260 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 |
|
261 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 |
|
262 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 |
|
263 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 |
|
264 hold the mutex</b> </p> <p>The calling thread has waited for a mutex and acquired |
|
265 it. This precondition is needed when the thread is about to release the mutex, |
|
266 ie call one of the <codeph>Signal()</codeph> functions. </p> <p id="GUID-DDEB4D47-04F5-5736-A8BE-3F1AC543F9D7"><b>Call only from ISR, IDFC |
|
267 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 |
|
268 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 |
|
269 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 |
|
270 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 |
|
271 be exiting</b> </p> <p>The pre-condition means that the described function |
|
272 should not be called after the thread has been killed. </p> <p>In EKA2, threads |
|
273 do not die immediately, they are placed on a queue to be deleted later. </p> <p>Functions |
|
274 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 |
|
275 property is a single value used by “Publish and Subscribe”. Each property |
|
276 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 |
|
277 means that the property must <i>NOT</i> already be open when the described |
|
278 function is called. </p> <p id="GUID-D924E37C-300A-58FF-890B-F1FA5349FA05"><b>Property has been opened</b> </p> <p>A |
|
279 property is a single value used by “Publish and Subscribe”. Each property |
|
280 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 |
|
281 means that the property must already be open before calling the described |
|
282 function. </p> <p id="GUID-F1485BCB-8384-518B-AE5B-F8387DF0C8F4"><b>Must be called under an |
|
283 XTRAP harness or calling thread must not be in a critical section</b> </p> <p>Each |
|
284 Symbian platform thread can be associated with a kernel-side |
|
285 exception handler, set using XTRAP(); for example, to detect bad memory accesses. </p> <p>The |
|
286 described function can legitimately cause an exception, and the pre-condition |
|
287 means that </p> <p> <i>either</i>: </p> <ul> |
|
288 <li id="GUID-485A8370-E3D5-5E67-9136-3150EC050DF0"><p>the described function |
|
289 should be called inside an XTRAP() harness to catch the exception </p> </li> |
|
290 </ul> <p> <i>or</i> </p> <ul> |
|
291 <li id="GUID-BDF6FFE8-E447-5E3D-A809-364A0A515C33"><p>the thread must not |
|
292 be in a critical section, because exceptions are not allowed inside them. |
|
293 If a thread takes an exception while inside a critical section, this is treated |
|
294 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> |
|
295 </ul> <p id="GUID-4D6B9502-0F88-5E0E-8E92-5783FE76555A"><b>DObject::Lock fast mutex |
|
296 held</b> </p> <p>The described function accesses an object whose internal |
|
297 data needs to be protected by the specified fast mutex. </p> <p>The operations |
|
298 of: </p> <ul> |
|
299 <li id="GUID-B358DA23-F140-5F08-878F-69455A83A729"><p>obtaining an object’s |
|
300 name </p> </li> |
|
301 <li id="GUID-3838D839-5210-5FB7-AF0C-3F3C299AA7B8"><p>setting an object's |
|
302 name </p> </li> |
|
303 <li id="GUID-2AD3BEC1-E934-513B-BAED-3FF164161F2D"><p>setting an object's |
|
304 owner </p> </li> |
|
305 </ul> <p>are all protected by the global fast mutex, <codeph>DObject::Lock</codeph>. |
|
306 This is done to avoid inconsistent results caused by, for example, one thread |
|
307 renaming an object while another is reading its name or full name. </p> <p>Setting |
|
308 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 |
|
309 held</b> </p> <p>The <codeph>DCodeSeg::CodeSegLock</codeph> mutex protects |
|
310 the global code graph from simultaneous accesses. Wait on this mutex before |
|
311 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 |
|
312 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 |
|
313 base port</b> </p> <p>The pre-condition means that the described function |
|
314 can only be called during the first phase of kernel initialisation, i.e. during |
|
315 execution of the Base Port implementation of <codeph>Asic::Init1()</codeph>. |
|
316 See the <xref href="GUID-DEB51862-A72B-5FB7-B1BA-F34685E71BFF.dita">Board Support |
|
317 Packages Quick Start</xref>. </p> <p>This condition may apply because the |
|
318 described function: </p> <ul> |
|
319 <li id="GUID-62621625-D712-5F4C-B31D-067E5887D8FD"><p>must be called before |
|
320 any context switch </p> </li> |
|
321 <li id="GUID-FB33B022-A388-5508-9C98-33518154BBBA"><p>must be called before |
|
322 the MMU is turned on. </p> </li> |
|
323 </ul> <p id="GUID-6122C9C6-05EB-508C-8C9A-45B6A8DAB42C"><b>The various parameters must |
|
324 be valid. The PIL or PSL will fault the kernel if not</b> </p> <p>This pre-condition |
|
325 refers to a DMA request. </p> <p>The parameters used when calling the described |
|
326 function must be as specified. If they are not, the platform independent layer |
|
327 or the platform specific layer cannot recover and will cause the kernel to |
|
328 fault, i.e. the device will reset. </p> <p id="GUID-041025B4-95B9-5493-ACC3-649B6683DE0D"><b>The request is not being |
|
329 transferred or pending</b> </p> <p>This pre-condition refers to a DMA request. </p> <p>The |
|
330 described function must not be called if a DMA request has already been set |
|
331 up, or is in progress. A possible reason for this is that the described function |
|
332 resets parameters that have been already setup. </p> <p id="GUID-582E833B-C0E9-5986-86C5-24BF15648D61"><b>Wait on TimerMutex before |
|
333 calling this</b> </p> <p>The <codeph>TimerMutex</codeph> mutex protects the |
|
334 timer queues. Wait and signal operations on the timer mutex are accomplished |
|
335 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>. |
|
336 This precondition is necessary when the described function manipulates the |
|
337 timer queue. </p> <p id="GUID-98CBADF3-8CD3-54BC-8CB7-C2BD8D48289A"><b>Message must be in ACCEPTED |
|
338 state</b> </p> <p>This pre-condition indicates that the message has been read |
|
339 by the receiving thread. It is not attached to a message queue but is currently |
|
340 in use by the receiving thread. </p> <p id="GUID-B9E940EF-0EC8-5EEB-B29B-B402BFF09350"><b>Queue must not be in asynchronous |
|
341 receive mode</b> </p> <p>This pre-condition refers to kernel side message |
|
342 queues. A kernel thread can receive messages: </p> <ul> |
|
343 <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> |
|
344 <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> |
|
345 </ul> <p>A possible reason for this precondition is that the queue is about |
|
346 to be polled. </p> <p>The queue may be polled either: </p> <ul> |
|
347 <li id="GUID-FD59C03B-1B65-52F6-A1C6-177D48D4CFC2"><p>before the first <codeph>Receive()</codeph> is |
|
348 issued </p> </li> |
|
349 <li id="GUID-7551CDCD-67B1-5A1A-B1AA-5F95CF63EBD4"><p>while processing a message |
|
350 but before <codeph>Receive()</codeph> is called again </p> </li> |
|
351 </ul> <p id="GUID-52D720FB-7F57-5340-8C34-F39FE1E50C36"><b>Container mutex must be |
|
352 held / Thread container mutex must be held / Process container mutex must |
|
353 be held</b> </p> <p>Each of the containers is protected by a mutex. </p> <p>The |
|
354 pre-condition means that the calling thread must acquire the relevant mutex |
|
355 before calling the described function. Object containers are <xref href="GUID-7FB9067F-D200-382C-84F7-49F0548D0A7F.dita"><apiname>DObjectCon</apiname></xref> types, |
|
356 and the relevant mutexes are acquired and freed by calling <codeph>Wait()</codeph> and <codeph>Signal()</codeph> on |
|
357 the container object. </p> </section> |
|
358 <section id="GUID-F2DE76D5-0970-584F-9526-52E85932ACE8"><title>Post-conditions</title> <p>A |
|
359 post condition describes what is true on return from a kernel API function. </p> <ul> |
|
360 <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> |
|
361 <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> |
|
362 <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> |
|
363 <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> |
|
364 <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> |
|
365 <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> |
|
366 <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> |
|
367 <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> |
|
368 <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> |
|
369 <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> |
|
370 <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> |
|
371 <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> |
|
372 <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> |
|
373 <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> |
|
374 </ul> <p id="GUID-BCA4F419-3306-5AB4-AA78-451FDA60BB22"><b>Calling thread is in a critical |
|
375 section</b> </p> <p>The code is in a critical section on return from the function. </p> <p>See |
|
376 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 |
|
377 thread must be in a critical section</xref>. </p> <p id="GUID-24DFFB87-639C-5D68-BCA0-D78AE870C485"><b>Calling thread is not in |
|
378 a critical section</b> </p> <p>The code is <i>NOT</i> in a critical section |
|
379 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 |
|
380 thread can hold no more than one fast mutex at any given time. A fast mutex |
|
381 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 |
|
382 post-condition means that, on exit from the described function, the kernel |
|
383 lock is on. The described function might have explicitly set the kernel lock |
|
384 or, more commonly, the lock was set before entry to the described function, |
|
385 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 |
|
386 must be locked</xref>. </p> <p id="GUID-7A7AC948-D84D-5581-80CE-328F1C6DA89E"><b>Kernel is unlocked</b> </p> <p>The |
|
387 kernel is <i>NOT</i> locked on exit from the described function. The described |
|
388 function might have explicitly unset the kernel lock or, more commonly, the |
|
389 lock was not set before entry to the described function, and has not been |
|
390 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 |
|
391 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 |
|
392 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 |
|
393 post-condition states that interrupts are enabled on return from the described |
|
394 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 |
|
395 must be enabled</xref> </p> <p id="GUID-298793D0-D6E0-5FE3-84DF-FE0057E83B31"><b>Interrupts are disabled</b> </p> <p>This |
|
396 post-condition states that interrupts are disabled on return from the described |
|
397 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 |
|
398 must be disabled</xref> </p> <p id="GUID-236D2CCB-1A32-5B30-A28D-96A9416A62A1"><b>System lock is held</b> </p> <p>This |
|
399 post-condition states that the system lock is held on return from the described |
|
400 function. </p> <p>The system lock is a specific fast mutex that only provides |
|
401 exclusion against other threads acquiring the same fast mutex. Setting, and |
|
402 acquiring the system lock means that a thread enters an implied critical section. </p> <p>The |
|
403 major items protected by the system lock are: </p> <ul> |
|
404 <li id="GUID-63E77673-0405-5E59-8102-67454FF96D1C"><p> <codeph>DThread</codeph> member |
|
405 data related to thread priority and status. </p> </li> |
|
406 <li id="GUID-3A37E1EF-89CF-50DA-B4B4-174A3B307873"><p>the consistency of the |
|
407 memory map; on the kernel side, the state of user side memory or the mapping |
|
408 of a process is not guaranteed unless (a) you are a thread belonging to the |
|
409 process that owns the memory or (b) you hold the system lock. </p> </li> |
|
410 <li id="GUID-D25EE56D-2FF5-515A-B826-08331B16C72E"><p>the lifetime of <codeph>DObject</codeph> type |
|
411 objects and references to them, including handle translation in Exec dispatch. </p> </li> |
|
412 </ul> <p><note> System lock is different from the kernel lock; the kernel |
|
413 lock protects against any rescheduling. When the system lock is set, the calling |
|
414 thread can still be pre-empted, even in the locked section.</note> </p> <p>The |
|
415 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 |
|
416 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 |
|
417 the mutex</b> </p> <p>The calling thread has waited for a mutex and acquired |
|
418 it. On return from the described function, the thread still holds the mutex. </p> <p>See |
|
419 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 |
|
420 calling thread must hold the mutex</xref>. </p> <p id="GUID-C293EDE0-B326-54A2-AB4F-17E9158B67AC"><b>Container mutex is held |
|
421 / Thread container mutex is held / Process container mutex is held</b> </p> <p>Each |
|
422 of the containers is protected by a mutex. </p> <p>The post-condition means |
|
423 that the calling thread has the relevant mutex on return from the described |
|
424 function. This is most likely because the mutex was acquired before entering |
|
425 the described function. </p> <p>Object containers are <xref href="GUID-7FB9067F-D200-382C-84F7-49F0548D0A7F.dita"><apiname>DObjectCon</apiname></xref> types, |
|
426 and the relevant mutexes are acquired and freed by calling <codeph>Wait()</codeph> and <codeph>Signal()</codeph> on |
|
427 the container object. </p> <p id="GUID-A5EED271-3A9C-5373-BC84-66546DE4DDD9"><b>DCodeSeg::CodeSegLock mutex |
|
428 held</b> </p> <p>The <codeph>DCodeSeg::CodeSegLock</codeph> mutex protects |
|
429 the global code graph from simultaneous accesses. </p> <p>This post condition |
|
430 means that the mutex is held on exit. The most common situation is that the |
|
431 mutex was acquired before entry to the described function. Relinquish the |
|
432 mutex by calling <codeph>DCodeSeg::Signal()</codeph>. </p> </section> |
|
433 </conbody></concept> |