Keyword reference

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.

BTraceBuffer

BTraceBuffer = N

rombuild only

A keyword for configuring the behaviour of the Symbian platform trace handler.

Use this keyword to set the initial size for any memory buffer used to store trace data.

See also Base How To BTrace.

BTraceMode

BTraceMode = N

rombuild only

A keyword for configuring the behaviour of the Symbian platform trace handler.

Use this keyword to set the initial mode of the trace handler. This BTRaceBuffer keyword takes a single integer that specifies the mode. For the default trace handler supplied with Symbian platform, this will be one of the RBTrace::TMode enum values defined in the header file d32btrace.h.

See also Base How To BTrace.

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:

1

collapse import thunks only

2

collapse import thunks and vtables

3

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

ArgumentPurpose

NOPAGING

To mark all executables as unpaged, irrespective of whether they are marked as paged or unpaged in the MMP file.

ALWAYSPAGE

To mark all executables as paged, irrespective of whether they are marked as paged or unpaged in the MMP file.

DEFAULTUNPAGED

All executables, which are not marked as paged or unpaged are marked as unpaged by default.

DEFAULTPAGED

All executables, which 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 the codepagingpolicy is defaultunpaged.

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

codepagingpolicy NOPAGING