Keyword reference (D-F)

diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A27BD4D8-8B0E-57C8-9C15-736109297DEA.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-A27BD4D8-8B0E-57C8-9C15-736109297DEA.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,369 @@ + + + + + +Keyword reference (D-F) +

This page lists the keywords starting from D to F.

data-aligndata-align = <hex-number>

rombuild +only

This keyword specifies the alignment for the executable's +data. It indicates the start address of a data segment that must be +aligned to a specified value.

Note: The +inclusion of data-align keyword in an OBY file does +not increase the size of ROM image.

datapagingoverride datapagingoverride [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

If the datapagingoverride keyword is spe,cified in an OBY file, it overrides the configuration +for data paging for the executable 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.

+ + + +

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 N_y and the number of old pages is N_o. If N_y > RN_o, 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.

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 +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 + + + + +

Supported

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

+ + +

Upgradeable

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

+ + +

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.

+ + +

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.

+ + +

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.

+ + +

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 + + + + +

Supported

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

+ + +

Upgradeable

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

+ + +

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.

+ + +

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.

+ + +

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.

+ + +

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.

formatversion

formatversion= <format version>

Specifies the SMR image format version. This value is checked by +the SMR consumers (such as HCR) at runtime to ensure code compatibility +with image or data format.

+ \ No newline at end of file