Static Data

Global writeable static data

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.

TBufC<20> fileName; //WSD 
void SetFileName()
 {
 static Tint iCount; //WSD ...
 }

Sometimes writeable static data appears in a non-obvious way. It is not always the case that const global variables are read-only data rather than global writeable static data. This is true for const objects with trivial constructors, such as integers. However if a const class has a non-trivial constructor, the const object will require a real variable and must be stored as WSD. For example:

const TInt myVariable=…; //OK – truly const
const TPtrC KSomeConstPtr=...; //NOT OK – non trivial constructor 
const TRgb KSomeConstCol=...; //NOT OK – non trivial constructor

Support for global writeable static data on Symbian

The Symbian platform supports global writeable static data in EXEs on all versions and handsets.

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.

Clean up of global writeable static data

Your program must make sure that global writeable static data that the program allocates is cleaned up.

The clean up rules are as follows:

• 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.

• Your program does not need to clean up WSD objects defined in DLLs that the process has dynamically loaded using RLibrary. The Symbian platform automatically calls destructors of these objects.

Alternatives to using global writeable static data

Native Symbian platform C++ code rarely uses WSD.

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.

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.

The following sections describe the alternatives that can be used to port code that makes use of global writeable static data.

Use thread-local storage (TLS)

Thread Local Storage (TLS) is a single per-thread word that can be used to simulate global writeable static data.

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 Dll::SetTls()). On destruction of the thread, the data is destroyed. Throughout the DLL the code references the TLS data (using Dll::Tls()) rather than the original global writeable static data.

Wrap in a server

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.

Move global variables into your classes

With relatively small amounts of code, it may be possible to move most global data inside classes.

Enabling global writeable static data

In order to enable global writeable static data, simply add a statement epocallowdlldata (case insensitive) to the project's MMP file:

TARGET my.dll 
TARGETTYPE dll 
EPOCALLOWDLLDATA 
… 

Costs and limitations

Emulator only allows a DLL with WSD to load into a single process

The Symbian platform EKA2 Emulator only allows a DLL with WSD to be loaded into a single process.

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 KErrNotSupported.

Emulator allows WSD by default

The Emulator will allow WSD in DLLs even if epocallowdlldata 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.

RAM usage for WSD data chunk

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.

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:

(4Kb - WSD Bytes) × number-client-processes

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.

Chunks are a finite resource

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.

ARM architecture 4 and 5 specific costs and limitations

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.

Case 1: Non Execute-in-place DLLs

For non-execute-in-place (non XIP) DLLs, an additional code chunk is required for every fixed process which links against the DLL.

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:

• Code chunk shared by all moving processes = 20 Kb

• Code chunk for each fixed process loading the DLL = 40 Kb

• Data chunk for each process loading the DLL = 6×4Kb = 24 Kb

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.

Case 2: Execute-in-place DLLs

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:

• 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)

• The ROM build fails if a DLL with static data links to a fixed process and any other process.

A few specific DLLs cannot have WSD

DLLs that are required to initialise the file server cannot have WSD, e.g. HAL.DLL, EUSER.DLL, EFSRV.DLL.

Frequently asked questions

How does Symbian's WSD implementation work ?

Case 1. For moving processes:

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:

• 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.

• 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).

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.

The way this works is:

1. 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.

2. 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.

3. 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.

4. 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.

Case 2. For fixed processes:

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".

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.

The restrictions listed above for ARM architecture 4 and 5 directly result.

• 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.

• 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.

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.

Why does the EKA2 Emulator only allow a DLL with WSD to load into a single process?

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.

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.

What happens if epocallowdlldata isn't declared for a DLL with WSD?

Case 1: On the EKA2 Emulator:

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).

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.

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.

On the EKA2 Emulator, the workaround Symbian have implemented is to recognise two types of DLL global data:

• 'Deliberate' global data is where the programmer specifies that they want DLL global data (using the epocallowdlldata 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.

• 'Accidental' global data is the data introduced by the compiler with no encouragement from the programmer. If epocallowdlldata 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.

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).

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.

Case 2: On the EKA1 Emulator

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.

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.

Case 3: On native target builds

On either EKA1 or EKA2, target compilers will fail the build with an error indicating that the code has initialised or un-initialised data.

The error message does not specify the symbol(s) that are causing the problem. The .map 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 DevNet knowledgebase works through an example of using a map file using the GCC compiler used on older Symbian platform releases.

Can Kernel DLLs have WSD ?

Yes, WSD is supported for kernel DLLs in both EKA1 and EKA2 (through alternative mechanisms to those described here).

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.