<?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-5B1D8D9C-90EF-5FCC-8D7D-01B13D6C2E68" xml:lang="en"><title>Nanokernel</title><shortdesc>The nanokernel is the core of the Kernel, and is a small real-time

operating system (RTOS) designed to run Symbian platform.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A <xref href="GUID-2700AAC8-A034-5E7D-B0E0-26B49E68BB18.dita">Personality Layer

for Real Time Applications</xref> is a client of the nanokernel, and this

topic is intended for writers of personality layers. </p>

<section id="GUID-B8D8C73E-75CB-417D-A6DA-EE8B77A28256"><title>Nanokernel threads</title> <p>The fundamental unit of execution

is the nanokernel thread, an <xref href="GUID-187D314F-1115-3671-AC46-37AEC5DFB2AC.dita"><apiname>NThread</apiname></xref> object. </p> <p>A

nanokernel thread has an integer priority, between 0 and 63 inclusive, and

is scheduled according to priority, the highest priority first. Equal priority

threads are scheduled on either a round robin or a run-to-completion basis,

selectable for each thread. For round robin scheduling, the time slice is

selectable for each thread. </p> <p>Priority 0 is reserved for the system

idle thread. </p> <p>Priorities 1-27 inclusive, and priority 48 are currently

used by Symbian platform threads; 12 is the priority of the foreground Symbian

platform application. There are, therefore, 35 distinct priorities that are

totally unused and available for a real time application. </p> <p>Nanokernel

threads may be created and destroyed dynamically, but the nanokernel does

not do any memory management. Memory for both the thread object and the thread

stack must be provided by the caller at create time. In fact the same rule

applies throughout the nanokernel - all memory for dynamically created objects

must be provided by the caller and freed by the caller after object destruction. </p> </section>

<section id="GUID-45416245-24B2-40FA-98C2-94C29F94A200"><title>Nanokernel synchronisation</title> <p>The nanokernel provides

the following synchronisation objects: </p> <ul>

<li id="GUID-F94065EB-10A6-51A8-8B11-A0B887B994C6"><p>A fast semaphore, a <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref> object.

This is a lightweight counting semaphore owned by a specific nanokernel thread.

Any thread can signal it, but only the owning thread can wait on it. </p> </li>

<li id="GUID-CFA09EAD-34FE-5F41-83D5-52381B4A6C81"><p>A fast mutex, a <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita"><apiname>NFastMutex</apiname></xref> object.

This is a lightweight mutual exclusion primitive. It is optimised for very

fast acquisition and release in the case where there is no contention, and

it provides priority inheritance. It is non-nestable, i.e. a thread is not

allowed to hold two fast mutexes simultaneously or to wait on one which it

already holds. In addition, a thread that holds a fast mutex cannot block

on any other wait object. </p> </li>

<li id="GUID-598F43D7-0517-5866-85BF-6E7D67C5CFDE"><p>Deferred function calls

(DFCs). </p> </li>

</ul> <p>There is also the option of thread synchronisation by doing one of: </p> <ul>

<li id="GUID-F3DBBDC5-1245-5C74-A02B-39FC5EFF8484"><p>disabling interrupts,

by calling <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-8C251C65-FDE7-3161-8D2B-61401FB6487F"><apiname>NKern::DisableAllInterrupts()</apiname></xref>  </p> </li>

<li id="GUID-869B40AF-9311-5539-8F5F-AFF1BF6F56F6"><p>disabling preemption,

by calling <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-7CBBF72B-4519-38DD-92CA-38AF636AFD8A"><apiname>NKern::Lock()</apiname></xref> </p> </li>

</ul> <p>However, these two techniques must be used with caution as they affect

all parts of the system. </p> </section>

<section id="GUID-640C747E-6A7B-47B3-BC05-84A10DAE484F"><title>Scheduling threads following a hardware interrupt</title> <p>In

order to keep interrupt latency to a minimum the vast majority of the nanokernel

runs with interrupts enabled; this includes the scheduler and other code which

manipulates the thread ready list. A consequence of this is that it is <i>not</i> permissible

for an interrupt service routine (ISR) to add a thread to the thread ready

list. The only way an ISR can influence the scheduling of threads is by means

of an Immediate Deferred Function Call (IDFC). </p> <p>An IDFC is a function

call that runs either: </p> <ul>

