<?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-5BDE6462-E6CA-5738-A587-C7D875574789" xml:lang="en"><title>Static
Data</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Symbian developers used to PC operating systems, such as Windows, may be
used to using writeable static data (typically meaning global variables) in
DLLs. On the Symbian platform, this is possible, but not recommended, because
it is expensive in memory, and has limited support in the Symbian platform
Emulator. </p>
<p>This page describes writeable static data (WSD), the alternatives to using
WSD, and the costs and issues associated with its use. </p>
<section id="GUID-4ED4247C-0515-4DC0-A6AA-73D0DB4E0CE9"><title>Global writeable static data</title> <p>Global writeable static
data (WSD) is any per-process variable which exists for the lifetime of the
process. In practice, this means any globally scoped data: data that is declared
outside of a function, struct, or class, and function scoped static variables. </p> <codeblock id="GUID-C7F90E06-286B-5E64-B94A-7683AA0DA0FB" xml:space="preserve">TBufC&lt;20&gt; fileName; //WSD 
void SetFileName()
 {
 static Tint iCount; //WSD ...
 }</codeblock> <p>Sometimes writeable static data appears in a non-obvious
way. It is not always the case that <codeph>const</codeph> global variables
are read-only data rather than global writeable static data. This is true
for <codeph>const</codeph> objects with trivial constructors, such as integers.
However if a <codeph>const</codeph> class has a non-trivial constructor, the <codeph>const</codeph> object
will require a real variable and must be stored as WSD. For example: </p> <codeblock id="GUID-897D2E68-5AF6-5C69-A5AA-276A9FB89DEC" xml:space="preserve">const TInt myVariable=…; //OK – truly const
const TPtrC KSomeConstPtr=...; //NOT OK – non trivial constructor 
const TRgb KSomeConstCol=...; //NOT OK – non trivial constructor</codeblock> </section>
<section id="GUID-2FFCE39F-2387-4802-99B5-62B824D93667"><title>Support for global writeable static data on Symbian</title> <p>The
Symbian platform supports global writeable static data in EXEs on all versions
and handsets. </p> <p>Versions of Symbian based on the EKA2 kernel (8.1b and
later) support WSD in DLLs on target hardware. Versions 8.1a and earlier,
based on the EKA1 kernel, do not support global WSD in DLLs. </p> </section>
<section id="GUID-D684D28A-5534-4867-BB3F-6341FAC55713"><title>Clean up of global writeable static data</title> <p>Your program
must make sure that global writeable static data that the program allocates
is cleaned up. </p> <p>The clean up rules are as follows: </p> <ul>
<li id="GUID-1D25BA8E-1A8E-5502-8FD9-7F74DBB39EF4"><p>Your program must clean
up WSD objects that are defined in the process EXE or its statically-loaded
DLLs. When a process exits, the Symbian platform does not automatically call
the destructors of these WSD objects. </p> </li>
<li id="GUID-7F1EB6D6-2EAD-5318-A066-DC9128A48EAF"><p>Your program does not
need to clean up WSD objects defined in DLLs that the process has dynamically
loaded using <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita"><apiname>RLibrary</apiname></xref>. The Symbian platform automatically
calls destructors of these objects. </p> </li>
</ul> </section>
<section id="GUID-3458566D-FEC2-4ED2-AFB8-3C61F693FBEF"><title>Alternatives to using global writeable static data</title> <p>Native
Symbian platform C++ code rarely uses WSD. </p> <p>However, code ported from
other operating systems may contain large amounts of static data. For example,
code written in the C programming language often makes use of WSD as the "glue"
between C function calls. </p> <p>In EKA1, WSD is not supported, so there
is no choice but to use the alternative mechanisms provided by the Symbian
platform to port such code. Even in EKA2 where global data is supported, Symbian
recommends that it only be used as a last resort. </p> <p>The following sections
describe the alternatives that can be used to port code that makes use of
global writeable static data. </p> <p><b>Use
thread-local storage (TLS)</b> </p> <p>Thread Local Storage (TLS) is a single
per-thread word that can be used to simulate global writeable static data. </p> <p>All
the static data in the DLL is grouped into a single struct or class. On creation
of the thread, an instance of the thread is allocated on the heap and a pointer
to this data is saved to TLS (using <codeph>Dll::SetTls()</codeph>). On destruction
of the thread, the data is destroyed. Throughout the DLL the code references
the TLS data (using <codeph>Dll::Tls()</codeph>) rather than the original
global writeable static data. </p> <p><b>Wrap
in a server</b> </p> <p>The Symbian platform supports writeable global static
data in EXEs. A common porting strategy is therefore to wrap the code in a
Symbian server (which is an EXE), and expose its API as a client interface. </p> <p><b>Move global variables into your classes</b> </p> <p>With relatively small
amounts of code, it may be possible to move most global data inside classes. </p> </section>
<section id="GUID-03B7CEEC-AF27-430C-8B70-D8E5D2B9703C"><title>Enabling global writeable static data</title> <p>In order
to enable global writeable static data, simply add a statement <codeph>epocallowdlldata</codeph> (case
insensitive) to the project's MMP file: </p> <codeblock id="GUID-0E673C33-569E-5F7B-9E51-55C2FC233D70" xml:space="preserve">TARGET my.dll 
TARGETTYPE dll 
EPOCALLOWDLLDATA 
… </codeblock> </section>
<section id="GUID-1437C47C-4D74-4332-9138-F2DA552C6715"><title>Costs and limitations</title> <p><b>Emulator
only allows a DLL with WSD to load into a single process</b> </p> <p>The Symbian
platform EKA2 Emulator only allows a DLL with WSD to be loaded into a single
process. </p> <p>This is a very serious restriction. If you have a shared
DLL with WSD, then the second process that attempts to load it in the emulator
will fail with <codeph>KErrNotSupported</codeph>. </p> <p><b>Emulator allows WSD by default</b> </p> <p>The Emulator will allow WSD
in DLLs even if <codeph>epocallowdlldata</codeph> is not declared in the mmp
file. However the data will be truly global: there will be one copy for the
entire emulator, rather than one copy for each emulated process. The only
restriction is that if the data's initialisers call any Symbian platform kernel
functions (i.e. executive calls), then the emulator will fault. </p> <p><b>RAM usage for WSD data chunk </b> </p> <p>When a process loads its first
DLL containing WSD, it creates a single chunk to store the data. The data
for subsequent WSD-enabled DLLs is loaded into the same chunk. </p> <p>The
data chunk will occupy at least one 4K RAM page (the smallest possible RAM
allocation), irrespective of how much static data is required. Any memory
not used for WSD will be wasted. Since the memory is per-process, the memory
wastage on the machine is: </p> <codeblock id="GUID-005105EF-A09A-5FF7-8056-7316AFCE1894" xml:space="preserve">(4Kb - WSD Bytes) × number-client-processes</codeblock> <p>It is very easy for a developer to add a few words of WSD to their DLL thinking
that's all the memory that they are using. However, the cost is actually 4K
for every process if a DLL with WSD has not already been loaded into the process.
If for example the DLL is used by 4 processes, that's potentially an "invisible"
cost of 16K. </p> <p><b>Chunks
are a finite resource</b> </p> <p>EKA2 has a hard coded limit of 16 chunks
per process; a limit that is required to ensure real-time behaviour. Every
process loading WSD-enabled DLLs uses a chunk to hold the data, reducing the
number of chunks available for other uses. </p> <p><b>ARM architecture 4 and 5 specific costs and limitations</b> </p> <p>There
are other significant costs that apply only to DLLs that link against "fixed
processes". Fixed processes are a feature of ARM v4 or v5 architecture only;
the following behaviour does not apply to devices based on the ARMv6 architecture. </p> <p> <b>Case
1: Non Execute-in-place DLLs</b>  </p> <p>For non-execute-in-place (non XIP)
DLLs, an additional code chunk is required for every fixed process which links
against the DLL. </p> <p>So imagine a 20Kb DLL (with a few bytes of WSD) that
is loaded into 4 normal "non-fixed" processes, and 2 fixed processes. The
(static) memory consumed is: </p> <ul>
<li id="GUID-57F9041D-240C-5B75-BC0C-EFA66AB411B6"><p>Code chunk shared by
all moving processes = 20 Kb </p> </li>
<li id="GUID-1FCC1ED4-0A60-5983-AF5A-2F7C8622BC80"><p>Code chunk for each
fixed process loading the DLL = 40 Kb </p> </li>
<li id="GUID-6CD0DBDD-E406-5F7D-9207-8E55B4043779"><p>Data chunk for each
process loading the DLL = 6×4Kb = 24 Kb </p> </li>
</ul> <p>So to allow a few bytes of WSD there is a 64Kb increase in consumed
memory. Note that the 20Kb code chunk shared by all processes is consumed
whether or not WSD is enabled. </p> <p> <b>Case 2: Execute-in-place DLLs</b>  </p> <p>For
XIP DLLs, there is no additional RAM cost other than the size of the WSD itself,
rounded up to the next multiple of 4KB. However: </p> <ul>
<li id="GUID-8B1EDEA4-8082-5DB1-87A8-E7B0FE5BB802"><p>An XIP DLL can be loaded
by any non-fixed process, OR it may be loaded by a single fixed process (and
therefore cannot be loaded by any other processes whatsoever) </p> </li>
<li id="GUID-BA2D82B1-A036-5281-95EB-A46A7976605B"><p>The ROM build fails
if a DLL with static data links to a fixed process <i>and</i> any other process. </p> </li>
</ul> <p> <b>A few specific DLLs cannot have WSD</b>  </p> <p>DLLs that are
required to initialise the file server cannot have WSD, e.g. HAL.DLL, EUSER.DLL,
EFSRV.DLL. </p> </section>
<section id="GUID-4DCE5F11-5066-4C72-9F39-E46737F7BDA8"><title>Frequently asked questions</title> <p><b>How
does Symbian's WSD implementation work ?</b> </p> <p> <b>Case 1. For moving
processes:</b>  </p> <p>The Symbian platform supports a moving memory model,
in which the data for a process is moved into a fixed virtual address space
(the "run section") when the process is active, and then back into the processes
"home" section when another process is active: </p> <ul>
<li id="GUID-26E98921-9094-5260-BA99-2F7FA4F7D6A7"><p>The data of processes
in the "home section" is uniquely addressed both in terms of physical RAM
pages, and in the MMU virtual address space. The data is protected from other
processes, except for the Kernel. </p> </li>
<li id="GUID-BBE7C17A-6FF7-5329-91C5-DEAF88A61B69"><p>The data of processes
in the run section occupies the same virtual address space as all other processes
when they run (the MMU moves the physical RAM pages into the appropriate virtual
address space). </p> </li>
</ul> <p>When a DLL with WSD is loaded (or at ROM build time), its code is
fixed to point to static data at specific addresses. In order to ensure that
only a single copy of the DLL code is required, Symbian's moving-process WSD
implementation ensures that the virtual addresses of static data is the same
across every running process. </p> <p>The way this works is: </p> <ol id="GUID-66A040C2-7B0F-56E0-A634-501D3E133A12">
<li id="GUID-964A78E1-D86E-50D0-8AA0-D3D9346A43E7"><p>A specific address space
is reserved for a per-process static data chunk. This chunk is used to hold
all the static data for all the DLLs loaded into the process. </p> </li>
<li id="GUID-0A528F28-55B2-5B8B-A337-8B2377241CF0"><p>At ROM build time the
kernel reserves specific addresses within the static data chunk for all the
WSD in all the ROM loaded DLLs. The addresses for ROM based DLLs are reserved
from the top of the static data chunk address space to the bottom. Note that
static data addresses for RAM based DLLs are reserved when the DLL is first
loaded into any process. In this case, addresses are reserved from the bottom
of the static data chunk address space. </p> </li>
<li id="GUID-1898478C-2E24-53B4-BDEB-765FEEDC539C"><p>When the first DLL with
WSD is loaded into a process, a static data chunk is created to hold the static
data for all DLLs that are loaded into the process. </p> </li>
<li id="GUID-7A88C9EB-31F9-559E-8DBD-221848CA2A46"><p>Any global static data
in the DLL is written to its specific reserved addresses. Note that addresses
are reserved for that particular static data across all processes; if the
DLL is loaded into another process, any static data will get the same virtual
address. </p> </li>
</ol> <p> <b>Case 2. For fixed processes:</b>  </p> <p>A fixed process is
one in which the process data does not move; code is run on process data stored
in the process "home section". </p> <p>Since the static data for every fixed
process is uniquely addressed, and a DLL can only point to a single address
for its data, the implication is that a separate copy of the DLL code is required
for every fixed process that loads the DLL. </p> <p>The restrictions listed
above for ARM architecture 4 and 5 directly result. </p> <ul>
<li id="GUID-125EDB37-4540-5EDB-9C19-6F92A307627F"><p>For XIP based devices
the DLL code chunk address is fixed at ROM build time, and there can only
be one copy of the DLL code. Therefore the DLL code can address the data in
either a single fixed process or the virtual address used by all moveable
addresses. </p> </li>
<li id="GUID-BC66EA5A-252D-5E37-80F6-BEC82C03DABA"><p>For non-XIP based devices
the DLL is run from RAM, and the loader is able to fix-up the address that
a DLL expects its data at load time (rather than ROM build time). Therefore
in this case the loader creates a separate copy of DLL code for each fixed
process that loads the DLL and a single copy shared by all moving processes. </p> </li>
</ul> <p>Notes: Fixed processes are not supported or required on ARM v6 architectures.
This discussion only applies to devices based on ARMv4 or v5. On ARM architecture
6 each DLL with WSD has a reserved address, similar to the ARMv5 moving process
case. However there is no 'home section' and memory is not relocated between
low and high addresses on a context switch. Instead, each process uses its
own set of page tables for the bottom half of virtual address space. </p> <p><b>Why does the EKA2 Emulator only allow a DLL with WSD to load into a single
process?</b> </p> <p>The Symbian platform permits a DLL with global data to
be loaded into only one Symbian platform process on the emulator. This limitation
is a result of the way the Emulator is implemented on top of the Windows process
model. </p> <p>On EKA2, separate Symbian platform processes are emulated within
a single Windows process. To preserve Symbian platform semantics there should
be one copy of the global data for each emulated process. However, this is
not possible since a DLL on the emulator is just a Windows DLL; Windows gives
it a single copy of any global data it needs when it is loaded. </p> <p><b>What happens if epocallowdlldata isn't declared for a DLL with WSD?</b> </p> <p> <b>Case
1: On the EKA2 Emulator:</b>  </p> <p>Most constant data should be treated
by the compiler as read-only rather than writeable static data (the exception
is when the const data has a non-trivial constructor, so a real variable is
required during initialisation). </p> <p>Unfortunately, different compilers
sometimes treat const data as WSD. For example, CodeWarrior puts it in writeable
data and initialises it at run time. MSVC generally puts it into read-only
data, but occasionally puts it into writeable data. </p> <p>As most DLLs have
const data, this means that the compilers have "accidentally" created WSD
in almost every DLL. Symbian cannot therefore rigorously enforce the "single
process can load a DLL with WSD" rule, as the Emulator would not work. </p> <p>On
the EKA2 Emulator, the workaround Symbian have implemented is to recognise
two types of DLL global data: </p> <ul>
<li id="GUID-6AD2E89F-6361-5F1F-8EC1-A203801BCC8F"><p>'Deliberate' global
data is where the programmer specifies that they want DLL global data (using
the <codeph>epocallowdlldata</codeph> keyword in the MMP file. In this case
any global data in the DLL is assumed to be deliberate, and the "DLL loaded
into one-emulated-process" rule applies. </p> </li>
<li id="GUID-225E44BE-434E-5C2A-8503-318E31B17EF0"><p>'Accidental' global
data is the data introduced by the compiler with no encouragement from the
programmer. If <codeph>epocallowdlldata</codeph> is absent, global data is
assumed to be accidental and the rule does not apply. Note that the global
data includes both const and non-const static data; there is no way to tell
the compilers to only apply it to non-const data - if we could do that then
we could force correct handling of const static data. </p> </li>
</ul> <p>In order to prevent abuse of this workaround, there are restrictions
on what can be done with accidental global data; specifically, the Emulator
will fault if any of the global data's initialisers attempt to call the Symbian
platform kernel functions (i.e. executive calls). </p> <p>Note that there
is only one copy of the global data. Therefore it is possible for two processes
to write to the same 'accidental' global data (causing undefined behaviour).
The "DLL loaded into one-emulated-process" rule prevents this being a problem
for deliberate global data. </p> <p> <b>Case 2: On the EKA1 Emulator</b>  </p> <p>The
EKA1 emulator has no concept of separate Symbian platform processes. Global
data is allowed on the Emulator as there is only one copy of any global data. </p> <p>Symbian
developers often have problems when porting to real hardware, which does not
support this type of data. This is discussed in the following section. </p> <p> <b>Case
3: On native target builds</b>  </p> <p>On either EKA1 or EKA2, target compilers
will fail the build with an error indicating that the code has initialised
or un-initialised data. </p> <p>The error message does not specify the symbol(s)
that are causing the problem. The <filepath>.map</filepath> files output by
the linker can however be helpful in finding the problem symbol. The RVCT
map files provide a list of global symbols and the object files in which they
occur. FAQ-0329 on the <xref href="http://developer.symbian.org/wiki/index.php/Symbian_C++_Knowledgebase_Q&amp;As#How_can_I_find_the_.22uninitialised_data.22_in_my_DLL.3F" scope="external">DevNet knowledgebase</xref> works through an example of using
a map file using the GCC compiler used on older Symbian platform releases. </p> <p><b>Can Kernel DLLs have WSD ?</b> </p> <p>Yes, WSD is supported for kernel
DLLs in both EKA1 and EKA2 (through alternative mechanisms to those described
here). </p> <p>Of course, kernel DLLs are guaranteed to be loaded into only
one process, so the per-process multiplication of RAM usage does not apply.
EKA2 will work correctly with global data in any kernel DLL. However EKA1
does not call constructors for global C++ objects in kernel extensions or
device drivers, and does not call destructors for global C++ objects in device
drivers at driver unload time. </p> </section>
</conbody></concept>