Emulator configuration file: epoc.ini in Emulator reference

The emulator can have a configuration file located in epoc32\data\ on the PC's file system. By default, its name is epoc.ini, but this can be changed using the command line option -M.

Note that when launching the emulator from the command line, emulator configuration options may alternatively, or additionally be specified on the command line, using syntax described in Emulator syntax: epoc.exe.

The following sections describe all the configuration options. Note that not all these are relevant to all phone emulators.

Configuration options are specified on separate lines in epoc.ini. The property name is specified first, followed by a space, followed by the value. For example, to set the screen width as 640 pixels and the screen height as 240 pixels, the epoc.ini entry would be:

ScreenWidth 640 ScreenHeight 240

Value	Parameters	Definition
`ScreenWidth`	integer	Screen width in pixels
`ScreenHeight`	integer	Screen height in pixels
`PhysicalScreenWidth`	integer	Physical screen width in twips. If not specified, the default value is used, which is recommended.
`PhysicalScreenHeight`	integer	Physical screen height in twips. If not specified, the default value is used, which is recommended.
`ScreenOffsetX`	integer	Screen offset from left hand side
`ScreenOffsetY`	integer	Screen offset from top

Note

The twips settings allow the GDIs twips-to-pixels mapping functions to be changed according to the size of the physical screen on the emulated model. The default values correspond to 0.21mm pixel size or 121 pixels per inch, which is the recommended setting to use for all platforms / emulators.

The STARTUPMODE macro is used to customise the startup of the TechView emulator. Including StartUpModeN in epoc.ini instructs ESTART to select a static startup configuration (SSC) file as follows:

StartUpMode0- use the default SSC (SSCForStartupMode0.rss).
StartUpMode1- use the Text Shell SSC (SSCForStartupMode1.rss).

Note that the "textshell" instruction in epoc.ini and the -Dtextshell -- option at the command prompt are now obsolete.
StartUpMode2- use the System Text SSC (SSCForStartupMode2.rss).
StartUpMode3- use the Rapid Start SSC ( SSCForStartupMode3.rss).
StartUpMode4- use SSCForStartupMode4.rss which is similar to the default but without watchers.

Value	Parameters	Definition
`FasciaBitmap`	bitmap name and path	Sets the background bitmap

Value	Parameters	Definition
`ColorDepth`	`Gray2`, `Gray4`, `Gray16`, `Gray256`, `Color16`, `Color256`, `Color4k`, `Color64k`, `Color16M`	Sets the colour depth to simulate various colour devices.

For more than one colour depth, specify the ColorDepth keyword once, and then specify as many of the color depth parameters as you want on the same line, for instance:

ColorDepth Gray256 Color256 Color4k

Value	Parameters	Definition
`_NewScreen_`	n/a	Used to precede the definition of each additional screen.

If the emulator uses multiple screens, the epoc.ini file may be divided into sections, each of which holds the properties that apply to a particular screen. _NewScreen_ is used to precede each list of screen-specific properties that apply to additional screens. Screen-specific properties are listed in the tables above, under Screen size and position, Fascia bitmap and Colour depth. For more information, see How to configure an emulator with multiple screens.

Value	Parameters	Definition
`WindowTitle`	string	Sets the emulator window title
`NoVersionInfo`	none	Prevents version information from appearing in the title

The following keywords are for configuring the digitiser size. The default behaviour is that the digitiser is enabled and is the same size as the fascia bitmap.

Value	Parameters	Definition
`DigitizerOffsetX`	integer	Position of the left of the emulated digitiser relative to the screen (not the fascia bitmap). The offset will generally be a negative number as the digitiser overlaps the screen in all directions. This defaults to minus the offset of the screen in the bitmap.
`DigitizerOffsetY`	integer	Position of the top of the emulated digitiser relative to the screen (not the fascia bitmap). The offset will generally be a negative number as the digitiser overlaps the screen in all directions. This defaults to minus the offset of the screen in the bitmap.
`DigitizerWidth`	integer	Width of digitiser in pixels.
`DigitizerHeight`	integer	Height of digitiser in pixels
`DisableDigitizer`	integer	Disable digitiser. If this is specified, no mouse events will be generated and buttons on the bitmap which are implemented with an off screen window will not work. The `VirtualKey` regions defined in the emulator configuration file will still work as they generate key events not pointer events.

