<?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>