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