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:
Bit | Flag
Name | Value |
---|
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:
Bit | Flag
Name | Value |
---|
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.