Kernel API Validity Checks

What does checking the validity of calls mean?

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).

For example, before you call Kern::CloseHandle(), the following conditions apply:

• the calling thread must be in a critical section

• interrupts must be enabled

• the kernel must be unlocked

• no fast mutex can be held

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.

The pre-conditions that apply vary with the function called; they are listed as part of the reference documentation for that function.

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.

What happens if a validity check fails?

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.

Validity checking is switched ON for a build of Symbian platform if one or both of the following macros is defined in ...\e32\kernel\kern_int.mmh :

• __KERNEL_APIS_CONTEXT_CHECKS_WARNING__

• __KERNEL_APIS_CONTEXT_CHECKS_FAULT__

Validity checking is switched OFF for a build of Symbian platform if both macros are undefined (in practice they will be marked as a comment rather than being completely deleted from the .mmh file).

__KERNEL_APIS_CONTEXT_CHECKS_WARNING__

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:

Description of pre-condition that has not been met
The name of the function checking the pre-condition

For example, when you call DLogicalChannel::Close(), you must be in a critical section. If you are not, then you will see the following text in your trace:

Assertion failed: Calling thread must be in a critical section
DLogicalChannel::Close

__KERNEL_APIS_CONTEXT_CHECKS_FAULT__

If this macro is defined, then calling a kernel-side function when the necessary pre-conditions have not been satisfied:

1. causes a text message to be written to a trace port, as happens if __KERNEL_APIS_CONTEXT_CHECKS_WARNING__ is defined.

2. 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.

__KERNEL_APIS_CONTEXT_CHECKS_WARNING__ and __KERNEL_APIS_CONTEXT_CHECKS_FAULT__

If both macros are defined, then validity checking behaves as if __KERNEL_APIS_CONTEXT_CHECKS_FAULT__ is defined.

Which conditions are checked?

The section pre-conditions within the larger section Pre-Conditions and Post-Conditions for Kernel APIs gives you some context for the most common pre-conditions that apply when calling kernel-side functions. This list is not exhaustive.