<?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-178E140F-BB15-5A82-99A6-D1BC0E11E018" xml:lang="en"><title>Kernel-side
Messages</title><shortdesc>Kernel-side messages are a means of communication between Symbian
platform threads executing kernel-side code. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Typically, they are used by device drivers to communicate between a client
thread, usually a user thread, and a kernel thread running the actual device
driver code. </p>
<p>The mechanism consists of a message, containing data, and a queue that
is associated with a DFC. The DFC runs in order to deal with each message. </p>
<p>A kernel-side message is represented by a <xref href="GUID-3FDD1B46-1427-3F1C-99D2-AD8446658E5A.dita"><apiname>TMessageBase</apiname></xref> object,
that allows a single 32-bit argument to be passed, and a single 32-bit return
value. In general, more arguments can be passed by deriving classes from <codeph>TMessageBase</codeph>.
In practice, each Symbian platform thread has a <xref href="GUID-D43CB8FA-C212-3B56-AD16-9F1D69DA7551.dita"><apiname>TThreadMessage</apiname></xref> object
embedded within it. <codeph>TThreadMessage</codeph> is derived from <codeph>TMessageBase</codeph>,
and contains space for 10 extra 32-bit arguments. These objects are used for
communication with device driver threads. </p>
<p>Both <codeph>TMessageBase</codeph> and <codeph>TThreadMessage</codeph> are
defined in <filepath>...\kernel\kernel.h</filepath>, which is exported to <filepath>epoc32\include\kernel</filepath>. </p>
<fig id="GUID-230AECE3-5006-543A-9F4F-088C62E14E6D">
<title>Message threads and queues</title>
<image href="GUID-D8A3C18B-A107-5557-B882-CD6CDD0F0F1D_d0e76208_href.png" placement="inline"/>
</fig>
<p> <xref href="GUID-CAAD5B87-CEE7-30E8-BA6A-08F9407C4C20.dita"><apiname>SDblQueLink</apiname></xref> is simply an object that allows a message
to be linked to another in the form of a doubly-linked list. </p>
<p>The message queue is represented by a <xref href="GUID-382DD935-E9D7-3E00-88B2-B28A89CAD4FB.dita"><apiname>TMessageQue</apiname></xref> object,
which consists of a DFC plus a doubly-linked list of received messages. The
DFC is attached to the receiving thread’s DFC queue and it runs whenever a
message becomes available for processing. </p>
<p> <codeph>TMessageQue</codeph> is defined in <filepath>...include\kernel\kernel.h</filepath>,
which is exported to <filepath>epoc32\include\kernel</filepath>; <codeph>SDblQueLink</codeph> is
defined in <filepath>...\nkern\nklib.h</filepath>, which is exported to <filepath>epoc32\include\nkern</filepath>. </p>
<p>The following shows, in simple terms, the relationship between messages
and the message queues: </p>
<fig id="GUID-2D1F4468-5208-51F1-9E48-B5E9DC44B6B2">
<title>Relationship between messages and message queues</title>
<image href="GUID-DA7751A1-4EC5-5FBA-A42B-E254133A1D82_d0e76254_href.png" placement="inline"/>
</fig>
<p>When a message is sent to the queue, either: </p>
<ul>
<li id="GUID-08445948-588F-512B-BA6C-D641F0DDF572"><p>the message is accepted
immediately, and the receiving thread’s DFC runs. This will happen if the
message queue is ready to receive, which will be the case if the message queue
is empty and the receiving thread has requested the next message. </p> </li>
</ul>
<p>or </p>
<ul>
<li id="GUID-BF81268D-31A4-50D6-A43A-F2C4556B367F"><p>the message is placed
on the delivered message queue, and the DFC does not run. This will happen
if there are other messages queued ahead of this one or if the receiving thread
has not (yet) requested another message. </p> </li>
</ul>
<p>A kernel-side message may be in one of three states at any time: </p>
<ul>
<li id="GUID-C9CF11B5-0B76-5F8A-87CC-75DF595F657E"><p>FREE - represented by
the <xref href="GUID-3FDD1B46-1427-3F1C-99D2-AD8446658E5A.dita#GUID-3FDD1B46-1427-3F1C-99D2-AD8446658E5A/GUID-BBF5D5BD-BC64-3EC8-82F4-A7A3EB1FF043"><apiname>TMessageBase::EFree</apiname></xref> enum value. This indicates that
the message is not currently in use. </p> </li>
<li id="GUID-924008AC-58F7-5979-95FA-EC11EC5B5D07"><p>DELIVERED - represented
by the <xref href="GUID-3FDD1B46-1427-3F1C-99D2-AD8446658E5A.dita#GUID-3FDD1B46-1427-3F1C-99D2-AD8446658E5A/GUID-828BA7EF-8962-3CEA-B322-7D92E368957B"><apiname>TMessageBase::EDelivered</apiname></xref> enum value. This indicates
that the message is attached to a message queue but is not currently in use
by the receiving thread. It may be removed from the queue and discarded with
no ill effects on the receiving thread. The client thread pointer may not
be used while the message is in this state. </p> </li>
<li id="GUID-57807061-A767-59A4-9D10-6A08A06DA214"><p>ACCEPTED - represented
by the <xref href="GUID-3FDD1B46-1427-3F1C-99D2-AD8446658E5A.dita#GUID-3FDD1B46-1427-3F1C-99D2-AD8446658E5A/GUID-D4BB85D9-DE00-3BD8-8A9A-4D40C031A94C"><apiname>TMessageBase::EAccepted</apiname></xref> enum value. This indicates
that the message is not attached to a message queue but is currently in use
by the receiving thread. The message may not be discarded. </p> </li>
</ul>
<p>Transitions between these states, including adding the message to, and
removing the message from a message queue, occur under the protection of the
global <xref href="GUID-382DD935-E9D7-3E00-88B2-B28A89CAD4FB.dita#GUID-382DD935-E9D7-3E00-88B2-B28A89CAD4FB/GUID-1134F81A-4427-3B7E-8BF3-1F2DB6698261"><apiname>TMessageQue::MsgLock</apiname></xref> fast mutex. The use of a mutex
is necessary to avoid queue corruption, for example, when multiple threads
are sending messages to the same message queue at the same time. The use of
a fast mutex means that message passing operations may only be invoked from
a thread context. </p>
<p>Kernel-side messages may be sent either synchronously or asynchronously.
Each <xref href="GUID-3FDD1B46-1427-3F1C-99D2-AD8446658E5A.dita"><apiname>TMessageBase</apiname></xref> object contains an <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref> on
which the sending thread will wait after sending a synchronous message. The
semaphore is signalled by the receiving thread after the message has been
processed and the completion code has been written in. The sending thread
is then released and picks up the return code. The <codeph>NFastSemaphore</codeph> also
contains a pointer to the sending <xref href="GUID-187D314F-1115-3671-AC46-37AEC5DFB2AC.dita"><apiname>NThread</apiname></xref>; this serves
to identify the sending thread and is therefore set up for both synchronous
and asynchronous message send. Note that this pointer is reference counted
- the access count of the originating <xref href="GUID-38D1534C-AA01-33AF-9937-CDD818A85F97.dita"><apiname>DThread</apiname></xref> is incremented
when the message is sent. This prevents the sending <codeph>DThread</codeph> object
disappearing if the thread terminates unexpectedly. When the message is completed
the extra access is removed asynchronously - the thread completing the message
will not need to delete the <codeph>DThread</codeph> itself. This is done
to avoid unpredictable execution times for message completion. Also note that
even messages sent asynchronously must be completed; this is required to set
the message state back to FREE and to remove the access count from the sending
thread. </p>
<p>The <xref href="GUID-D43CB8FA-C212-3B56-AD16-9F1D69DA7551.dita"><apiname>TThreadMessage</apiname></xref> objects embedded in Symbian platform
thread control blocks, <xref href="GUID-38D1534C-AA01-33AF-9937-CDD818A85F97.dita"><apiname>DThread</apiname></xref> objects, are always sent
synchronously - this ensures that one message per thread will always suffice.
In addition, these messages are cancelled if the corresponding thread terminates.
Cancelling an ACCEPTED message has no effect, but cancelling a DELIVERED message
will remove the message from the queue and also remove the access count held
by the message on the sending thread. Hence the sending thread pointer should
only be used by the receiving thread if the message is in the ACCEPTED state. </p>
</conbody></concept>