Nanokernel

Nanokernel threads

The fundamental unit of execution is the nanokernel thread, an NThread object.

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.

Priority 0 is reserved for the system idle thread.

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.

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.

Nanokernel synchronisation

The nanokernel provides the following synchronisation objects:

• A fast semaphore, a NFastSemaphore 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.

• A fast mutex, a NFastMutex 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.

• Deferred function calls (DFCs).

There is also the option of thread synchronisation by doing one of:

• disabling interrupts, by calling NKern::DisableAllInterrupts()

• disabling preemption, by calling NKern::Lock()

However, these two techniques must be used with caution as they affect all parts of the system.

Scheduling threads following a hardware interrupt

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

An IDFC is a function call that runs either:

• immediately after the completion of the ISR, and any other ISRs that are pending.

or

• as soon as preemption is re-enabled, if preemption was disabled at the time the interrupt occurred.

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.

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.

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 TDfc, 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.

Nanokernel thread handlers

Each nanokernel thread can have the following handlers defined:

• Exit handler. This is called in the context of the exiting thread just before it is terminated.

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

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

• State handler. This is the fundamental hook used for personality layers.. It is called if:

  • the thread is suspended

  • the thread is resumed

  • the thread is released

  • the thread has its priority changed

  • the thread's wait timeout expires and there is no time-out handler and the thread is in an unrecognised nanokernel state.

See also ...\e32\personality\example\personality.cpp.

Timer management

The nanokernel provides a basic relative timer object, an NTimer, which can generate either one-shot or periodic interrupts.

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.

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.