Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Emulator configuration file: epoc.ini


Purpose

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.

[Top]


Syntax

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 

[Top]


Configuration options


Screen size and position

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.


Startupmode

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:


Fascia bitmap

Value

Parameters

Definition

FasciaBitmap

bitmap name and path

Sets the background bitmap


Colour depth

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


Multiple screens

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.


Window title

Value

Parameters

Definition

WindowTitle

string

Sets the emulator window title

NoVersionInfo

none

Prevents version information from appearing in the title


Digitiser size

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.


Virtual key regions

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.


Key mapping

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 Hot key actions.


LEDs

A phone emulator can emulate two hardware LEDs. The following settings determine the appearance of these LEDs.

Value

Parameters

Definition

LedSize

integer

Size of LED in pixels.

LedArrangeVertically

n/a

Arrange the LEDs vertically

LedArrangeHorizontally

n/a

Arrange the LEDs horizontally

LedOffsetX

integer

LED offset from the left of the bitmap

LedOffsetY

integer

LED offset from the top of the bitmap

LedGap

integer

Gap between the LEDs in pixels


Debugging

Value

Parameters

Definition

DebugMask

integer

Deprecated keyword (used in kernel tracing). It specifies a value to be passed to User::SetDebugMask() to control the kind of debugging information printed to the debugger's output window.

JustInTime

none | debug | query

Enables or disables just-in-time debugging with the debug emulator.

  • none - disables just-in-time debugging.

  • debug - enables just-in-time debugging.

  • query - enables just-in-time debugging, but also displays a dialog box on the PC hosting the emulator. The dialog box displays:

    • the panic category or the kernel fault category

    • the panic number or the kernel fault number

    In debug builds, you can choose whether or not to debug the code. In non-debug builds, the dialog box does not give you this choice.

See also User::SetJustInTime().


Pointer type

Value

Parameters

Definition

PointerType

None, Pen, Mouse, Delta-Mouse

Pointer type

The PointerType setting in the emulator configuration file sets the type of pointer device that is available on the target phone. The setting determines the events that the window server makes available to applications.

PEN simulates pen input: events only occur when the pen is touching the digitiser: i.e. in the emulator, when the left mouse button is depressed. With MOUSE, an application also gets Move events: that is, an application can detect a mouse moving even while the button is not pressed. NONE is not currently supported.

The standard shell and applications do not respond to Move events, so the setting value does not alter their behaviour.


Memory capacity

Value

Parameters

Definition

MegabytesOfFreeMemory

integer

Limits amount of memory available.

This option sets the maximum total heap size in megabytes, in order to emulate target machines with different memory capacities. If this parameter is not specified, the amount of free memory defaults to 64MB.

If you wish to limit the heap, it is conventional to allow one megabyte for Symbian OS use: for example, specify 7 to simulate a 8MB machine.


Alias name

Value

Parameters

Definition

DefineKeyName

alias value

Define an alias name for a Symbian OS key code.


Comments

Value

Parameters

Definition

#

n/a

Text following the hash is a comment.


Multiple fascias and screen orientations

Value

Parameters

Definition

Configuration

filename

Used when supporting multiple configurations; defines the name of a configuration file in which the settings for each configuration are stored.

This keyword can only be used in the main epoc.ini file.

More than one configuration file can be defined, for example:

...
configuration c1.ini
configuration c2.ini
configuration c3.ini
...

Information for each configuration is then defined within each of the files defined by the configuration keyword.

For an example, see How to configure an emulator to support multiple fascias and screen orientations.


Activation

Value

Parameters

Definition

OnActivation

orientation key

Specifies the orientation in degrees, and the key to be sent to the window server when this configuration is activated.

Orientation defines the angle through which the new fascia is to be rotated with respect to the default emulator window position; this takes one of the values:

  • 0 - to maintain the same orientation.

  • 90 - to flip the emulator window to the right

  • 180 - to invert the emulator window

  • 270 - to flip the emulator window to the left.

