Keyword reference (A-C)

This page lists the keywords starting from A to C.

## ##

BUILDROM only

Performs textual substitution. +All subsequent instances of the two characters ## are replaced with +an empty string.

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

ABI_DOWNGRADE ABI_DOWNGRADE from->to

BUILDROM only

Allows BUILDROM to substitute a compatible executable if a specified source file +is not available.

The use of this keyword is not appropriate +for production devices, but is useful in the development environment +as it increases the chances of producing a ROM in the presence of +build problems.

For example,

ABI_DOWNGRADE THUMB->ARMI

This substitutes \ARMI\ for \THUMB\ if a specified source file +cannot be found.

Another example is in localisation support. +Problem suppression allows BUILDROM to handle a missing source.Enn file by specifying source.EXT instead. In a final pass, if any file is still not available after +applying these downgrades, then BUILDROM will simply +comment out the line in the .oby file in the +hope that the missing file is not vital to the ROM. If this behaviour +is not appropriate, then the command line option -s can be used to enforce stricter behaviour and cause BUILDROM to terminate after the final pass if files are missing.

alias[[HWVD]] alias[[HWVD]] = <existing-file> <destination-file> [ directory-attribute-list ]

rombuild and rofsbuild

Creates an additional +filesystem entry, which refers to an existing file. rombuild allows directory aliases to preserve the guarantee that the ROM +filesystem should not contain cycles. The existing-file must not be +hidden, and both names are now available to resolve DLL static linkage.

align align = <hex-number>

rombuild only

Specifies the alignment boundary +for the file that follows immediately after the align statement.

area area = <name>

rombuild only

Defines the area in which the +executable will be relocated. The specified name must have been previously +defined in the area control statement.

area area = <name> <run-address> <maxlength>

rombuild only

Defines a new relocation area. +The area is identified by the specified name. Executable files placed +in this area will be relocated so that they run in the address range X, where X is defined as:

<run-address> <= X < <run-address> + <maxlength>.

The Bootstrap is required +to copy the relevant subset of ROM to the run address at Boot time. +The main purpose of this is to relocate time-critical executables +to internal or tightly-coupled RAM.

ascii ascii

rombuild only

Indicates that this is not a Unicode +build.

attrib attrib = [ s | S ][ h | H ][ r | R | w | W ] | hide

rombuild and rofsbuild

Files may have the System, +Hidden, read-only and writable attributes.

File attributes +are copied from the source file and are then overridden by the attributes +specified by this keyword. Specifying S, H, or R sets the corresponding attribute; +specifying s, h or r clears it.

W and w are +synonyms for R and r respectively. To mark a file +in the ROM as being writable, specify attrib=W.

As this is a ROM, the file cannot be physically modified even +if the read-only attribute is cleared, but it is useful to mark files +as writeable so that copies are made writeable, for example on a CF +card or a RAM file system.

Using the hide attribute indicates that the file should be included in the ROM +but not recorded in the ROM filesystem. If the file is a DLL it will +be available for resolving static links from other files in the same +ROM, but not available to RAM-loaded software or DLLs in an extension +ROM.

AUTO-BITMAP AUTO-BITMAP=<source> <dest>

BUILDROM only

Either selects a compressed MBM +file if generating an XIP ROM image, or the original source file if +generating a non-XIP ROM image

This statement translates to COMPRESSED-BITMAP for XIP ROMs and to data for non-XIP ROMs.

autosize autosize = <block size>

rofsbuild only

Reduces the size to a whole number +of blocks where <block size> defines the granularity.

For +example if rofsize is set to 0x30000 and the actual image size is 0x1234, +then the generated image size without the autosize option is +0x30000. If autosize is set to 0x1000, then the generated image size +is 0x2000.

BINARY_SELECTION_ORDER BINARY_SELECTION_ORDER=<source-build1>,<source-build2>,..

This causes the tools to check the given locations for files +in the specified order:

BINARY_SELECTION_ORDER=GCCE, ARMV5_ABIv2

causes buildrom to first check the GCCE directory +for files and then if not found there, to look in the ARMV5_ABIv2 directory.

BITMAP BITMAP=<source> <dest>

BUILDROM only

Generates an uncompressed Symbian platform XIP ROM format MBM file from the <source> MBM +file and copies it into the ROM at <dest>.

bootbinary bootbinary = <boot-file-name>

rombuild only

The file name of the ROM's bootstrap +code, which on ARM CPUs appears at physical address 0x00000000 when +the machine is booted.

BTrace BTrace = N1 [N2 [N3 [N4 [N5 [N6 [N7 [N8]]]]]]]

rombuild only

A keyword for configuring the +behaviour of the Symbian platform mechanism for generating and capturing +trace information (BTrace).

Each trace +has a category which is 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). This keyword sets 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.

The BTrace keyword +takes up to eight 32-bit integers, representing a set of 256 bits. +Each bit in the set 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.

The rule for mapping the bits in these eight integers to the BTrace::TCategory values is as follows: to turn on trace +category C, where C is one of the BTrace::TCategory enum values, set bit position C%32 to one in integer Nx where x = C/32.

+ +

