<?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-2700AAC8-A034-5E7D-B0E0-26B49E68BB18.dita">
<linktext>Personality Layer for Real                 Time Applications</linktext>
</link>
</related-links></concept>