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