<li id="GUID-4324A39E-D9F9-5F21-93BA-8014B39D17A0"><p>immediately after the

completion of the ISR, and any other ISRs that are pending. </p> </li>

</ul> <p>or </p> <ul>

<li id="GUID-BAA5895F-DBBC-5B42-B57A-5AF4DEC90824"><p>as soon as preemption

is re-enabled, if preemption was disabled at the time the interrupt occurred. </p> </li>

</ul> <p>IDFCs run in FIFO order, i.e. the first one queued is first one to

run, with interrupts enabled and preemption disabled. This means that IDFCs

cannot be preempted either by threads or by other IDFCs, but only by ISRs.

However, they can add threads to the ready list and thus cause rescheduling. </p> <p>As

IDFCs are nonpreemptive, they need to be kept short. This means that they

affect thread latency. If a large amount of work needs to be done in response

to an ISR, then a Deferred Function Call (DFC) should be used. </p> <p>A DFC

is a function call that runs in the context of a nominated thread. A DFC is

associated with a DFC queue, which in turn is associated with a thread. The

thread simply waits forever for a DFC to be added to the queue and then calls

back the DFC. DFCs execute with both interrupts and preemption enabled. Because

DFCs are so common in Symbian platform driver code, the nanokernel provides

a shortcut to allow them to be queued directly by ISRs instead of by an IDFC.

The same object, a <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita"><apiname>TDfc</apiname></xref>, is used for both IDFCs and DFCs.

When this object is queued by an ISR, it first executes as an IDFC; the code

for this IDFC is buried in the nanokernel. This code transfers the object

to the final DFC queue and wakes up the DFC thread as required. </p> </section>

<section id="GUID-1EB1E07D-433B-4058-9CE3-4825A8945704"><title>Nanokernel thread handlers</title> <p>Each nanokernel thread

can have the following handlers defined: </p> <ul>

<li id="GUID-A52FA56C-D5CF-5186-A3A4-09941C17C0E0"><p>Exit handler. This is

called in the context of the exiting thread just before it is terminated. </p> </li>

<li id="GUID-66E53EEE-B076-5116-AA72-CDE4EE19315D"><p>Exception handler. This

is called if a CPU exception occurs during the execution of the thread; it

is called, in the context of the thread. </p> </li>

<li id="GUID-8369C8AD-C9C1-505D-89F3-983F23009F9B"><p>Time-out handler. This

is called if the thread's wait time-out expires with the thread in the BLOCKED

state, or in an unknown state. It is called in the context of the nanokernel

timer thread, DFC Thread 1, with preemption enabled. It is used in Symbian

platform wait-with-timeout operations. </p> </li>

<li id="GUID-7665E6CA-8BB4-5F1B-8CEB-DA5F59D77619"><p>State handler. <i>This

is the fundamental hook used for personality layers.</i>. It is called if: </p> <ul>

<li id="GUID-7996AB09-C5DF-520E-ADBB-B65AF9EC536F"><p>the thread is suspended </p> </li>

<li id="GUID-39CC9F5E-663F-5BAD-8D04-55E698F7D405"><p>the thread is resumed </p> </li>

<li id="GUID-4DE5F701-EA02-5C43-896D-38202F9CB8EE"><p>the thread is released </p> </li>

<li id="GUID-EA3FCFAF-890B-537B-BE1F-F605B19BF9B5"><p>the thread has its priority

changed </p> </li>

<li id="GUID-63E0ABEB-2878-5F4D-92CB-AF2EB28D2A54"><p>the thread's wait timeout

expires and there is no time-out handler and the thread is in an unrecognised

nanokernel state. </p> </li>

</ul> </li>

</ul> <p>See also <filepath>...\e32\personality\example\personality.cpp</filepath>. </p> </section>

<section id="GUID-600F44F2-9F2D-409A-9D66-10526319020C"><title>Timer management </title> <p>The nanokernel provides a basic

relative timer object, an <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref>, which can generate either

one-shot or periodic interrupts. </p> <p>A time-out handler is called when

the timer expires, either from the timer ISR or from the nanokernel timer

thread. Timer objects may be manipulated from any context. The timers are

driven from a periodic system tick interrupt, usually a 1ms period. </p> <p>For

the purposes of power management, an API is provided to return the number

of ticks left until the next timer expiry, thus enabling the tick interrupt

to be suppressed and a deep sleep mode to be entered. </p> </section>