Mercurial Mercurial > oss > MCL > sftools > depl > docscontent / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Adaptation/GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1.dita
changeset 15 307f4279f433 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Adaptation/GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1.dita	Fri Oct 15 14:32:18 2010 +0100
@@ -0,0 +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-GENID-1-2-1-9-1-8-1-17-1" 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-GENID-1-2-1-9-1-8-1-17-1-3-1-1"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1/GUID-55866E19-257D-5C0B-BFD2-31F0A5B74070-GENID-1-2-1-9-1-8-1-17-1-3-2">What does checking the validity of calls mean?</xref>  </p> </li>
+<li id="GUID-3F5064A8-174B-503C-AA02-08797E804126-GENID-1-2-1-9-1-8-1-17-1-3-1-2"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1/GUID-E2945D82-0EC5-53AD-82DE-AD47C21E870C-GENID-1-2-1-9-1-8-1-17-1-3-3">What happens if a validity check fails?</xref>  </p> </li>
+<li id="GUID-C9DCF427-9283-5476-9F16-88C94FC18D28-GENID-1-2-1-9-1-8-1-17-1-3-1-3"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1/GUID-BB0C87D0-CC1E-5EC9-872C-AA50C99F323F-GENID-1-2-1-9-1-8-1-17-1-3-4">Which conditions are checked?</xref>  </p> </li>
+</ul>
+<section id="GUID-55866E19-257D-5C0B-BFD2-31F0A5B74070-GENID-1-2-1-9-1-8-1-17-1-3-2"><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-GENID-1-2-1-9-1-8-1-17-1-3-2-4-1"><p>the calling thread must
+be in a critical section </p> </li>
+<li id="GUID-DBBDB602-3451-5745-B80C-4779BCDCEDC7-GENID-1-2-1-9-1-8-1-17-1-3-2-4-2"><p>interrupts must be enabled </p> </li>
+<li id="GUID-094CE1C9-0F5E-5ECE-96CE-187CAF998633-GENID-1-2-1-9-1-8-1-17-1-3-2-4-3"><p>the kernel must be unlocked </p> </li>
+<li id="GUID-765B8EFA-F539-5169-B593-F077942E2164-GENID-1-2-1-9-1-8-1-17-1-3-2-4-4"><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-GENID-1-2-1-9-1-8-1-17-1-3-3"><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-GENID-1-2-1-9-1-8-1-17-1-3-3-4-1"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1/GUID-F97EBEF0-D07C-5F40-ADE6-BD050B54A010-GENID-1-2-1-9-1-8-1-17-1-3-3-6">__KERNEL_APIS_CONTEXT_CHECKS_WARNING__</xref> </p> </li>
+<li id="GUID-FAFC6553-92CB-52A5-843D-C9A2136F22F6-GENID-1-2-1-9-1-8-1-17-1-3-3-4-2"><p><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1/GUID-A2D9762E-6A1A-5307-9BEE-4EA9A86350EF-GENID-1-2-1-9-1-8-1-17-1-3-3-11">__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-GENID-1-2-1-9-1-8-1-17-1-3-3-6"><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-GENID-1-2-1-9-1-8-1-17-1-3-3-8" 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-GENID-1-2-1-9-1-8-1-17-1-3-3-10" xml:space="preserve">Assertion failed: Calling thread must be in a critical section
+DLogicalChannel::Close</codeblock> <p id="GUID-A2D9762E-6A1A-5307-9BEE-4EA9A86350EF-GENID-1-2-1-9-1-8-1-17-1-3-3-11"><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-GENID-1-2-1-9-1-8-1-17-1-3-3-13">
+<li id="GUID-B4E5922D-FB75-5DD5-BF9B-F0D2833FAB9B-GENID-1-2-1-9-1-8-1-17-1-3-3-13-1"><p>causes a text message
+to be written to a trace port, as happens if <codeph/><xref href="GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1/GUID-F97EBEF0-D07C-5F40-ADE6-BD050B54A010-GENID-1-2-1-9-1-8-1-17-1-3-3-6">__KERNEL_APIS_CONTEXT_CHECKS_WARNING__</xref> is defined. </p> </li>
+<li id="GUID-821EAF7B-E8D5-5D9E-85BA-AEF3A88C5EBD-GENID-1-2-1-9-1-8-1-17-1-3-3-13-2"><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-GENID-1-2-1-9-1-8-1-17-1.dita#GUID-A90D9D85-53DC-5368-89F2-137BE5D50745-GENID-1-2-1-9-1-8-1-17-1/GUID-A2D9762E-6A1A-5307-9BEE-4EA9A86350EF-GENID-1-2-1-9-1-8-1-17-1-3-3-11">__KERNEL_APIS_CONTEXT_CHECKS_FAULT__</xref> is defined. </p> </section>
+<section id="GUID-BB0C87D0-CC1E-5EC9-872C-AA50C99F323F-GENID-1-2-1-9-1-8-1-17-1-3-4"><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
MCL/sftools/depl/docscontent