Kernel +API Validity Checks

What does checking the validity of calls mean?
What happens if a validity check fails?
Which conditions are checked?

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:

causes a text message +to be written to a trace port, as happens if __KERNEL_APIS_CONTEXT_CHECKS_WARNING__ is defined.
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.