Keyword reference

This page lists the keywords starting from P to R.

pagingoverride

pagingoverride [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

This overrides the code and data paging settings for all the files, such as EXE and DLL in an OBY file. 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:

pagingoverride NOPAGING

pagingpolicy

pagingpolicy [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

This overrides the default settings for both code and data paging. It also overrides the settings from all the previous levels. This keyword takes a single argument, which can be one of the possible values listed in pagingoverride.

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

pagingpolicy NOPAGING

patchdata

patchdata <binary_name> @ <symbolname> <newvalue>

BUILDROM only

This keyword is introduced since Symbian OS v9.3, and it enables you to change the value of a constant that is exported by a binary while building the ROM image.

This means that the value of the constant can be changed without rebuilding the binary. This is useful for quickly building ROM images with different values for the constant, allowing you to make comparisons in behaviour between the ROMs. This keyword must be placed before or after the binary that it patches in the OBY file.

<binary_name>

The name of the binary on the PC and not the name in the ROM image.

<symbolname>

The symbolic name of the constant exported by the binary.

<newvalue>

The replacement value. This can be specified either as an integer or as a hexadecimal value.

It is assumed that the exported constant is an integer that is either 1 byte, 2 bytes or 4 bytes in length, which means that the size of this replacement value must not exceed the capacity of the constant to represent it.

For example, if a DLL named dllA.dll is created based on the header file dllA.h and source file dllA.cpp:

//dllA.h
IMPORT_C int bar();
...
//dllA.cpp
#include “dllA.h”
EXPORT_C extern const unsigned int foo = 0x1234;
EXPORT_C int bar ()
    {
    return foo;
    ...
    }

then an executable file can import this constant; for example:

#include <e32cons.h>
#include <e32base.h>
#include “dllA.h”
...
int importValue = bar();
...

If you add the following statement to the .oby file to change the value of constant "foo" while building the ROM, then the actual value of foo accessed by the executable file is 0x100, and not 0x1234 as specified when DllA was originally built.

patchdata dllA @ foo 0x100

Notes:

  • The value of the constant in the source is not changed. It is only its value in the copy of the binary incorporated into the ROM image that is changed.

  • Do not define a patchable constant (exported data) in the source file in which it is referred to, because the compiler may inline it. If a constant is inlined, it cannot be patched. Hence, the constant must be defined in a separate source file and must be referred to in other source files by using the extern qualifier.

patched

patched

rombuild only

This is used when sectioning a ROM for language variants etc. If an executable is to be replaced, make it patched in the first section of the ROM and include a replacement in the top section of the ROM, after the section keyword.

This keyword appears at the point in the obey file where the ROM is to be split. All files before this line appear in the first (constant) section and files after appear in the second (patch/language) section.

platsecdiagnostics

platsecdiagnostics [on | off]

rombuild only

This is a keyword that affects Symbian platform security when building a ROM.

It controls whether or not diagnostic messages are emitted when a capability or other platform security policy check fails. A diagnostic message takes the general form:

*PlatSec* ERROR - xxxxx

if platform security is enforced

*PlatSec* WARNING - xxxxx

if platform security is NOT enforced.

The string xxxxx represents the text of the message that describes the capability being violated or the security policy check that is failing.

  • Specify on to enable diagnostic messages to be emitted.

  • Specify off to disable diagnostic messages from being emitted.

  • If neither on nor off is specified, then on is assumed as a default.

platsecdisabledcaps

platsecdisabledcaps [+|-]cap1 [+|- cap2] [+|- cap3] ...[+|-capn]

rombuild only

This is a keyword that affects Symbian platform security when building a ROM.

It allows capabilities to be added to, or removed from, all executables in the ROM image.

Specify a list of capability names prefixed either by a + character or a - character. The first capability name in the list does not need to prefixed by either of these characters, but if it is omitted a + character is assumed.

Capabilities preceded by a + character are added to all executables, while those preceded by a - character are removed from all executables.

Any of the capabilities listed in the left hand column in the table below can be specified; follow the corresponding link in the right hand column for a description of that capability. Note that you can also use:

+ALL

to add all capabilities, and

+NONE

to remove all capabilities.

Note, however, that the combinations -ALL and -NONE are not permitted

Capability
TCapability Enum value

TCB

ECapabilityTCB

CommDD

ECapabilityCommDD

PowerMgmt

ECapabilityPowerMgmt

MultimediaDD

ECapabilityMultimediaDD

ReadDeviceData

ECapabilityReadDeviceData

WriteDeviceData

ECapabilityWriteDeviceData

DRM

ECapabilityDRM

TrustedUI

ECapabilityTrustedUI

ProtServ

ECapabilityProtServ

DiskAdmin

ECapabilityDiskAdmin

NetworkControl

ECapabilityNetworkControl

AllFiles

ECapabilityAllFiles

SwEvent

ECapabilitySwEvent

NetworkServices

ECapabilityNetworkServices

LocalServices

ECapabilityLocalServices

ReadUserData

ECapabilityReadUserData

WriteUserData

ECapabilityWriteUserData

Location

ECapabilityLocation

For example:

PlatSecDisabledCaps LocalServices+ReadDeviceData+ReadUserData

platsecenforcement

platsecenforcement [on | off]

rombuild only

This is a keyword that affects Symbian platform security when building a ROM.

It controls whether or not platform security is enforced.

  • Specify on to enable platform security enforcement. If enforcement is enabled, and a capability or other platform security policy check fails, then the appropriate action for a failed platform security check occurs.

  • Specify off to disable platform security enforcement. If enforcement is disabled, and a capability or other platform security policy check fails, then the system continues as though the original platform security check had in fact passed.

  • If neither on nor off is specified, then on is assumed as a default.

platsecenforcesysbin

platsecenforcesysbin [on | off]

rombuild only

This is a keyword that affects Symbian platform security when building a ROM.

It controls whether or not to force the location of binary executables into the \Sys\Bin\ directory.

  • Specifying on has the following effects:

      • rombuild places all executables into Z:\Sys\Bin\, and overrides any file path specified in any of the .IBY files.

      • the loader only looks for files in the \Sys\Bin\ directory and only loads files from the \Sys\Bin\ directory. If a different path is specified this path is ignored and the \Sys\Bin\ directory is searched.

  • Specifying off causes rombuild to place files according to the file path specified in the .IBY files and permits the loader to load files from any specified path.

  • If neither on nor off is specified, then on is assumed as a default.

platsecprocessisolation

platsecprocessisolation [on | off]

rombuild only

This is a keyword that affects Symbian platform security when building a ROM.

It controls whether or not insecure APIs inherited from EKA1 (Versions 8.1a, 8.0a, 7.0s, and earlier) are to be disabled. These are APIs whose use is intended to be restricted. The kernel provides run-time checks for their correct usage.

See the list of APIs affected by the platsecprocessisolation keyword.

  • Specify on to disable insecure APIs. Incorrect use of this set of restricted APIs results in diagnostic messages, if platsecdiagnostics is on, and raises panics or causes errors if platsecenforcement is on.

  • Specify off to allow insecure APIs.

  • If neither on nor off is specified, then on is assumed as a default.

primary[[HWVD]]

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

rombuild only

A standard executable file that is loaded directly, bypassing the file server. The Boot program loads and gives control to the primary; this is the Kernel.

As with all standard executable files, this is loaded, relocated and stripped of its relocation information.

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

priority

priority = <hex-number> | <priority-keyword>

rombuild only

Sets the priority of the process. The priority can be a hexadecimal number, or one of the keywords listed below. The keywords correspond to the associated priority value.

Keyword

Process priority

low

EPriorityLow

background

EPriorityBackground

foreground

EPriorityForeground

high

EPriorityHigh

windowserver

EPriorityWindowServer

fileserver

EPriorityFileServer

realtimeserver

EPriorityRealTimeServer

supervisor

EPrioritySupervisor

reloc

reloc = <hex-address>

rombuild only

Overrides the default stack size for the executable.

rem

rem <comment>

rombuild and rofsbuild

Defines a comment line. Text that appears after the rem keyword is interpreted as a comment.

rename

rename[[HWVD]]= <existing-file> <destination-file> [ full-attribute-list ]

rombuild and rofsbuild

Adding a file and then renaming it is equivalent to adding it directly at the rename destination. The existing and destination directories do not have to be the same.

RIGHT_NOW

RIGHT_NOW

BUILDROM only

A pre-defined substitution. This is replaced with the exact time in the format dd/mm/yy hh:mm:ss

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

rofsname

rofsname = <filename>

rofsbuild only

Defines the name of the core image.

rofssize

rofssize = <size in bytes>

rofsbuild only

Specifies the maximum size of the core image, or the maximum size of the extension.

romalign

romalign = <hex-alignment>

rombuild only

The address alignment boundary for files in the ROM.

This value should be greater than 4 and a multiple of 4. The recommended value is 0x10. If no value is specified, rombuild defaults to using a value of 0x1000. If the value specified is not a multiple of 4, it is rounded off.

ROMBUILD_OPTION

ROMBUILD_OPTION <command-line-option>

BUILDROM only

Adds additional command line parameters to the eventual invocation of rombuild. It is primarily used to specify the -no-header option for platforms which don't want the 256-byte REPRO header. The ROMBUILD_OPTION keyword can be used multiple times if desired.

romchecksum

romchecksum = <32 bit hex-number>

rombuild and rofsbuild

The checksum in the final ROM image is made using the following algorithm:

checksum = romchecksum - sum of 32bit words in ROM image.

ROM_IMAGE

ROM_IMAGE <id> <name> [size=<rom max size>] [xip | non-xip] [compress | no-compress] [extension]

BUILDROM only

Defines a ROM image.

This is a ROM configuration feature; up to 8 ROM images can be defined for a device.

id

A value in the range 0..7 to identify the ROM image.

name

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

non-xip

Specifies a non-XIP ROM. If not specified, a XIP ROM is the default

size = <rom-max-size>

Defines the maximum size of the ROM. Not required for XIP ROMs.

compress

Compresses an XIP ROM. If not specified, no compression is the default behaviour.

extension

Defines this image as an extension to the previous image.

To mark a file for inclusion in a ROM it is prefixed with the keyword ROM_IMAGE. For example:

ROM_IMAGE[2] data=ZSYSTEM\Apps\Calc\calc.INSTCOL_MBM System\Apps\Calc\Calc.mbm

A Block of files can be included using '{' '}' braces, for example:

ROM_IMAGE[2]
    {
    #include "calc.iby"
    #include "word.iby"
    }
      

File blocks can be nested, for example:

ROM_IMAGE[2]
    {
    #include "calc.iby"
    ROM_IMAGE[0]
        {
        #include "word.iby"
        }
    #include "video.iby"
    }
      

romlinearbase

romlinearbase = <hex-address>

rombuild only

The virtual address of the start of ROM, in hex.

This is the address at which the kernel expects to find the start of the ROM. The recommended value depends on the memory model:

  • For the Multiple Memory Model, typically used on ARMV6 based hardware platforms, the recommended value is 0x80000000.

  • For the Moving Memory Model, typically used on ARMV5 based hardware platforms, the recommended value is 0xF8000000.

romname

romname = <rom-file-name>

rombuild only

This is the name of the output file. It contains the ROM image that rombuild creates.

romnameeven

romnameeven = <rom-file-name-even>

rombuild only

rombuild can write two separate ROM images, one containing the odd bytes of the image and the other the even. This is done if this keyword and the romnameodd keyword are used to specify the output filenames for the two half-images. A filename of "*" can be specified, which means use the file name specified on the romname keyword and append .even.

romnameodd

romnameodd = <rom-file-name-odd>

rombuild only

rombuild can write two separate ROM images, one containing the odd bytes of the image and the other the even. This is done if this keyword and the romnameeven keyword are used to specify the output filenames for the two half-images. A filename of "*" can be specified, which means use the file name specified on the romname keyword and append .odd.

romsize

romsize = <hex-size>

rombuild and rofsbuild

The size of the entire ROM, in hex, for example, 0x400000 for a 4MB ROM.