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