<?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-42F8FA5A-BBE4-50DE-917E-D05755019FEC" xml:lang="en"><title>Personality
Layer Design</title><shortdesc>Provides some guidelines for the design of a personality layer
for real time Applications for the Kernel.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-A0EC87BF-170D-46B4-AEFF-F21D7483149B"><title>Memory management</title> <p>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. </p> <p>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. </p> <p>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 <filepath>.bss</filepath> 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. </p> </section>
<section id="GUID-FAA30849-282F-4E2D-ABDA-63E130A2D2FB"><title>Threads and mapping thread priorities</title> <p>A nanokernel
thread will be used for each RTOS thread </p> <p>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. </p> <p>Note that any attempt
to increase the number of priorities supported by both the nanokernel and
the Symbian platform kernel would be <i>prohibitively</i> expensive in terms
of RAM usage. </p> </section>
<section id="GUID-169604BD-A22A-5B56-8279-13F875AB4AB6"><title>Communication
between Symbian platform and the RTOS Environments</title> <p>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: </p> <ul>
<li id="GUID-DC8AF97D-EA8A-5852-96FF-CCA19D69F614"><p>it must be possible
for a Symbian platform thread to cause an RTOS thread to be scheduled and
vice-versa </p> </li>
<li id="GUID-EF671D7A-28B6-505D-823C-5B51C378225E"><p>it must be possible
for data to be transferred between Symbian platform and RTOS threads in both
directions. </p> </li>
</ul> <p>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. </p> <p>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. </p> <p>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 <xref href="GUID-38D1534C-AA01-33AF-9937-CDD818A85F97.dita"><apiname>DThread</apiname></xref> structure representing the Symbian platform
calling thread, for example to perform exception trapping. Some possibilities
for the data transfer mechanism are: </p> <ul>
<li id="GUID-96A247AA-BA1C-50E5-8400-5487DFF5991D"><p>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. </p> </li>
<li id="GUID-1D2B6085-7B3A-51EF-BFF6-865D4AF94E5A"><p>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. </p> </li>
</ul> </section>
<section id="GUID-09CC8168-50FD-49ED-8376-05C00C3243FA"><title>Synchronisation/communication primitives</title> <p>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. </p> <p><b>Blocking
a thread on a wait object</b> </p> <p>To make a thread block on a new type
of wait object, call the nanokernel function <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-72F2E4E0-B498-32D2-BB24-E79AC66EFDDB"><apiname>Kern::NanoBlock()</apiname></xref>,
passing the maximum time for which the thread should block, the new N-state
value, and a pointer to the wait object. </p> <p>Use the <codeph>TPriListLink</codeph> base
class of <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita"><apiname>NThreadBase</apiname></xref> to attach the thread to a list of
threads waiting on the object. Note that this must be done after calling <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-72F2E4E0-B498-32D2-BB24-E79AC66EFDDB"><apiname>Kern::NanoBlock()</apiname></xref>.
As preemption is disabled before this function is called, a reschedule will
not occur immediately, but will be deferred until preemption is reenabled. </p> <p id="GUID-5017FB0A-5C1E-5C88-9315-E12C12D9639F"><b>State handler</b> </p> <p>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: </p> <codeblock id="GUID-31E807F7-250B-552D-8480-5F282C151565" xml:space="preserve">void StateHandler(NThread* aThread, TInt aOp, TInt aParam);</codeblock> <ul>
<li id="GUID-B8ECADB3-0345-56CB-8C7A-6D4E8CE15726"><p> <codeph> aThread</codeph> is
a pointer to the thread involved. </p> </li>
<li id="GUID-711957A1-4D01-5F8B-BF67-70EB8F39D20B"><p> <codeph> aOp</codeph> is
one of the <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-FF52640A-87C9-319B-B4C6-F6B860171229"><apiname>NThreadBase::NThreadOperation</apiname></xref> values that indicates
which operation is being performed on the thread. </p> </li>
<li id="GUID-FF54386A-D163-5F53-B230-296BE402C9E6"><p> <codeph> aParam</codeph> is
a parameter that depends on <codeph>aOp</codeph>. </p> </li>
</ul> <p>Note that the state handler is always called with preemption disabled. </p> <p>The
possible values of <codeph>aOp</codeph> are: </p> <table id="GUID-F4372C47-F491-55E2-B06E-2C68628B5BC5">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <codeph>aOp</codeph> value </p> </entry>
<entry><p>Description </p> </entry>
</row>
<row>
<entry><p> <codeph>ESuspend</codeph>  </p> </entry>
<entry><p>Called if the thread is suspended while not in a critical section
and not holding a fast mutex. Called in whichever context <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-FF94D458-C2D0-3D20-ADD6-AAE68A3296C3"><apiname>NThreadBase::Suspend()</apiname></xref> is
called from. </p> <p> <codeph>aParam</codeph> contains the requested suspension
count. </p> </entry>
</row>
<row>
<entry><p> <codeph>EResume</codeph>  </p> </entry>
<entry><p>Called if the thread is resumed while actually suspended, and the
last suspension has been removed. Called in whichever context <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-C0A6E734-7DE6-37B9-AAB2-A2A0E2664731"><apiname>NThreadBase::Resume()</apiname></xref> is
called from. </p> <p> <codeph>aParam</codeph> contains no additional information. </p> </entry>
</row>
<row>
<entry><p> <codeph>EForceResume</codeph>  </p> </entry>
<entry><p>Called if the thread has all suspensions cancelled while actually
suspended. Called in whichever context <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-BE92FBC3-A7D9-3576-A1A9-7BBA6EE64226"><apiname>NThreadBase::ForceResume()</apiname></xref> is
called from. </p> <p> <codeph>aParam</codeph> contains no additional information. </p> </entry>
</row>
<row>
<entry><p> <codeph>ERelease</codeph>  </p> </entry>
<entry><p>Called if the thread is released from its wait. This call should
make the thread ready if necessary. Called in whichever context <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-1B24AC4E-C4A1-32AE-BC6E-DC3131116EF8"><apiname>NThreadBase::Release()</apiname></xref> was
called from. </p> <p> <codeph>aParam</codeph> is the value passed into <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-1B24AC4E-C4A1-32AE-BC6E-DC3131116EF8"><apiname>NThreadBase::Release()</apiname></xref> to
be used as a return code. </p> <p>If <codeph>aParam</codeph> is non-negative,
this indicates normal termination of the wait condition. </p> <p>If <codeph>aParam</codeph> is
negative, it indicates early or abnormal termination of the wait; in this
case the wait object should be rolled back as if the wait had never occurred.
For example, a semaphore's count needs to be incremented if <codeph>aParam</codeph> is
negative, since in that case the waiting thread never acquired the semaphore. </p> </entry>
</row>
<row>
<entry><p> <codeph>EChangePriority</codeph>  </p> </entry>
<entry><p>Called if the thread's priority is changed. Called in whichever
context <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-A92E7B01-C1D0-3997-B3E1-2E54229FFA75"><apiname>NThreadBase::SetPriority()</apiname></xref> is called from. This
function should set the <codeph>iPriority</codeph> field of the thread, after
doing any necessary priority queue manipulations. </p> <p> <codeph>aParam</codeph> contains
the new priority. </p> </entry>
</row>
<row>
<entry><p> <codeph>ELeaveCS</codeph>  </p> </entry>
<entry><p>Called in the context of the thread concerned if the thread calls <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-2C897BA5-2BD7-3ABA-9F2B-F0B1AC14D1AE"><apiname>NKern::ThreadLeaveCS()</apiname></xref> with
an unknown <codeph>iCsFunction</codeph> that is negative but not equal to <codeph>ECsExitPending</codeph>. </p> <p>aParam
contains the value of <codeph>iCsFunction</codeph>. </p> </entry>
</row>
<row>
<entry><p> <codeph>ETimeout</codeph>  </p> </entry>
<entry><p>Called if the thread's wait time-out expires and no time-out handler
is defined for that thread. Called in the context of the nanokernel timer
thread (DfcThread1). This should cancel the wait and arrange for an appropriate
error code to be returned. The handler for this condition will usually do
the same thing as the handler for <codeph>ERelease</codeph> with a parameter
of <xref href="GUID-BAC2386E-8168-3CDB-9F9F-180319EF6920.dita"><apiname>KErrTimedOut</apiname></xref>. </p> <p> <codeph>aParam</codeph> contains
no additional information. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>See the code in <filepath>...\e32\personality\example\...</filepath> for
practical examples. </p> <p><b>Releasing
the thread</b> </p> <p>When a thread's wait condition is resolved, the nanokernel
function <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-1B24AC4E-C4A1-32AE-BC6E-DC3131116EF8"><apiname>NThreadBase::Release()</apiname></xref> should be called. This
takes a single <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> parameter. </p> <p>The parameter is
usually <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>, 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. </p> <p> <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-1B24AC4E-C4A1-32AE-BC6E-DC3131116EF8"><apiname>NThreadBase::Release()</apiname></xref> should
be called with preemption disabled. It performs the following actions: </p> <ul>
<li id="GUID-6697024F-ED05-5C5A-A834-EA89402AE173"><p>sets the <codeph>NThreadBase::iWaitObj</codeph> field
to NULL </p> </li>
<li id="GUID-C1DF3120-4FD3-5B6C-90F8-6D8C7CAD0B88"><p>cancels the wait timer
if it is still running </p> </li>
<li id="GUID-6E346E2B-4F94-56FB-8372-8260BCC4CA8C"><p>stores the supplied
return code in <codeph>NThreadBase::iReturnCode</codeph>  </p> </li>
<li id="GUID-3AF577DB-41A9-553E-9EFD-6F0DA2FADCEA"><p>calls the <xref href="GUID-42F8FA5A-BBE4-50DE-917E-D05755019FEC.dita#GUID-42F8FA5A-BBE4-50DE-917E-D05755019FEC/GUID-5017FB0A-5C1E-5C88-9315-E12C12D9639F">state handler</xref> passing <codeph>ERelease</codeph> 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 <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-82E43D79-721D-31A9-B9ED-1277F2300914"><apiname>NThreadBase::CheckSuspendThenReady()</apiname></xref> to
make the thread ready again if necessary. </p> </li>
</ul> </section>
<section id="GUID-1FF1CFE8-41E3-4912-AE28-39D289442BB7"><title>Thread scheduling following a hardware interrupt</title> <p>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. </p> <p>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 <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-9542588A-2920-3CB0-A2C0-A55FA6BC29A2"><apiname>NKern::CurrentContext()</apiname></xref>,
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. </p> <p>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 <codeph>Interrupt::Bind()</codeph> 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 <xref href="GUID-3C34724F-B476-5329-B0B1-6D5A34294979.dita">Interrupt
Dispatcher Tutorial</xref>. </p> </section>
</conbody><related-links>
<link href="GUID-5B1D8D9C-90EF-5FCC-8D7D-01B13D6C2E68.dita"><linktext>Nanokernel</linktext>
</link>
<link href="GUID-2700AAC8-A034-5E7D-B0E0-26B49E68BB18.dita"><linktext>Personality
Layer for Real                 Time Applications</linktext></link>
</related-links></concept>