|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1" xml:lang="en"><title>Kernel |
|
13 API Validity Checks</title><shortdesc>Describes the pre-condition checks that Kernel APIs can do when |
|
14 they are called. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <ul> |
|
16 <li id="GUID-5D68233C-71CB-5779-B73D-675543F03817-GENID-1-2-1-8-1-1-7-1-1-4-1-3-1-1"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1/GUID-55866E19-257D-5C0B-BFD2-31F0A5B74070-GENID-1-2-1-8-1-1-7-1-1-4-1-3-2">What does checking the validity of calls mean?</xref> </p> </li> |
|
17 <li id="GUID-3F5064A8-174B-503C-AA02-08797E804126-GENID-1-2-1-8-1-1-7-1-1-4-1-3-1-2"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1/GUID-E2945D82-0EC5-53AD-82DE-AD47C21E870C-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3">What happens if a validity check fails?</xref> </p> </li> |
|
18 <li id="GUID-C9DCF427-9283-5476-9F16-88C94FC18D28-GENID-1-2-1-8-1-1-7-1-1-4-1-3-1-3"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1/GUID-BB0C87D0-CC1E-5EC9-872C-AA50C99F323F-GENID-1-2-1-8-1-1-7-1-1-4-1-3-4">Which conditions are checked?</xref> </p> </li> |
|
19 </ul> |
|
20 <section id="GUID-55866E19-257D-5C0B-BFD2-31F0A5B74070-GENID-1-2-1-8-1-1-7-1-1-4-1-3-2"><title>What does checking |
|
21 the validity of calls mean?</title> <p>A kernel-side function or service almost |
|
22 always requires that various preconditions apply before that function or service |
|
23 can be called. There are also times when a call to a kernel-side function |
|
24 or service from device drivers may not be appropriate, for example, calls |
|
25 to some specific functions from within Interrupt Service Routines (ISRs) or |
|
26 from within Deferred Function Calls (DFCs). </p> <p>For example, before you |
|
27 call <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-71A20F01-5E5F-3B27-92BA-3B3BF7D578C9"><apiname>Kern::CloseHandle()</apiname></xref>, the following conditions apply: </p> <ul> |
|
28 <li id="GUID-8B1908C7-BBC0-58DB-BA95-D6E550B53E2D-GENID-1-2-1-8-1-1-7-1-1-4-1-3-2-4-1"><p>the calling thread must |
|
29 be in a critical section </p> </li> |
|
30 <li id="GUID-DBBDB602-3451-5745-B80C-4779BCDCEDC7-GENID-1-2-1-8-1-1-7-1-1-4-1-3-2-4-2"><p>interrupts must be enabled </p> </li> |
|
31 <li id="GUID-094CE1C9-0F5E-5ECE-96CE-187CAF998633-GENID-1-2-1-8-1-1-7-1-1-4-1-3-2-4-3"><p>the kernel must be unlocked </p> </li> |
|
32 <li id="GUID-765B8EFA-F539-5169-B593-F077942E2164-GENID-1-2-1-8-1-1-7-1-1-4-1-3-2-4-4"><p>no fast mutex can be |
|
33 held </p> </li> |
|
34 </ul> <p>If conditions such as these are not met before you call the kernel-side |
|
35 function or service, then you risk damaging the integrity of the kernel and |
|
36 the whole system, with a very high risk of causing the kernel to fault followed |
|
37 by a re-boot of the device. </p> <p>The pre-conditions that apply vary with |
|
38 the function called; they are listed as part of the reference documentation |
|
39 for that function. </p> <p>To help device driver test suites check that device |
|
40 driver code is valid, stringent checks can be switched on in debug (non-production) |
|
41 builds of Symbian platform (and in the resulting test ROM images). These checks |
|
42 help to catch non-compliant device driver code during the testing phase of |
|
43 a new device. This minimizes the risk of production devices failing because |
|
44 of faulty device driver code. </p> </section> |
|
45 <section id="GUID-E2945D82-0EC5-53AD-82DE-AD47C21E870C-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3"><title>What happens |
|
46 if a validity check fails?</title> <p>Validity checking is done by code that |
|
47 is conditionally compiled into a build of Symbian platform. Such code has |
|
48 an impact on the performance of the device on which it runs, but is always |
|
49 restricted to test devices. On production builds of Symbian platform, validity |
|
50 checking is switched off, which means that the code is not compiled in and |
|
51 has no effect on performance. </p> <p>Validity checking is switched ON for |
|
52 a build of Symbian platform if <i>one or both</i> of the following macros |
|
53 is defined in <filepath>...\e32\kernel\kern_int.mmh</filepath> : </p> <ul> |
|
54 <li id="GUID-47071D73-190A-5996-9E82-67AE907A4918-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-4-1"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1/GUID-F97EBEF0-D07C-5F40-ADE6-BD050B54A010-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-6">__KERNEL_APIS_CONTEXT_CHECKS_WARNING__</xref> </p> </li> |
|
55 <li id="GUID-FAFC6553-92CB-52A5-843D-C9A2136F22F6-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-4-2"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1/GUID-A2D9762E-6A1A-5307-9BEE-4EA9A86350EF-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-11">__KERNEL_APIS_CONTEXT_CHECKS_FAULT__</xref> </p> </li> |
|
56 </ul> <p>Validity checking is switched OFF for a build of Symbian platform |
|
57 if <i>both</i> macros are <i>undefined</i> (in practice they will be marked |
|
58 as a comment rather than being completely deleted from the <filepath>.mmh</filepath> file). </p> <p id="GUID-F97EBEF0-D07C-5F40-ADE6-BD050B54A010-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-6"><b> __KERNEL_APIS_CONTEXT_CHECKS_WARNING__</b> </p> <p>If |
|
59 this macro is defined, then calling a kernel-side function when the necessary |
|
60 pre-conditions have not been satisfied causes a text message to be written |
|
61 to a trace port. The message has the format: </p> <codeblock id="GUID-637F4DA3-5B60-542B-8BC7-BEF67A884FFD-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-8" xml:space="preserve">Description of pre-condition that has not been met |
|
62 The name of the function checking the pre-condition</codeblock> <p>For example, |
|
63 when you call <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita#GUID-A3CC1D95-4681-3349-A67C-F113A614041D/GUID-CF1F6A0E-342A-3EDD-953C-3176D7D7F0A0"><apiname>DLogicalChannel::Close()</apiname></xref>, you must be in |
|
64 a critical section. If you are not, then you will see the following text in |
|
65 your trace: </p> <codeblock id="GUID-73E792DA-9C83-5885-A5E3-9293341ACFFC-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-10" xml:space="preserve">Assertion failed: Calling thread must be in a critical section |
|
66 DLogicalChannel::Close</codeblock> <p id="GUID-A2D9762E-6A1A-5307-9BEE-4EA9A86350EF-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-11"><b>__KERNEL_APIS_CONTEXT_CHECKS_FAULT__</b> </p> <p>If |
|
67 this macro is defined, then calling a kernel-side function when the necessary |
|
68 pre-conditions have not been satisfied: </p> <ol id="GUID-6735A9D4-C120-54E1-884C-1008221652DC-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-13"> |
|
69 <li id="GUID-B4E5922D-FB75-5DD5-BF9B-F0D2833FAB9B-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-13-1"><p>causes a text message |
|
70 to be written to a trace port, as happens if <codeph/><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1/GUID-F97EBEF0-D07C-5F40-ADE6-BD050B54A010-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-6">__KERNEL_APIS_CONTEXT_CHECKS_WARNING__</xref> is defined. </p> </li> |
|
71 <li id="GUID-821EAF7B-E8D5-5D9E-85BA-AEF3A88C5EBD-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-13-2"><p>causes the kernel to |
|
72 fault, specifying the function name as the fault category, and zero as the |
|
73 fault number. The crash debugger is also started if this is present on the |
|
74 device. </p> </li> |
|
75 </ol> <p><b>__KERNEL_APIS_CONTEXT_CHECKS_WARNING__ |
|
76 and __KERNEL_APIS_CONTEXT_CHECKS_FAULT__</b> </p> <p>If both macros are defined, |
|
77 then validity checking behaves as if <xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-8-1-1-7-1-1-4-1/GUID-A2D9762E-6A1A-5307-9BEE-4EA9A86350EF-GENID-1-2-1-8-1-1-7-1-1-4-1-3-3-11">__KERNEL_APIS_CONTEXT_CHECKS_FAULT__</xref> is defined. </p> </section> |
|
78 <section id="GUID-BB0C87D0-CC1E-5EC9-872C-AA50C99F323F-GENID-1-2-1-8-1-1-7-1-1-4-1-3-4"><title>Which conditions |
|
79 are checked?</title> <p>The section <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita#GUID-63456B20-3A61-554A-BBA4-C23B176E39A8/GUID-5F986149-D75B-5B3F-92F3-7B4FB89F4718">pre-conditions</xref> within the larger section <xref href="GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita">Pre-Conditions |
|
80 and Post-Conditions for Kernel APIs</xref> gives you some context for the |
|
81 most common pre-conditions that apply when calling kernel-side functions. |
|
82 This list is not exhaustive. </p> </section> |
|
83 </conbody></concept> |