Keyword reference

This page lists the keywords starting from D to F.

datapagingoverride

datapagingoverride [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

If the datapagingoverride keyword is specified in an OBY file, it overrides the configuration for data paging for the EXE files defined in OBY file. This keyword takes a single argument, which can be one of the possible values listed in codepagingoverride.

datapagingpolicy

datapagingpolicy [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

This overrides the default settings for data paging and the settings from all the previous levels.

This keyword takes a single argument, which can be one of the possible values listed in codepagingoverride.

data[[HWVD]]

data[[HWVD]] = <source-file> <destination-file> [File-attribute-list]

rombuild and rofsbuild

A file that is copied from its source location into the ROM without any processing.

Note that the HWVD is optional but, if specified, must be enclosed within square brackets.

dataaddress

dataaddress = <hex-address>

rombuild only

Linear address of data/bss chunks for all executables except the Kernel.

datadriveimagename

datadriveimagename = <image name>

ROFSBUILD only

Specifies the name of the data drive image.

DATA_IMAGE

DATA_IMAGE <id> <name> [size=<partition size>] [FAT16 | FAT32] [compress | no-compress]

BUILDROM only

Defines a data drive image.

This is a data drive configuration feature. There is no limitation for the number of data drive images that can be defined for an internal media.

id

A value to identify the data drive image.

name

A name suitable as a suffix for the data drive image, IBY and logs.

size = <partition size>

Defines the size of the data drive image that has to be generated.

compress

Compresses files in the image. If not specified, no compression is the default behaviour.

To mark a file for inclusion in a data drive it is prefixed with the keyword DATA_IMAGE. For example:

DATA_IMAGE[2] fatname size=16000000 fat16 -compress

The above information can also be included using '{' '}' braces, for example:

DATA_IMAGE[2]
    {
    dataimagename=fatname
    compress
    dataimagefilesystem=fat16
    dataimagesize=16000000  
    }
      

dataimagefilesystem

dataimagefilesystem = <FAT16 | FAT32>

BUILDROM and ROFSBUILD only

Specifies the file system type of the datadrive image. If this is not specified then by default BUILDROM sets the image file system as fat16.

dataimagename

dataimagename = <image name>

ROFSBUILD only

Specifies the name of the datadrive image. If this is not specified then by default BUILDROM sets the image name as dataimagex, where x is the image index.

dataimagesize

dataimagesize = <size in bytes>

ROFSBUILD only

Specifies the maximum size of a data drive image. The default size is the size of the data drive folder.

DEFAULT_LANGUAGE

DEFAULT_LANGUAGE NN

BUILDROM only

Localisation support. Specifies the default language as a Symbian 2-digit code. This keyword should only be used once.

DEFINE

DEFINE <name> <replacement>

BUILDROM only

Performs textual substitution. All subsequent instances of <name> are replaced by <replacement>.

Notes:

  • There is no UNDEFINE facility, and substitutions are applied in an unspecified order

  • The C++ preprocessor cannot be used conveniently because it inserts whitespace around substituted text.

device[[HWVD]]

device[[HWVD]] = <source-file> <destination-image-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

Defines kernel-mode logical or physical device drivers, which can have global data. The address of this data is generated by rombuild.

Note that the HWVD is optional but, if specified, must be enclosed within square brackets.

dll[[HWVD]]

dll[[HWVD]] = <source-file> <destination-image-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

Specifies an executable file whose entry point must be called.

debugport

debugport = <32bit-number>

rombuild only

Specifies the destination port for Kernel and Bootstrap traces.

rombuild stores the value in the ROM header. Each ASSP is free to interpret the debug port as it pleases, for example, as a serial port number or as an I/O base address. The default value is -1.

defaultstackreserve

defaultstackreserve = <default stack reserve>

rombuild only

Specifies the maximum size of the stack.

demandpagingconfig

demandpagingconfig <MinLivePages> <MaxLivePages> <YoungOldPageRatio> <NANDPageReadDelay> <NANDPageReadCPUOverhead>

rombuild only

Specifies settings for demand paging enabled ROM.

This keyword takes four arguments, which are described below:

  • MinLivePages: This is the minimim number of RAM pages to reserve for the paging system.The number must be at least equal to 2*(YoungOldPageRatio+1). If a smaller number is specified, a number equal to this formula is used instead.

    For example, the YoungOldPageRatio is 3 and MinLivePages is set to 5. According to the formula 2*(YoungOldPageRatio+1), the minimum number of live pages must be 8, but the number specified is 5. So the minimum number is set to 8.

  • MaxLivePages: The maximum number of RAM pages the paging system may use. The number must be greater than or equal to MinLivePages. On a production system the number is always set to maximum (32767). However, low values may be used to test the effects of low free RAM.

  • YoungOldPageRatio: The ratio of young to old pages maintained by the system. For this purpose, the paging system maintains a list of live pages, which is again split into two sub-lists: a list of young pages, and a list of old pages in the system. The paging system uses YoungOldPageRatio to maintain the relative sizes of these two lists.

    For example, let us assume that the ratio is R, the number of young pages is Ny and the number of old pages is No. If Ny > RNo, a page is taken from the end of the young pages list and placed at the start of the old pages list. This process is called aging.

  • NANDPageReadDelay: The delay in microseconds, between initiating a page read operation and completing it. During this delay, other threads in the system may use the CPU.

  • NANDPageReadCPUOverhead: The CPU instruction execution time in microseconds, to setup and process a page read operation. During this delay, the CPU is busy and is not accessible by other threads.

Note: All the above listed attributes are limited to the value range 0-32767.

dlldatatop

dlldatatop = <address of data region>

rombuild only

Specifies the top of the DLL data region.

ECHO

ECHO <anything at all>

BUILDROM only

Prints the rest of the line following the ECHO keyword to standard output.

__ECOM_PLUGIN

__ECOM_PLUGIN(<local build directory>, <rom binary directory>, <local epoc32\data\Z directory>, <rom resources directory>, <DLL filename>, <resource filename>)

BUILDROM only

Specifies an ECom plug-in, consisting of an implementation DLL and an ECom registration resource file, to include in ROM.

Symbian platform code does not use this keyword directly. Instead, it uses the macro ECOM_PLUGIN, defined in \epoc32\rom\include\header.iby, which allows the plug-in to be specified more briefly, in the following form:

ECOM_PLUGIN(<DLL name>,<resource file name>)

For example:

ECOM_PLUGIN(foo.dll,12345abc.rsc)

Note that the resource file name is specified using the <DLL-uid>.rsc format. This is for compatibility with OS versions before v9.0. From v9.0, this parameter is ignored, and the resource file is assumed to have the same name as the implementation DLL (for example foo.rsc).

Use of this keyword allows BUILDROM to perform special handling of ECom plug-ins. In particular, it allows BUILDROM optionally to create a static plug-in information (SPI) file, which contains all the resource registration files for ROM-based plug-ins. This allows ECom to be more efficient, as it can use the SPI file to find all ROM-based plug-ins and not have to scan the file system for them. BUILDROM implements this using the spidata keyword.

Note that as part of the ROM creation process, it is possible to add support for multiple languages. This affects how ECom resource files are specified by BUILDROM:

  • If an SPI file is being created the ECOM_PLUGIN lines are processed at an intermediate BUILDROM stage to produce:

    spidata=MULTI_LINGUIFY( EXT sourcename destname ) <spi-id> <target-spi-dir>

    During the BUILDROM localisation stage these lines become:

    spidata = <source-file> <original-destination-file> <spi-id> <target-spi-dir>

    where <spi-id> has the extension .SPI for the default language, and the extension .Snn for all other language codes nn. This means that if multiple languages are being included in the ROM image there is an SPI file for each included language.

  • If an SPI file is not being created ECOM_PLUGIN lines are processed an intermediate BUILDROM stage to produce:

    data=MULTI_LINGUIFY( EXT sourcename destname )

    During the BUILDROM localisation stage these lines become:

    data=sourcename.Enn destname.EXT for the default language code

    data=sourcename.Enn destname.Enn for all other language codes nn.

EPOCROOT

EPOCROOT

BUILDROM only

A pre-defined substitution. This is replaced with the value of the EPOCROOT environment variable.

Note that there is no UNDEFINE facility, and substitutions are applied in an unspecified order.

epocwrapper

epocwrapper

rombuild only

Indicates that a Symbian platform (EPOC) ROM wrapper is required

ERROR

ERROR <anything at all>

BUILDROM only

Prints the rest of the line following the ERROR keyword to standard output, and reports the source file name and the line number. In addition, it causes BUILDROM to terminate without attempting to create the ROM image(s).

exattrib

exattrib=U

ROFSBUILD only

This keyword is used with the data keyword to specify an additional attribute for the file being included in the ROM image. This attribute enables the file server to append the ROFS mounting information in the format, file.ext[<mount_id>-00] when registering the file.

The following example shows how this keyword is used to set the attribute for a text file, which is copied to the ROM image:

data=EPOCROOT##epoc32\rom\rofstest\hello8.txt Exattrib\test1.txt exattrib=U

Assuming that the test1.txt file is in the ROFS image and is the first one to be mounted by the file server, the file is included in the ROM image in the following format:

z:\Exattrib\test1.txt[01-00]

EXCLUDE_FEATURE

EXCLUDE_FEATURE <feature name> [ SF <status flags> ]  [ UD <user data> ] 

Where <feature> is either the feature name or a feature uid value.

Note: The space between the keyword FEATURE and <feature name> is optional.

<status flags> is a 32 bit hex number indicating the status flags of the feature. Each bit in the status flag signifies the following:

BitFlag NameValue

0

Supported

If the bit is set the feature is included, else the feature is excluded.

1

Upgradeable

This bit is reserved for future use. It will be used to upgrade a feature which is already associated to the device.

2

Modifiable

If the bit is set the feature is modified at run-time. The default flag values for such a feature are defined in a ROM image obey file.

3

Blacklisted

If the bit is set the feature is blacklisted, and cannot be changed at run-time. It signifies that if the feature appears in subsequent data files or plug-in info, it would be ignored.

It also prevents a feature from being upgraded and it can never be changed/ overridden. If a feature is blacklisted, its upgradeable flag is not set.

4

Uninitialised

If the bit is set the flag supported state is not initialised at build-time, and it is initialised at run-time by system software.

To set the supported flag of a specific feature, perform a runtime call to RFeatureControl.

5

Persisted

If the bit is set the flag value is preserved across reboot or system turn off period.

6-31

Reserved

These bits are reserved for future use.

<user data> is a 32 bit hex number indicating the user data value associated with the feature.

BUILDROM only

The EXCLUDE_FEATURE keyword is used to mark a feature as excluded.

extension[[HWVD]]

extension[[HWVD]] = <source-file> <destination-image-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

Defines a kernel-mode DLL that can have global data, the address of which is generated by rombuild. Extension files are connected together in a linked list, which allows the Kernel to load the extensions at boot time before the ROM file system is available.

Note that the HWVD is optional but, if specified, must be enclosed within square brackets.

extensionrofs

extensionrofs

rofsbuild only

Marks the start of the definition of an optional extension ROFS.

extensionrofsname

extensionrofsname = <filename>

rofsbuild only

Defines the name of the ROFS extension image.

Any new files added after this keyword will appear in the extension. The files in the core can be renamed, hidden, and aliased by using the other keywords.

extensionrom

extensionrom = <rom-file-name>

rombuild only

This marks the start of an extension ROM section. A filename of "*" can be specified, which means use the file name specified on the romname keyword in a rom-information-statement

externaltool

externaltool=<toolname>

BUILDROM only

Used for invoking external tools through the IBY file keyword externaltool, specifying the list of toolnames each seperated by a comma. externaltool=toolname1, toolname2,... toolnameN

The same invocation can be achieved alternatively by using BUILDROM command-line option -e<toolname>.

fattable

fattable=<number of FAT tables>

rofsbuild only

Configures the number of FAT tables for the file system in the data-drive image.

FEATURE

FEATURE <feature name> [ SF <status flags> ]  [ UD <user data> ]

Where <feature> is either the feature name or the feature uid value.

Note: The space between the keyword FEATURE and <feature name> is optional.

<status flags> is a 32 bit hex number indicating the status flags of the feature. Each bit in the status flag signifies the following:

BitFlag NameValue

0

Supported

If the bit is set the feature is included, else the feature is excluded.

1

Upgradeable

This bit is reserved for future use. It will be used to upgrade a feature which is already associated to the device.

2

Modifiable

If the bit is set the feature is modified at run-time. The default flag values for such a feature are defined in a ROM image obey file.

3

Blacklisted

If the bit is set the feature is blacklisted, and cannot be changed at run-time. It signifies that if the feature appears in subsequent data files or plug-in info, it would be ignored.

It also prevents a feature from being upgraded and it can never be changed/ overridden. If a feature is blacklisted, its upgradeable flag is not set.

4

Uninitialised

If the bit is set the flag supported state is not initialised at build-time, and it is initialised at run-time by system software.

To set the supported flag of a specific feature, perform a runtime call to RFeatureControl.

5

Persisted

If the bit is set the flag value is preserved across reboot or system turn off period.

6-31

Reserved

These bits are reserved for future use.

<user data> is a 32 bit hex number indicating the user data value associated with the feature.

BUILDROM only

The FEATURE keyword is used to mark a feature as included.

file[[HWVD]]

file[[HWVD]] = <source-file> <destination-image-file> [File-attribute-list] [Override-Attribute-list] [paged | unpaged]

rombuild and rofsbuild

A standard executable file, for example, a .exe or a .dll, in PE format or E32 image format. Executable files are stripped of their relocation information prior to being stored in the ROM. The relocation information is not necessary in the ROM because all files are executed in place with an address that is determined at ROM build time. Use the modifiers paged and unpaged to specify whether to page the executables or not. You can also use the MMP file keywords paged and unpaged to specify whether to page an executable or not.

For example, the following entry in the Obey file provides the source and destination locations of the file MyLibrary.dll and marks the DLL as unpaged.

file=ABI_DIR\DEBUG_DIR\MyLibrary.dll   \sys\bin\MyLibrary.dll   unpaged

Notes:

  • the HWVD is optional but, if specified, must be enclosed within square brackets.

  • the information required to relocate the file is not preserved; this keyword provides a fully resolved uncompressed file.

filecompressnone

filecompressnone=\Epoc32\release\<platform><build><target directory><source file> <destination file>

rombuild only

Doesn't compress the resulting ROM image.

For example:

filecompressnone=\epoc32\release\ARMV\UREL\TEST\RUNTEST.EXE    sys\bin\RUNTEST.EXE

filecompressinflate

filecompressinflate=\Epoc32\release\<platform><build><target directory><source file> <destination file>

rombuild only

Compresses the resulting ROM image using the Deflate, Huffman+LZ77 algorithm.

For example:

filecompressinflate=\epoc32\release\ARMV\UREL\TEST\RUNTEST.EXE    sys\bin\RUNTEST.EXE

filecompressbytepair

filecompressbytepair=\Epoc32\release\<platform><build><target directory><source file> <destination file>

rombuild only

Compresses the resulting ROM image using the bytepair algorithm.

For example:

filecompressbytepair=\epoc32\release\ARMV\UREL\TEST\RUNTEST.EXE    sys\bin\RUNTEST.EXE

filecompress[[HWVD]]

filecompress[[HWVD]] = <source-file> <destination-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

An XIP (execute-in-place) executable to be loaded into the ROM in compressed format. Note that the information required to relocate the file is preserved.

fileuncompress[[HWVD]]

fileuncompress[[HWVD]] = <source-file> <destination-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

XIP (execute-in-place) executable to be loaded into the ROM uncompressed format. Note that the information required to relocate the file is preserved.

fixed

fixed

rombuild only

This executable is loaded as a fixed address process, and has its data fixed in kernel space (high memory). The data of normal executables is paged in and out of low memory as the executable runs. Fixing a chosen subset of the system servers saves context switch time, and speeds execution considerably.