Personality Layer Design

Memory management

The personality layer assumes that the RTA will run in a single flat address space in which there is neither protection between different parts of the application nor protection of any hardware or CPU resource from any part of the application. For example, any part of the application code can access any I/O port, and can disable interrupts.

To get this behaviour under the Kernel Architecture 2, the RTA must run in supervisor mode in the kernel address space. The obvious way to do this is to make the RTA together with the personality layer a kernel extension. This also ensures that it is started automatically early on in the boot process.

In general the RTA will have its own memory management strategy and will not wish to use the standard Symbian platform memory management system. To achieve this, the personality layer will allocate a certain fixed amount of RAM for use by the real time application at boot time. For a telephony stack this will be around 128K - 256K. This can be done either by including it in the kernel extension's .bss section, or by making a one-time allocation on the kernel heap at boot time. Depending on the RTA requirements, the personality layer can manage this area of RAM (if the RTOS being emulated provides memory management primitives) or the RTA can manage it.

Threads and mapping thread priorities

A nanokernel thread will be used for each RTOS thread

A priority mapping scheme will be required to map RTOS priorities, of which there are typically 64 to 256 distinct values, to nanokernel priorities. As long as the RTA does not use more than 35 threads running simultaneously, which is usually the case, it should be possible to produce a mapping scheme that allows each thread to have a distinct priority, if needed. If this limit is exceeded, it will be necessary to fold some priorities together.

Note that any attempt to increase the number of priorities supported by both the nanokernel and the Symbian platform kernel would be prohibitively expensive in terms of RAM usage.

Communication between Symbian platform and the RTOS Environments

To allow the functionality of the RTA to be available to Symbian platform applications, it is necessary that a mechanism exist by which Symbian platform code and the RTA may communicate with each other. In practice this means:

• it must be possible for a Symbian platform thread to cause an RTOS thread to be scheduled and vice-versa

• it must be possible for data to be transferred between Symbian platform and RTOS threads in both directions.

It will usually be possible for a Symbian platform thread to make standard personality layer calls (the same calls that RTOS threads would make) in order to cause an RTOS thread to be scheduled. This is because the nanokernel underlies both types of thread and most 'signal' type operations (i.e. those that make threads ready rather than blocking them) can be implemented using operations which make no reference to the calling thread, and which are therefore not sensitive to which type of thread they are called from.

The standard personality layer calls will not work in the other direction, since it will not be possible for a Symbian platform thread to wait on a personality layer wait object. The most straightforward way for RTOS threads to trigger scheduling of a Symbian platform thread would be to enque a DFC on a queue operated by a Symbian platform thread. Another possibility would be for the Symbian platform thread to wait on a fast semaphore which could then be signalled by the RTOS thread. However the DFC method fits better with the way device drivers are generally written. A device driver will be necessary to mediate communication between Symbian platform user mode processes and the RTA since the latter runs kernel side.

All data transfer between the two environments must occur kernel side. It will not be possible for any RTOS thread to access normal user side memory since the functions provided for doing so access parts of the DThread structure representing the Symbian platform calling thread, for example to perform exception trapping. Some possibilities for the data transfer mechanism are:

• A fairly common architecture for real time applications involves a fixed block size memory manager and message queues for inter-thread communication. The memory manager supports allocation and freeing of memory in constant time. The sending thread allocates a memory block, places data in it and posts it to the receiving thread's message queue. The receiving thread then processes the data and frees the memory block, or possibly passes the block to yet another thread. It would be a simple proposition to produce such a system in which the memory manager could be used by any thread. In that case a Symbian platform thread could pass messages to RTOS threads in the same way as other RTOS threads. Passing data back would involve a special type of message queue implemented in the personality layer. When a message was sent to a Symbian platform thread a DFC would be enqueued. That DFC would then process the message data and free the memory block as usual. This scheme combines the data transfer and scheduling aspects of communication.