For example to turn on the trace category ECodeSegs, (i.e. the trace generated when code segments are created and destroyed +mapped into out of processes, and when memory is committed and decommitted) +you would specify:

BTrace 0x00000200

which turns on bit position 9 (counting from zero and starting +at the right hand side of the integer). Note that there is no need +to specify the remaining 7 integers if they all have zero values, +as zero is assumed by default.

See also Base How To BTrace.

capabilitycapability = <capability-names>

rombuild +only

This keyword overrides platform security capabilities +of the executable specified in the OBY file. For information on the +use of capabilities and current capability set, see Platform security +architecture in the Symbian C++ Developer +Library.

clustersizeclustersize=<cluster-size>

This keyword +specifies the cluster size for a FAT image generated by the ROM tools. +The keyword must be specified in the DATA_IMAGE[x] section of the OBY file. If it is not specified in the DATA_IMAGE[x] section, a warning is displayed.

The value of the cluster +size must meet the following conditions:

The cluster size must be between 512 bytes and 32KB (sector +size).
- For a FAT16 image, the cluster size must be in the range 4101– +65508 bytes.
- For a FAT32 image, the cluster size must be greater than 65541 +bytes.
The cluster size must belong to the geometric progression series, +512, 1024, 2048, 4096, and so on. A geometric progression series is +a sequence of numbers where each term after the first is found by +multiplying the previous one by a fixed number called common ratio. +In this series, the first number of the series is 512 and the common +ratio is 2.

code-align code-align = <hex-number>

rombuild only

This keyword specifies the alignment +for the executable's code. It indicates the start address of a code +segment that must be aligned to a specified value. If the original +address of the code segment does not match the alignment, the whole +executable file is relocated to meet alignment. After the image is +loaded in RAM a block of memory is unused.

The code alignment +is an optimisation depending on the hardware the ROM is being built +for. Setting the code align can allow the ROM to be built in such +a way that it reduces the work for the CPU when loading the code that +is, it can be loaded in one pass. This improves the performance. If +it is unaligned it can take multiple passes.

For example:

Define an .oby file:
file=\epoc32\release\armv5\urel\helloworld.exe sys\bin\helloworld.exe code-align = 0x1000
Build ROM with +the above .oby file.
The log file +is:
Code Align to 8161f000. Skipped 2296 bytes + + ******************************************************************** + Processing file \epoc32\release\armv5\urel\helloworld.exe + Load Address: 8161ef88 + Size: 000004a8 + Uids: 1000007a e8000047 00000000 0dcafc2f + Entry point: 8161f000 + Code start addr: 8161f000

In the log file, we can find that the code start address +of helloworld.exe matches the alignment 0x1000. To do that, a gap is generated before helloworld.exe that is,after the image is loaded in RAM +a block of memory is unused.

It is unique for ekern.exe, which is at least page aligned. If the value of code-align is less than page size, ekern.exe will be aligned +as page size. Otherwise, ekern.exe will be aligned +as the value of code-align.

Note: If an .oby file includes this keyword, the +size of ROM image is same. But the size loaded in RAM is slightly +larger than the original.

coffwrapper coffwrapper

rombuild only

Indicates that a COFF ROM wrapper +is required.

collapse collapse = <cpu> <compiler> <mode>

rombuild only

This is only supported when the +<cpu> is ARM and the <compiler> is GCC.

The <mode> +can take one of the following values:

+ + + +

collapse import thunks only

+ + +

collapse import thunks and vtables

+ + +

collapse branches

+ + + +

compress compress

rombuild only

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

COMPRESSED-BITMAP COMPRESSED-BITMAP=<source> <dest>

BUILDROM only

Generates a compressed Symbian +platform XIP ROM format MBM file from the <source> MBM file and +copies it into the ROM at <dest>.

coreimage coreimage = <core image file>

rofsbuild only

This tells rofsbuild that the +generation of the core image is not required and that the specified +core image should be used to as the base for generating the extension +image.

codepagingoverride codepagingoverride [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

This keyword sets the +page attributes of executables at a global level. It is applicable +to all executables in ROM or ROFS partitions. It takes a single argument, +which can be one of the following:

+ + + +Argument +Purpose + + + + +

NOPAGING

All executables are marked as unpaged, irrespective of whether +they are marked as paged or unpaged in the MMP file.

+ + +

ALWAYSPAGE

All executables are marked as paged, irrespective of whether +they are marked as paged or unpaged in the MMP file.

+ + +

DEFAULTUNPAGED

All executables that are not marked as paged or unpaged +are marked as unpaged by default.

+ + +

DEFAULTPAGED

All executables that are not marked as paged or unpaged +are marked as paged by default.

+ + + +

For example, the following entry in the Obey file marks +all the executables as unpaged:

codepagingoverride NOPAGING

codepagingpolicy codepagingpolicy [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

This sets a flag in +the ROM when it is built, and the loader in the kernel decides a policy +for executables that are in default state (neither marked as paged +nor as unpaged). This keyword takes a single argument, which can be +one of the possible values listed in codepagingoverride. The default value for codepagingpolicy +is DEFAULTPAGED.

For example, the following +entry in the Obey file instructs the loader not to page the executables +in default state:

codepagingpolicy NOPAGING