Value

Parameters

Definition

VirtualKey

key-code shape params

Defines a virtual key region.

The key-code shape parameters have the following syntax:

rect <x>,<Y> <W>,<H>

where:

<X> is an integer defining the x-coordinate position of the top left corner of the region.
<y> is an integer defining the y-coordinate position of the top left corner of the region.
<w> is an integer defining the width of the region.
<h> is an integer defining the height of the region.

Note that the comma (,) between the <x> and <y> integers, and between the <w> and <h> integers is required.

Note

The syntax will allow different shapes, but the only shape supported is rect which specifies a rectangle. The parameters are the co-ordinates for the top left and bottom right of the rectangle.

Value

Parameters

Definition

KeyMap

[<modifier>]

<realKey>

<keyCode>

Maps a real key on the PC keyboard to a Symbian OS key code.

<modifier>

This is optional, but specifies a modifier key as represented by one of the following string mnemonics:
- LeftAlt
- RightAlt
- LeftCtrl
- RightCtrl
<realkey>

This string mnemonic for a PC key. The list of possible strings is the same as that for the EmulatorControlHotKey keyword.
<keyCode>

The string mnemonic for a Symbian OS keycode. Symbian OS keycodes are one of the TStdScanCode enum values. The strings to be used here can be one of the C++ symbols used to define these enum values, i.e. the strings "EStdKeyNull", "EStdKeyBackspace" etc. The Latin letters 'A' to 'Z' or one of the digits '0' to '9' can also be used.

For example:

KeyMap LeftAlt N EStdKeyF4 KeyMap LeftAlt M EStdKeyF5

Sets "LEFT ALT" + "N" to "F4" and "LEFT ALT" + "M" to "F5" respectively.

Note that this keyword is commonly used when emulating MultiMediaCards. This is because the F4 and F5 keys are used to emulate MMC drive events. However, this can cause a problem when debugging, because F5 is used for continuing the debugger. Setting up the above mapping means that pressing "LEFT ALT" + "M" will emulate a media change event (normally F5).

See also:

There are various emulator settings that can be used to set platform security behaviour. The default setting on kits supplied by Symbian is that platform security is fully enabled and enforced (all settings set to On). It may be useful however when programs are being developed to temporarily suspend enforcement of platform security using the PlatSecEnforcement or PlatSecDisabledCaps settings. The platform security diagnostic messages written to the debug log file can then be examined to discover any platform security checks that are failing, without the inconvenience of the program stopping or giving an error code.

Value	Parameters	Definition
`PlatSecEnforcement`	`[On \| Off]`	When a capability or other Platform Security policy check fails, and after any diagnostic message has been emitted (if enabled), the final action is dependent on whether Platform Security enforcement is enabled. If enforcement is not enabled, then the system continues as though the original Platform Security check in fact passed. If enforcement is enabled, then the appropriate action for a failed Platform Security check happens. To enable PlatSec enforcement, set this to `On`. To disable enforcement, so that PlatSec checks are assumed to have passed, set this to `Off`
`PlatSecDisabledCaps`	`<capability>`+`<capability>`+...	Use this to disable a specified set of capabilities: for example, `PlatSecDisabledCaps LocalServices+ReadDeviceData+ReadUserData` The implementation of this feature is achieved by automatically granting to all binaries the disabled capabilities as they are loaded at run-time. These capabilities are assigned before any capability checking is done, therefore checks for these capabilities will always succeed and will not cause diagnostic messages.
`PlatSecDiagnostics`	`[On \| Off]`	Capability and other Platform Security policy checks are made by the executable loader, and some low level Base APIs. When these checks fail a diagnostic message may be emitted, if this setting is ON. Diagnostic messages are logged to file, by default `EPOCWIND.OUT` in the Windows temporary directory. Diagnostic messages take the form of a single line which starts with the text PlatSec followed by either ERROR or WARNING depending on whether Platform Security enforcement is enabled or not.
`PlatSecProcessIsolation`	`[On \| Off]`	Some kernel APIs inherited from EKA1 can have insecure uses, such as a thread in one process being allowed to kill a thread in another process. When this flag is set, the kernel provides run-time checks for their correct usage.
`PlatSecEnforceSysBin`	`[On \| Off]`	When this flag is set, the executable loader will only look for and load files in the `\Sys\Bin\` directory. If a different path is specified, then this path is ignored and `\Sys\Bin\` searched.

Value	Parameters	Definition
`TimerResolution`	integer	The OS has a high resolution timer, accessed through methods such as `User::AfterHighRes()`, and `RTimer::HighRes()`. This defaults to 5ms on the Emulator. This can be altered through this setting.

Value	Parameters	Definition
`NoGui`		Starts the emulator without displaying any window. This is particularly intended to allow emulator console programs to be used in automated scripts, where displaying a window would be inappropriate.

You can specify the speed for flash used by emulated LFFS drives using the following settings. Values are in microseconds.

Value	Parameters	Definition
`FlashEraseTime`	integer	Delay applied to erase operations. Default is 1000000 (1s).
`FlashResumeTime`	integer	Delay applied to resuming after being suspended. Default is 5000 (5ms).
`FlashWriteTime`	integer	Delay applied to write operations. Default is 406.

Value	Parameters	Definition
`EmulatorMediaPath`	directory	Specifies the directory path for files that store data for drives for emulated file systems, such as NAND, LFFS, and MMC drives. The default is `epoc32\data\media`. If the value `%temp%` is specified, then the current Windows temporary directory is used.

MultiMediaCard drives are defined by the emulator specific versions of estart.exe, and estart.txt . However, the following keywords affect the way that the emulated MultiMediaCard drives behave.

Note that the keywords are case-insensitive.

Value

Parameters

Definition

MultiMediaCardSize=

<kilobytes>

Defines the size of emulated MultiMediaCard drives.

The default value is 1Mb, if no value is explicitly specified.

Note that if you change the size of the emulated drive, then this will affect behaviour when the emulator is subsequently re-started:

if the size of the drive is decreased, then you will see a smaller, initially unformatted, emulated drive.
if the size of the drive is increased, then you will see a larger emulated drive, and its formatting and file structure remain intact.

_EPOC_Socket_<SocketNum>_PWORD_<cardNum>

<password string>

Specifies a password for an emulated slot. By default, there is no password for any of the emulated drives/cards, and therefore this item is not compulsory.

<SocktNum>

The slot number.
<cardNum>

The number of the card that has this password. This should be 0 for all drives except drive 1.
<password string>

The password for this slot and card.

For example:

MultiMediaCardSize=100

Sets up an emulated card size of 100Kb.

The Symbian OS mechanism for generating and capturing trace information can be used on the emulator. The default Symbian OS trace handler is always loaded and initialised when the emulator starts up.

There are a number of keywords that you can use to set up default states.

Each trace has a category, an 8-bit value; the kernel implements a filter that enables traces in each category to be either discarded (disabled) or passed to the trace handler (enabled). You use the BTrace0, BTrace1, ...BTrace7 keywords to set the initial state of that filter, i.e. to indicate whether a trace category is enabled or disabled.

A trace category is one of the BTrace::TCategory enum values.

Each of the BTrace0, BTrace1, ..., BTrace7 keywords takes a 32-bit integer. The complete set of eight 32-bit integers is viewed as a sequence of 256 bits. Each bit is associated with a single category - if a bit is set it means that the corresponding category is enabled - if a bit is not set it means that the corresponding category is disabled.

Each of the BTrace0, BTrace1, ... ,BTrace7 keywords maps to successive sets of 32 categories.

Emulator configuration file: `epoc.ini`

Purpose

Syntax

Configuration options

Screen size and position

Note

Startupmode

Fascia bitmap

Colour depth

Multiple screens

Window title

Digitiser size

Virtual key regions

Note

Key mapping

LEDs

Debugging

Pointer type

Memory capacity

Alias name

Comments

Multiple fascias and screen orientations

Activation

Click actions for specific screen regions

Hot key actions

Platform security

Timer resolution

No GUI

LFFS speed emulation

Emulated media path

Emulated MultiMediaCards

Tracing

Disk access speed

Kernel extensions