<?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-49379616-C235-598D-AE43-668998AD072B" xml:lang="en"><title>Process,
Thread, Stack and Memory Attributes</title><shortdesc>Reference for users of the debug monitor tool to the attributes
of Kernel objects and memory structure. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<ul>
<li id="GUID-98737E3D-1A08-53ED-89C5-C0398E02C509"><p> <xref href="GUID-49379616-C235-598D-AE43-668998AD072B.dita#GUID-49379616-C235-598D-AE43-668998AD072B/GUID-4D7F6A1F-3120-5547-B027-344C08A01D83">Process and thread priorities</xref>  </p> </li>
<li id="GUID-F08BDD05-90C3-544E-8C41-788A556F799F"><p> <xref href="GUID-49379616-C235-598D-AE43-668998AD072B.dita#GUID-49379616-C235-598D-AE43-668998AD072B/GUID-DDC45F0A-6B62-5EE6-9E42-D21F07BCF4B4">Thread state summary</xref>  </p> </li>
<li id="GUID-5C39B7CB-D8B1-5DD4-BD62-76595A3B2EB4"><p> <xref href="GUID-49379616-C235-598D-AE43-668998AD072B.dita#GUID-49379616-C235-598D-AE43-668998AD072B/GUID-C6296C07-220E-5EB8-9E12-F7D63AB4B181">Thread and process exit information summary</xref>  </p> </li>
<li id="GUID-4F26D9D7-D335-5332-899D-E4DA6D8F4819"><p> <xref href="GUID-49379616-C235-598D-AE43-668998AD072B.dita#GUID-49379616-C235-598D-AE43-668998AD072B/GUID-68CF9014-4922-56B9-9E53-AC5697F60E8E"> Critical threads and processes</xref>  </p> </li>
<li id="GUID-528E13A3-7E35-5153-87D6-C25CD3E90B6E"><p> <xref href="GUID-49379616-C235-598D-AE43-668998AD072B.dita#GUID-49379616-C235-598D-AE43-668998AD072B/GUID-6530D514-A6CC-5AE9-AA97-C223B2189A09">Kernel calls and thread context</xref>  </p> </li>
<li id="GUID-4D0AC539-A105-5D26-896C-E32A2863213B"><p> <xref href="GUID-49379616-C235-598D-AE43-668998AD072B.dita#GUID-49379616-C235-598D-AE43-668998AD072B/GUID-5A573FEB-A274-5C0F-A6B6-87D5BAD8A21C">Stacks</xref>  </p> </li>
<li id="GUID-3A45E908-3D72-5871-9DEB-454F75A084BE"><p> <xref href="GUID-49379616-C235-598D-AE43-668998AD072B.dita#GUID-49379616-C235-598D-AE43-668998AD072B/GUID-E3F102A4-D187-5BC9-BE97-9F8447A5DB45">Virtual memory and run addresses</xref>  </p> </li>
</ul>
<section id="GUID-4D7F6A1F-3120-5547-B027-344C08A01D83"><title>Process and
thread priorities</title> <p>Internally the scheduler always deals with nanokernel
threads, <codeph>NThread</codeph> objects, and their associated priority between
0 (lowest) and 63 (highest). In general, a thread with a higher priority that
is ready to run will always run in preference to threads with a lower priority.
The only exception is where a higher priority thread waits on a nanokernel
fast mutex held by a lower priority thread. In this case, the higher priority
thread will yield to the lower priority thread holding the mutex. </p> <p>A
Symbian platform thread, a <codeph>DThread</codeph> object, has an embedded <codeph>NThread</codeph>,
which enables it to be scheduled by the nanokernel. </p> <p>There are two
ways of setting a priority for Symbian platform thread: </p> <ul>
<li id="GUID-8568544D-49F4-5D52-8E38-28A09058FB04"><p>using the two-level
priority scheme </p> </li>
<li id="GUID-F3D2BAF8-9C95-59C3-A50E-150A7BDA4EE7"><p>using an absolute priority. </p> </li>
</ul> <p><b>The
two level priority scheme</b> </p> <p>In this scheme, a Symbian platform thread
priority is relative to the priority of its owning process. By default, Symbian
platform threads inherit the priority of their owning process when they are
created. This priority can be raised or lowered relative to the process priority
- this just sets the thread’s priority to the process priority plus or minus
a specified priority weighting. If the priority of the process is changed,
the priority of its threads will change relative to other threads in the system
but will remain the same relative to each other. </p> <p>The default priority
of a process is <codeph>EPriorityForgeround</codeph>, which is an absolute
priority of 350. Threads by default are created with relative priority <codeph>EPriorityNormal</codeph> which
sets them to the same priority as the owning process. The window server lowers
the priority of background UI processes to <codeph>EPriorityBackground</codeph> (250). </p> <p>The
NULL thread, also known as the idle thread, runs at priority 0, and means
that it will only run when there are no other threads ready to run. </p> <p>Symbian
platform thread priorities map onto <codeph>NThread</codeph> priorities in
the range 1 to 31 as shown in the table below. </p> <table id="GUID-E61C3B76-B47D-5B9B-A469-A369D5AB4AFC">
<tgroup cols="8"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><colspec colname="col4"/><colspec colname="col5"/><colspec colname="col6"/><colspec colname="col7"/>
<tbody>
<row>
<entry><p> <b>Thread priority</b>  </p> </entry>
<entry><p>Idle </p> </entry>
<entry><p>Much Less </p> </entry>
<entry><p>Less </p> </entry>
<entry><p>Normal </p> </entry>
<entry><p>More </p> </entry>
<entry><p>Much More </p> </entry>
<entry><p>Real Time </p> </entry>
</row>
<row>
<entry><p> <b>Process priority</b>  </p> </entry>
<entry><p> </p> </entry>
<entry><p> </p> </entry>
<entry><p> </p> </entry>
<entry><p> </p> </entry>
<entry><p> </p> </entry>
<entry><p> </p> </entry>
<entry><p> </p> </entry>
</row>
<row>
<entry><p>Low </p> </entry>
<entry><p>1</p> </entry>
<entry><p>1</p> </entry>
<entry><p>2</p> </entry>
<entry><p>3</p> </entry>
<entry><p>4</p> </entry>
<entry><p>5</p> </entry>
<entry><p>22 </p> </entry>
</row>
<row>
<entry><p>Background </p> </entry>
<entry><p>3</p> </entry>
<entry><p>5</p> </entry>
<entry><p>6</p> </entry>
<entry><p>7</p> </entry>
<entry><p>8</p> </entry>
<entry><p>9</p> </entry>
<entry><p>22 </p> </entry>
</row>
<row>
<entry><p>Foreground </p> </entry>
<entry><p>3</p> </entry>
<entry><p>10 </p> </entry>
<entry><p>11 </p> </entry>
<entry><p>12 </p> </entry>
<entry><p>13 </p> </entry>
<entry><p>14 </p> </entry>
<entry><p>22 </p> </entry>
</row>
<row>
<entry><p>High </p> </entry>
<entry><p>3</p> </entry>
<entry><p>17 </p> </entry>
<entry><p>18 </p> </entry>
<entry><p>19 </p> </entry>
<entry><p>20 </p> </entry>
<entry><p>22 </p> </entry>
<entry><p>23 </p> </entry>
</row>
<row>
<entry><p>SystemServer1 </p> </entry>
<entry><p>9</p> </entry>
<entry><p>15 </p> </entry>
<entry><p>16 </p> </entry>
<entry><p>21 </p> </entry>
<entry><p>23 </p> </entry>
<entry><p>25 </p> </entry>
<entry><p>28 </p> </entry>
</row>
<row>
<entry><p>SystemServer2 </p> </entry>
<entry><p>9</p> </entry>
<entry><p>15 </p> </entry>
<entry><p>16 </p> </entry>
<entry><p>21 </p> </entry>
<entry><p>23 </p> </entry>
<entry><p>25 </p> </entry>
<entry><p>28 </p> </entry>
</row>
<row>
<entry><p>SystemServer3 </p> </entry>
<entry><p>9</p> </entry>
<entry><p>15 </p> </entry>
<entry><p>16 </p> </entry>
<entry><p>21 </p> </entry>
<entry><p>23 </p> </entry>
<entry><p>25 </p> </entry>
<entry><p>28 </p> </entry>
</row>
<row>
<entry><p>RealTimeServer </p> </entry>
<entry><p>18 </p> </entry>
<entry><p>26 </p> </entry>
<entry><p>27 </p> </entry>
<entry><p>28 </p> </entry>
<entry><p>29 </p> </entry>
<entry><p>30 </p> </entry>
<entry><p>31 </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>where: </p> <ul>
<li id="GUID-4315CEE2-2717-5E8F-A8F7-885C621A95B6"><p>the process priority
values are defined by the internal Symbian platform enum <codeph>TProcPriority</codeph>,
defined in <filepath>...\e32\include\kernel\kern_priv.h</filepath>. The symbols
in the table correspond to the symbols in the enum. </p> </li>
<li id="GUID-89D0D7FA-4B17-5753-898A-26C1B20EE59B"><p>the thread priority
values are defined by the internal Symbian platform enum <codeph>TThrdPriority</codeph>,
defined in <filepath>...\e32\include\kernel\kern_priv.h</filepath>. The symbols
in the table correspond to the symbols in the enum. </p> </li>
</ul> <p><b>Absolute
priority scheme</b> </p> <p>It is possible to set an absolute priority that
is not relative to the process priority; it is not affected by changes in
the process priority. </p> </section>
<section id="GUID-DDC45F0A-6B62-5EE6-9E42-D21F07BCF4B4"><title>Thread state
summary</title> <p>This is a brief summary about nanokernel thread states
and Symbian platform thread states. </p> <p><b>Nanokernel
thread states</b> </p> <p>The state of a nanokernel thread is referred to
as the NState (or N-state). This is to disambiguate it from any other state,
such as the state of a Symbian platform thread (referred to as the MState
or M-state). </p> <p>The states of a nanokernel thread are defined by the
values of the <xref href="GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC.dita#GUID-379D9320-AC3C-3206-8A5D-EE6E5983EBDC/GUID-2184305D-18EF-3322-9276-20F8A4253455"><apiname>NThreadBase::NThreadState</apiname></xref> enumeration. </p> <p><b>Symbian platform thread states</b> </p> <p>The state of a Symbian platform
thread is referred to as the MState (or M_state). This is in addition to the
nanokernel N-state, and tracks threads waiting on Symbian platform synchronization
objects. The <codeph>DThread</codeph> class representing a Symbian platform
thread is internal to Symbian, but the following table defines its possible
states. The values in the left-hand column are the enumerators of the internal
enumeration <codeph>DThread::TThreadState</codeph>. </p> <table id="GUID-C6ACF17D-2E18-5FCB-9383-BAE57D8F420F">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <codeph>ECreated</codeph>  </p> </entry>
<entry><p>The initial state of all Symbian platform threads. It is a transient
state; the thread starts in this state when the <codeph>DThread</codeph> object
is created, and stays in that state until it is ready to be resumed, typically
when DLL linkage and memory allocation is complete. At this point, the state
will change to <codeph>EReady</codeph>. </p> </entry>
</row>
<row>
<entry><p> <codeph>EDead</codeph>  </p> </entry>
<entry><p>This is the final state of a Symbian platform thread. A thread enters
this state when it reaches the end of its exit handler, just before the nanokernel
terminates it. In effect, the thread has exited but has not yet been deleted. </p> </entry>
</row>
<row>
<entry><p> <codeph>EReady</codeph>  </p> </entry>
<entry><p>This indicates that the thread is not waiting on, or attached to
any Symbian platform kernel wait object. It does not necessarily imply that
the thread is actually ready to run - this is indicated by the N-state. For
example, a thread that is explicitly suspended or waiting on a nanokernel
wait object (generally a fast semaphore) still has a READY M-state provided
that it is not attached to any Symbian platform wait object. </p> </entry>
</row>
<row>
<entry><p> <codeph>EWaitSemaphore</codeph>  </p> </entry>
<entry><p>This indicates that the thread is currently blocked waiting for
a Symbian platform semaphore, and is enqueued on the semaphore’s wait queue.
The thread’s <codeph>DThread::iWaitObj</codeph> field points to the semaphore. </p> <p>For
example, this is the case if the thread calls <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-50223158-D05D-33FE-A3DD-FFA9E2F464FF"><apiname>User::WaitForRequest()</apiname></xref> or <xref href="GUID-AED27A76-3645-3A04-B80D-10473D9C5A27.dita#GUID-AED27A76-3645-3A04-B80D-10473D9C5A27/GUID-68F18434-4758-33BA-9959-1F92A50651A2"><apiname>RSemaphore::Wait()</apiname></xref>  </p> </entry>
</row>
<row>
<entry><p> <codeph>EWaitSemaphoreSuspended</codeph>  </p> </entry>
<entry><p>This indicates that the thread has been explicitly suspended after
blocking on a Symbian platform semaphore, and is enqueued on the semaphore’s
suspended queue. The thread’s <codeph>DThread::iWaitObj</codeph> field points
to the semaphore. </p> </entry>
</row>
<row>
<entry><p> <codeph>EWaitMutex</codeph>  </p> </entry>
<entry><p>This indicates that the thread is currently blocked waiting for
a Symbian platform mutex, and is enqueued on the mutex wait queue. The thread’s <codeph>DThread::iWaitObj</codeph> field
points to the mutex. </p> </entry>
</row>
<row>
<entry><p> <codeph>EWaitMutexSuspended</codeph>  </p> </entry>
<entry><p>This indicates that the thread has been explicitly suspended after
blocking on a Symbian platform mutex, and is enqueued on the mutex suspended
queue. The thread’s <codeph>DThread::iWaitObj</codeph> field points to the
mutex. </p> </entry>
</row>
<row>
<entry><p> <codeph>EHoldMutexPending</codeph>  </p> </entry>
<entry><p>This indicates that the thread has been woken up from the EWaitMutex
state but has not yet claimed the mutex. The thread is enqueued on the mutex
pending queue and the thread’s <codeph>DThread::iWaitObj</codeph> field points
to the mutex. </p> </entry>
</row>
<row>
<entry><p> <codeph>EWaitCondVar</codeph>  </p> </entry>
<entry><p>This indicates that the thread is waiting on a condition variable. </p> </entry>
</row>
<row>
<entry><p> <codeph>EWaitCondVarSuspended</codeph>  </p> </entry>
<entry><p>This indicates that the thread is suspended while waiting on a condition
variable. </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section id="GUID-C6296C07-220E-5EB8-9E12-F7D63AB4B181"><title>Thread and
process exit information summary</title> <p>User threads and processes have
“exit information”. When a thread or process terminates the reason for the
termination is found in the exit information. For example, a panic will store
the panic category and reason in the exit information. Exit information has
three parts: the exit type, exit reason and exit category. </p> <p>Exit type
is defined by the <xref href="GUID-0296BFC6-7F7C-3259-AF21-7E9B5C304B24.dita"><apiname>TExitType</apiname></xref> enum. </p> <p>When a thread
or process is created, its exit type is set to 3. An exit type of 3 indicates
that the thread is still active, though not necessarily running. If the thread
terminates for any reason, then the exit type is changed to reflect the cause
of the exit. </p> <p>Once the thread or process has exited, the exit reason
and exit type fields will contain useful information. The contents depends
on the type of exit. </p> <p>Note that if the main thread in a process exits,
then the process will exit with the same exit information as the thread. </p> <p><b>Exit category: Terminate</b> </p> <p>if <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-CE11A762-AF52-3122-86C8-C2F362AEF764"><apiname>RThread::Terminate()</apiname></xref> or <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-3DD41FD4-F389-340F-8E18-8FDEBC953251"><apiname>RProcess::Terminate()</apiname></xref> is
called, then the exit category is <codeph>Terminate</codeph>, and the exit
reason is the value of the <codeph>aReason</codeph> argument passed to these
functions. </p> <p><b>Exit
category: Kill</b> </p> <p>If <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-1F717486-784A-32B9-A048-EE4F2450F8C8"><apiname>RThread::Kill()</apiname></xref> or <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-8E87D3AE-E3F0-34DD-98C6-71B0D0D55FB8"><apiname>RProcess::Kill()</apiname></xref> is
called, then the exit category is <codeph>Kill</codeph>, and the exit reason
is the value of the <codeph>aReason</codeph> argument passed to these functions. </p> <p><b>Exit category: panic</b> </p> <p>If a thread panics, then the exit category
is <codeph>panic</codeph>, and the exit reason is the panic number. For example
a USER-19 panic would give the following exit information: </p> <codeblock id="GUID-ACC94269-E06E-5C7F-ACAF-74764FE21A0F" xml:space="preserve">exit type = 2
exit category = “USER”
exit reason = 19
</codeblock> </section>
<section id="GUID-68CF9014-4922-56B9-9E53-AC5697F60E8E"><title> Critical threads
and processes</title> <p>Marking a thread or process as “system critical”
means that it is an integral and essential part of the system, for example,
the file server. In effect the thread or process is being declared necessary
for correct functioning of the device. If a system critical thread exits or
panics then the device will reboot; during development it will enter the debug
monitor. A thread can be set as process critical, which means that if it panics
the process will be panicked. </p> </section>
<section id="GUID-6530D514-A6CC-5AE9-AA97-C223B2189A09"><title> Kernel calls
and thread context</title> <p>When a user thread makes a call into any kernel
code, the kernel code continues to run in the context of the user thread.
This applies to device driver code. </p> <p>The stack is swapped to a kernel-side
stack and the permissions of the thread are increased to kernel privilege,
but otherwise the user thread is still running. Each thread has a small kernel
stack used to handle kernel calls – it would be dangerous to continue using
the normal thread stack in case it overflows. Some calls are handled in this
state, others – typically device drivers – will post a message to a kernel
side thread to carry out the request. </p> </section>
<section id="GUID-5A573FEB-A274-5C0F-A6B6-87D5BAD8A21C"><title>Stacks</title> <p>When
a process is created, a chunk is allocated to hold the process executable's <codeph>.data</codeph> section
(initialised data) and <codeph>.bss</codeph> section (zero filled data). Sufficient
space (default 2Mb) is also reserved as user-side stack space for threads
that run in that process. </p> <p>By default, each thread is allocated 8k
of user-side stack space. A guard of 8k is also allocated. </p> <p>The stack
area follows the <codeph>.data</codeph> and <codeph>.bss</codeph> sections,
and each thread's user side stack follows. On ARM processors the stack is
descending, so that as items are added to the stack, the stack pointer is
decremented. This means that if the stack overflows, the stack pointer points
into the guard area and causes a processor exception, with the result that
the kernel panics the thread. </p> <fig id="GUID-C87444AA-A8DC-5A5C-B2E6-B15FA69B6CE1">
<image href="GUID-DD0DA06D-4180-54F1-8807-A7BF31D6A1F1_d0e70450_href.png" placement="inline"/>
</fig> <p>Return addresses are stored by pushing them on to the stack so at
any point you can trace through the stack looking at the saved return addresses
to see the chain of function calls up to the present function. </p> <p>The
size of the user-side stack space has an indirect effect on the number of
threads that a process can have. There are other factors involved, but this
is an important one. The limit is a consequence of the fact that a process
can have a maximum of 16 chunks. This means that if threads within a process
can share a heap (allocated from a single chunk), then it is possible to have
a maximum of 128 threads per process [2Mb/(8K + 8K)]. More threads may be
possible if you allow only 4K of stack per thread. </p> <p>Apart from the
kernel stack attached to each thread, the kernel also maintains stacks that
are used during processing of interrupts, exceptions and certain CPU states.
Interrupts and exceptions can occur at any time, with the system in any state,
and it would be dangerous to allow them to use the current stack which may
not even be valid or may overflow and panic the kernel. The kernel stacks
are guaranteed to be large enough for all interrupt and exception processing. </p> </section>
<section id="GUID-E3F102A4-D187-5BC9-BE97-9F8447A5DB45"><title>Virtual memory
and run addresses</title> <p>Symbian platform devices have an MMU which is
used to map the addresses seen by running code to real addresses of memory
and I/O. The MMU in effect creates a virtual memory map, allowing scattered
blocks of RAM to appear contiguous, or for a section of memory to appear at
different addresses in different processes, or not at all. </p> <p>Symbian
platform uses the MMU to provide memory protection between processes, to allow
sharing of memory, efficient allocation of RAM and to make all processes “see”
the same memory layout. Three different memory models are supported by Symbian
platform on ARM CPUs: </p> <ul>
<li id="GUID-456A3D12-E1E0-5289-B5EB-2E3A47F07684"><p>moving model: this is
the model familiar from EKA1 where processes are moved to a run-address in
low memory when executing and moved back to a home-address in high memory
when not running. </p> </li>
<li id="GUID-3A5BCC68-7BAC-58B8-9727-54A880A7CED3"><p>direct model: this is
used when the CPU does not have an MMU, or is emulating a system without an
MMU. Not normally used, but occasionally useful for development boards </p> </li>
<li id="GUID-7CB07322-B33E-5723-975C-6D2442B924F9"><p>multiple model: only
supported in ARM architecture V6 and above, each process has its own set of
MMU tables. A context switch changes the current MMU table to the new thread’s
table, instead of moving memory about in a single table as with moving model. </p> </li>
</ul> <p><b>Fixed
processes</b> </p> <p>For ARM architectures with a virtually-tagged cache,
fixed processes avoid the need to flush the cache on context switches by keeping
all the code and data at a fixed address. This implies that there can only
ever be one instance of each fixed process because the data chunk address
cannot be changed. </p> <p>Important servers such as the file server and window
server are fixed. </p> <p>There is no limit to the number of fixed processes
that can be supported. The kernel will attempt to use ARM domains for fixed
process protection, but there are a limited number of domains so when they
are exhausted normal MMU techniques will be used. Domains are slightly faster
in a context switch but this is negligible compared to the real purpose of
the fixed process in avoiding the cache flush. </p> </section>
</conbody></concept>