Key is the text representation of the (TKeyCode) keycode that is passed to the window server, and serves to identify the configuration to the window server; it must be one of the text strings:

  • EKeyScreenDimension0

  • EKeyScreenDimension1

  • EKeyScreenDimension2

  • EKeyScreenDimension3

Note that although the window server tells the emulator to rotate when it gets the key message (if setup in wsini.ini), the orientation is required so that the emulator can rotate and change when the device is off.

Example:

OnActivation 270 EKeyScreenDimension1


Click actions for specific screen regions

Value

Parameters

Definition

EmulatorControl

command command_specific_data region_definition

Defines the action that the emulator is to take when a specific region of the screen is clicked. It is similar, in its effects, to the virtualkey keyword (see Virtual key regions).

There are two commands available:

  • NextConfig - changes the configuration to the next one in the list.

    The command takes no command specific data.

  • SelectConfig - changes the configuration to the one specified.

    This command takes an integer as a parameter. This is a value that identifies the new configuration; the number is an index into the list of configurations defined by the configuration keywords in the main epoc.ini file. The index is relative to zero, so that 0 refers to the first .ini file defined.

The region definition has the same syntax and meaning as virtualkey keyword, i.e.

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.

Examples:

NextConfig rect 14,500 29,22

EmulatorControl SelectConfig 3 rect 189,500 32,23

See also Hot key actions.


Hot key actions

Value

Parameters

Definition

EmulatorControlHotKey

Parameters: command command_specific_data key_sequence

Defines the action that the emulator is to take when a specific key combination is pressed.

There are two commands available:

  • NextConfig - changes the configuration to the next one in the list.

    The command takes no command specific data.

  • SelectConfig - changes the configuration to the one specified.

    This command takes an integer as a parameter. This is a value that identifies the new configuration; the number is an index into the list of configurations defined by the configuration keywords in the main epoc.ini file. The index is relative to zero, so that 0 refers to the first .ini file defined.

The key_sequence is a comma separated list of keys. Eack key is identified by a string that is a mnemonic for that key; the possible strings are:

  • Escape

  • 1

  • 2

  • 3

  • 4

  • 5

  • 6

  • 7

  • 8

  • 9

  • 0

  • Minus

  • Equals

  • BackSpace

  • Tab

  • Q

  • W

  • E

  • R

  • T

  • Y

  • U

  • I

  • O

  • P

  • SquareBracketLeft

  • SquareBracketRight

  • Enter

  • LeftCtrl

  • A

  • S

  • D

  • F

  • G

  • H

  • J

  • K

  • L

  • SemiColon

  • SingleQuote

  • BackTick

  • LeftShift

  • Hash

  • Z

  • X

  • C

  • V

  • B

  • N

  • M

  • Comma

  • FullStop

  • ForwardSlash

  • RightShift

  • NkpAsterisk

  • LeftAlt

  • Space

  • CapsLock

  • F1

  • F2

  • F3

  • F4

  • F5

  • F6

  • F7

  • F8

  • F9

  • F10

  • Pause

  • ScrollLock

  • Nkp7

  • Nkp8

  • Nkp9

  • NkpMinus

  • Nkp4

  • Nkp5

  • Nkp6

  • NkpPlus

  • Nkp1

  • Nkp2

  • Nkp3

  • Nkp0

  • NkpFullStop

  • BackSlash

  • F11

  • F12

For example, so that the configuration changes to the next one in the list when the key combination Ctrl-Shift-U is pressed, you need to add the following string to the epoc.ini file:

EmulatorControlHotKey NextConfig LeftCtrl,LeftShift,U

See also:


Platform security

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.


Timer resolution

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.


No GUI

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.


LFFS speed emulation

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.


Emulated media path

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.


Emulated MultiMediaCards

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:


Tracing

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.

See also Base How To BTrace.

Value

Parameters

Definition

BTrace0

<Integer>

Set the bits in this integer to enable the corresponding trace category.

Bit 0 (i.e. the rightmost bit) represents category number 0.

Bit 31 (i.e. the leftmost bit) represents category number 31.

Note that the category number is one of the BTrace::TCategory enum values.