• Any standard buffering arrangement could be used between the RTA and the device driver (e.g. circular buffers). Contention between threads could be prevented using nanokernel fast mutexes, on which any thread can wait, or by the simpler means of disabling preemption or disabling interrupts. It will also be possible for RTOS threads to make use of shared I/O buffers for transfer direct to user mode clients, provided that these buffers are set up by the Symbian platform device driver thread. This may be useful as a way to reduce copying overhead if bulk data transfer is necessary between the two domains.

Synchronisation/communication primitives

The nanokernel does not support most of the synchronisation and communication primitives provided by a standard RTOS. Any such primitives required by the RTA will have to be implemented in the personality layer. This means that the personality layer needs to define new types of object on which threads can wait. This in turn means that new nanokernel thread states (N-state) must be defined to signify that a thread is waiting on an object of the new type. In general, each new type of wait object requires an accompanying new nanokernel thread state.

Blocking a thread on a wait object

To make a thread block on a new type of wait object, call the nanokernel function Kern::NanoBlock(), passing the maximum time for which the thread should block, the new N-state value, and a pointer to the wait object.

Use the TPriListLink base class of NThreadBase to attach the thread to a list of threads waiting on the object. Note that this must be done after calling Kern::NanoBlock(). As preemption is disabled before this function is called, a reschedule will not occur immediately, but will be deferred until preemption is reenabled.

State handler

Every thread that can use a new type of wait object, must have a nanokernel state handler installed to handle operations on that thread when it is waiting on that wait object. A nanokernel state handler is a function that has the following signature:

void StateHandler(NThread* aThread, TInt aOp, TInt aParam);

• aThread is a pointer to the thread involved.

• aOp is one of the NThreadBase::NThreadOperation values that indicates which operation is being performed on the thread.

• aParam is a parameter that depends on aOp.

Note that the state handler is always called with preemption disabled.

The possible values of aOp are:

See the code in ...\e32\personality\example\... for practical examples.

Releasing the thread

When a thread's wait condition is resolved, the nanokernel function NThreadBase::Release() should be called. This takes a single TInt parameter.

The parameter is usually KErrNone, if the wait condition is resolved normally. A typical example is where the semaphore on which the thread is waiting, is signalled. A negative parameter value is used for an abnormal termination, and in this case, the wait object may need to be rolled back.

NThreadBase::Release() should be called with preemption disabled. It performs the following actions:

• sets the NThreadBase::iWaitObj field to NULL

• cancels the wait timer if it is still running

• stores the supplied return code in NThreadBase::iReturnCode

• calls the state handler passing ERelease and the return code. If the return code is negative this should remove the thread from any wait queues and roll back the state of the wait object. In any case it should call NThreadBase::CheckSuspendThenReady() to make the thread ready again if necessary.

Thread scheduling following a hardware interrupt

Most RTOS allow interrupt service routines (ISRs) to perform operations such as semaphore signal, queue post, set event flag directly, usually using the same API as would be used in a thread context. The Kernel Architecture 2 nanokernel does not allow this; ISRs can only queue an IDFC or DFC.

The way to get round this limitation is to incorporate an IDFC into each personality layer wait object. The personality layer API involved then needs to check whether it is being invoked from an ISR or a thread and, in the first case, it queues the IDFC. It may need to save some other information for use by the IDFC, for example, it may need to maintain a list of messages queued from ISRs, a count of semaphore signals from ISRs or a bit mask of event flags set by ISRs. Checking for invocation from an ISR can be done either by using NKern::CurrentContext(), or by checking the CPSR directly; if doing the latter note that any mode other than USR or SVC on the ARM counts as interrupt context.

Hardware interrupts serviced by the RTA will need to conform to the same pattern as those serviced by Symbian platform extensions or device drivers. This means that the standard preamble must run before the actual service routine and the nanokernel interrupt postamble must run after the service routine to enable reschedules to occur if necessary. This can be done by calling Interrupt::Bind() as provided by the base port during RTA initialisation (possibly via a personality layer call if it must be called from C code). See also Interrupt Dispatcher Tutorial.