BTrace1

<Integer>

Set the bits in this integer to enable the corresponding trace category.

Bit 0 (i.e. the rightmost bit) represents category number 32.

Bit 31 (i.e. the leftmost bit) represents category number 63.

Note that the category number is one of the BTrace::TCategory enum values.

BTrace2

<Integer>

Set the bits in this integer to enable the corresponding trace category.

Bit 0 (i.e. the rightmost bit) represents category number 64.

Bit 31 (i.e. the leftmost bit) represents category number 95.

Note that the category number is one of the BTrace::TCategory enum values.

BTrace3

<Integer>

Set the bits in this integer to enable the corresponding trace category.

Bit 0 (i.e. the rightmost bit) represents category number 96.

Bit 31 (i.e. the leftmost bit) represents category number 127.

Note that the category number is one of the BTrace::TCategory enum values.

BTrace4

<Integer>

Set the bits in this integer to enable the corresponding trace category.

Bit 0 (i.e. the rightmost bit) represents category number 128.

Bit 31 (i.e. the leftmost bit) represents category number 159.

Note that the category number is one of the BTrace::TCategory enum values.

BTrace5

<Integer>

Set the bits in this integer to enable the corresponding trace category.

Bit 0 (i.e. the rightmost bit) represents category number 160.

Bit 31 (i.e. the leftmost bit) represents category number 191.

Note that the category number is one of the BTrace::TCategory enum values.

BTrace6

<Integer>

Set the bits in this integer to enable the corresponding trace category.

Bit 0 (i.e. the rightmost bit) represents category number 192.

Bit 31 (i.e. the leftmost bit) represents category number 223.

Note that the category number is one of the BTrace::TCategory enum values.

BTrace7

<Integer>

Set the bits in this integer to enable the corresponding trace category.

Bit 0 (i.e. the rightmost bit) represents category number 224.

Bit 31 (i.e. the leftmost bit) represents category number 255.

Note that the category number is one of the BTrace::TCategory enum values.

BTraceBuffer

<Integer>

The initial size for any memory buffer used to store trace data.

See also Base How To BTrace.

BTraceMode

<Integer>

The initial mode of the trace handler. For the default trace handler supplied with Symbian OS, this will be one of the RBTrace::TMode enum values defined in the header file d32btrace.h.

See also Base How To BTrace.


Disk access speed

These settings can be used to change the read/write speed for access to Win32 mapped disks (e.g. emulator C: drive). This allows a delay to be inserted to better emulate slower disks on real devices.

The implementation calculates the delay on each read and write call, based on the size of the buffer and waits using User::AfterHighRes(). To approximate a 2.5MB/s read speed, and a 0.5MB/s write speed, you could set:

DiskRead=400
DiskWrite=2000

The values are measured in microseconds-per-kilobyte.

Value

Parameters

Definition

DiskRead

integer

Delay for disk read

DiskWrite

integer

Delay for disk write


Kernel extensions

The Extension keyword is used to define a list of kernel extensions to be started when the emulator is booted. If no extensions are specified then the standard extension list is loaded. However, extensions that are specified on the command line or in the ini file, replace, rather than add to, the standard extension list. For example, when the application is started with "-DExtension=epbusmmc.dll" only the extensions epbusmmc.dll and exstart are loaded. The extension exstart is always loaded.

Value

Parameters

Definition

Extension

extension-1[;extension-2][;extension-3]...[; extension-n]

Each entry in the list of extensions is separated by a semi-colon (;) character. Note that there is no terminating semi-colon.

Extension names consist of a filename and a file type separated by a full-stop (.) character. The file type can be omitted, but .dll is then assumed.

For example:

Extension btracex.ldd;medlfs.pdd;epbusmmc

Alternatively, if you launch the emulator from the command line, you can specify the extension list as a parameter to epoc.exe:

> epoc.exe -DExtension=btracex.ldd;medlfs.pdd;epbusmmc --

Both the previous examples generate the following list of extensions to be handled at boot time:

Starting the emulator without specifying any extensions results in loading the standard list of extensions: