Making a ROM image
Introduction
This section describes the syntax and use of the ROM building tool, the organisation and format of the obey files which drives the operation of the tool and finally describes the structure and format of ROM images.
The tool used to build a ROM image is BUILDROM. This tool uses two other tools ROMBUILD and ROFSBUILD to produced ROM images. The ROMBUILD tool is used for XIP ROMs. ROFSBUILD is used for Non-XIP ROMs.

Building a ROM requires that the following are available or have been successfully created:
•	Symbian OS components making up a set of releasables
•	a Bootstrap binary image
•	a text file specifying how the ROM image is to be built.

Executables are pre-processed, relocated, and have their imports and exports bound for a ROM image based at some given virtual address. The files, base address of the ROM, and various other parameters are specified by means of the obey file. This is a file of type .oby and is a text file containing statements that specify how the ROM image is to be built. A .oby file can include other files in the same way that files containing C++ source can #include other C++ files. By convention, the included files have the .iby file type. This structure allows flexibility in the way that ROM images are defined.
The ROM building process produces a log, which is written to rombuild.log in the current directory.
BUILDROM processes obey files written in a superset of the language supported by ROMBUILD and ROFSBUILD. Depending on whether an XIP ROM or non XIP ROM image is being generated it will produce an obey file which is directly acceptable to ROMBUILD or ROFSBUILD. It then invokes either ROMBUILD or ROFSBUILD on the final obey file and performs a number of post-processing steps to produce a ROM symbol file and directory listing.
The import or relocation sections of an executable are no longer needed when that executable is bound into a ROM. These sections are removed as part of the ROM building process, reducing the size taken up by that executable.
A file header mapped by the TRomImageHeader class replaces the standard image file header.
The Bootstrap code and the file/directory structure imposes a small overhead on a ROM.
BUILDROM
BUILDROM is the Symbian OS ROM configuration tool.  BUILDROM is designed to be a unified ROM building front-end to the binary ROM building tools ROMBUILD and ROFSBUILD. 
BUILDROM provides features to specify multiple ROMs for a target device.  The characteristics of each ROM are described to the ROM builder which determines how they are built.  Characteristics: XIP-ness, compression, and extensions.  Each file to be included in the ROM can be steered into any of the specified ROM images. BUILDROM can ensure that all the files destined for the ROM exist.
BUILDROM assembles an XIP obey files suitable for ROMBUILD, and non-XIP obey files for ROFSBUILD. It automatically provides the appropriate headers required to generate extensions if they are specified.  
The initial obeyfile is modified by C++ preprocessor directives and subsequently adjusted by statements in the ROM specification language. The C++ preprocessor is applied to the file(s) before processing, and the C++ #define, #ifdef  and #include facilities should be used to control the inclusion and exclusion of source lines. The modifications to the content of those lines should be done using the BUILDROM textual substitution facility.
The final obey file is in the subset of the specification language which is understood directly by ROMBUILD or ROFSBUILD
BUILDROM keywords are not case-sensitive.
Each obyfile parameter specifies a file via a search path: if the filename is not matched then BUILDROM will look in \epoc32\rom\include.
Usage:
  buildrom [options] obeyfile [obeyfile2 ...]   
The available options are
-Dxxx	C++ preprocessor arguments	
-o<image name>	ROM image name, overriding any ROMNAME statement 	
-s	strict option, any missing files will stop buildrom without generating a ROM image. Without this option it is possible to generate a ROM image with missing files.	

Popular -D defines to use include
   -D_DEBUG		select debug versions of some files
   -D_FULL_DEBUG	select debug versions of all files
   -D_ARM4
   -D_ARM4T		specify the target platform
   -D_KABI=xxxx	specify the target platform for the Kernel (e.g. ARMV5)
Strict checking of missing files.
BUILDROM will normally ignore any missing files specified in the obey files. To prevent the generation of the ROM image when files are missing the -s option is used. This ensures that BUILDROM terminates after all the files have been checked and some are found missing. The error message indicates how many files are missing.
Automatic generation of extension header for XIP ROM
If the ROM_IMAGE specifices an XIP image with an extension, than the following header will automatically be added to the obey file. 
extensionrom=<name>
romsize=<rom max size>
The <name> and <rom max size> are as specified in the ROM_IMAGE keyword. 

The addition of the header will result in rombuild tool producing multiple images from the obey file.
ROMBUILD
ROMBUILD is the Symbian OS binary XIP ROM builder.  It is typically invoked through BUILDROM.  ROMBUILD understands a sub-set of the BUILDROM obey file syntax.
ROMBUILD allows a ROM extension to be added to the ROM base.  The extension enables renaming and hiding of files in the ROM base, and also allows new files to be added to the ROM drive.
Syntax: 
ROMBUILD [options] <obeyfilename>
Options can be:
-v	verbose	
-?	display more detailed help for command	
-s[log|screen|both]	display size summary to the specified destination	
-r<FileName>	compare a sectioned Rom image	
-no-header	suppress the image loader header	
-check-capabilities	Enforce Platform Security capabilities	
-check-datacaging	Enforce Data Caging	
-coff-header	use a PE-COFF header rather than an EPOC header	
-d<bitmask>	set trace mask (DEB build only)	
-compress	compress the ROM Image	
-no-sorted-romfs	do not add sorted entries arrays (6.1 compatible)	

ROFSBUILD
ROFSBUILD is the Symbian OS non-XIP ROM builder. ROFSBUILD understands a sub-set of the BUILDROM obey file syntax
ROFSBUILD allows a ROM extension to be added to the ROM base.  The extension enables renaming and hiding of files in the ROM base, and also allows new files to be added to the ROM drive.
Syntax: 
ROFSBUILD [options] <obeyfilename>
Options can be:
-v	verbose	
-?	display help for command	
-s[log|screen|both]	display size summary to the specified destination	
-d<bitmask>	set trace mask (DEB build only)	
-compress	compress executable files where possible	
-coreimage <core image file>	use the specified core image file as the basis for creating the extension	

Obey Files
Obey files are standard text files containing statements that are used to control the operation of the ROM building tools. Each of the tools (BUILDROM, ROMBUILD and ROFSBUILD) can handle different subsets of the obey file syntax. 
The obey file syntax handled by BUILDROM includes the following:
•	BUILDROM specific keywords/macros
•	Common keywords for both ROMBUILD and ROFSBUILD
•	ROMBUILD specific keywords
•	ROFSBUILD specific keywords
The obey file syntax handled by ROMBUILD includes the following:
•	Common keywords for both ROMBUILD and ROFSBUILD
•	ROMBUILD specific keywords
The obey file syntax handled by ROFSBUILD includes the following:
•	Common keywords for both ROMBUILD and ROFSBUILD
•	ROFSBUILD specific keywords
By convention, obey files have a .oby extension. Also by convention, any files included by the obey file have a .iby extension.
Syntax conventions
The following conventions apply to obey file statements:
•	most statements are in lower case
•	case is significant
•	a line that is a comment can be identified using the rem keyword
•	blank lines are ignored
•	the = symbol, where used, is optional; a blank character can be used instead
•	a file name can, optionally, be enclosed within quotes; a file name that contains spaces must be enclosed within quotes
•	the stop statement causes the rest of the obey file to be ignored
Overview
An obey file consists of a number of sections, each defining a ROM image:
•	the kernel-rom-section defines a bootable ROM image which includes the Kernel
•	each extension-rom-section defines a ROM image which extends the kernel-rom-section.
Every section contains a list of obey statements that specify ROM configuration information or files to be included in the ROM image.
Each section is scanned twice. This allows the configuration information to appear anywhere in the list. 
Extension ROM sections are marked by the extensionrom keyword, and can only contain those ROM information statements that are not related to Kernel configuration.
BUILDROM Specific Keywords
The keywords in this section are only seen by the BUILDROM tool and are usually converted into something suitable for ROMBUILD or ROFSBUILD. 
Textual Substitution
BUILDROM implements a simple textual substitution scheme: the C++ preprocessor cannot be used conveniently because it inserts whitespace around the substituted text.
DEFINE <name> <replacement>	All subsequent instances of <name> will be replaced by <replacement>.	
##	will replace "##" with an empty string.	

There are three pre-defined substitutions
EPOCROOT	the value of the EPOCROOT environment variable	
TODAY	today's date as dd/mm/yyyy	
RIGHT_NOW	the exact time as dd/mm/yyyy hh:mm:ss	

There is no "UNDEFINE" facility, and the substitutions are applied in an unspecified order.
Additional Simple Keywords
BUILDROM implements the following simple keywords
ECHO <anything at all>	Simply prints the rest of the line to standard output.	
WARNING <anything at all>	Reports the source file and line number as well as printing the message	
ERROR <anything at all>	Reports the source file and line number as well as printing the message. Any ERRORs will cause BUILDROM to abort without attempting to create the ROM.	
ROMBUILD_OPTION <command-line-option>	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	
 
Localisation Support
BUILDROM implements the MULTILINGUIFY() macro that can expand a single source line into multiple
lines referring to distinct language codes.
LANGUAGE_CODE <nn>	Can be used multiple times to specify the Symbian 2-digit codes for languages to be supported in this ROM.	
DEFAULT_LANGUAGE <nn>	Used to specify the default language. It should only be used once.	
data=MULTILINGUIFY(EXT <sourcename> <destname>)	During the localisation pass, the MULTILINGUIFY lines are expanded into a line per language code. 	

Example for the MULTILINGUIFY macro.
The line:
    data=MULTILINGUIFY( EXT sourcename destname )
becomes
    data=sourcename.Enn destname.EXT	for the default language code nn
    data=sourcename.Enn destname.Enn	for all other language codes nn

This provides support for the BafUtils::NearestLanguageFile() function, which is performing a similar mapping from language codes to filenames.
XIP ROM format bitmaps
MAKMAKE normally generates EPOC MBM files in a compressed format, but there is an alternative uncompressed format which allows an MBM to be used directly from the ROM filesystem. BUILDROM supports on-the-fly generation of ROM format MBM files from compressed MBM files using the BITMAP keyword as follows
BITMAP=<source> <dest>	BUILDROM creates an intermediate file using the BMCONV utility. 	
COMPRESSED-BITMAP=<source> <dest>	If the files are already compressed then the    COMPRESSED-BITMAP keyword has to be used in the same way as the BITMAP keyword. Different parameters to BMCONV utility are used to create the appropriate format	

BUILDROM will use an existing intermediate file if it is newer than the corresponding source file.
XIP and Non-XIP ROM format bitmaps
BUILDROM provides a keyword to automatically select between XIP and non-XIP versions of bitmaps.This is used when it is not known by the application author if the bitmap is to be included in an XIP or non-XIP ROM.
AUTO-BITMAP=<source> <dest>	This keyword will use "compressed-bitmap=" for XIP ROMs and "data=" for non-XIP ROMs.	
XIP and non-XIP ROM format AIF files
A keyword is provided to automatically select between XIP and non-XIP versions of AIF files.
AIF=<source> <dest>	This keyword will use the _xip version of the specified AIF for XIP ROMs or the originaly supplied file otherwise	
Source reorganisation for two-section ROMs
ROMBUILD and ROFSBUILD have the ability to create ROMs divided into two sections, such that the upper section can be replaced without needing to change the lower section. This facility is most often used to put localised resource files into the upper section, so BUILDROM provides support for gathering marked obey source lines and placing them in the upper section of the ROM.
SECTION2 <anything>	All lines beginning with the SECTION2 keyword are removed from the OBY file, and placed into a separate list with the SECTION2 keyword removed. When BUILDROM encounters the SECTION keyword, the accumulated section2 list is inserted after the SECTION line, and subsequent SECTION2 keywords are removed as they occur. If no SECTION line is encountered, the accumulated section2 list is emitted after the end of the input file(s).	
Example
    LANGUAGE_CODE 01
    LANGUAGE_CODE 10
    DEFAULT_LANGUAGE 10
    file=sourcedir\myapp.dll destdir\myapp.dll
    SECTION2 REM bitmaps for myapp
    SECTION2 bitmap=MULTILINGUIFY( MBM sourcedir\myapp destdir\myapp )
    file=sourcedir\myengine.dll destdir\myengine.dll
    section 0x800000
    file=sourcedir\example destdir\example
    SECTION2 data=sourcedir\example2 destdir\example2

would become
    
    file=sourcedir\myapp.dll destdir\myapp.dll
    file=sourcedir\myengine.dll destdir\myengine.dll

    section 0x800000
    REM bitmaps for myapp
    data=sourcedir\myapp.M01_rom destdir\myapp.M01
    data=sourcedir\myapp.M10_rom destdir\myapp.MBM

    file=sourcedir\example destdir\example
    data=sourcedir\example2 destdir\example2
Problem suppression
BUILDROM does a number of things which probably are not appropriate for producing production devices, but which increase the chance of Symbian internal development builds producing a ROM in the presence of build problems.
ABI_DOWNGRADE   from->to	Allows BUILDROM to substitute a compatible executable if the specified source file is not available. For example
It is usually used as
ABI_DOWNGRADE   THUMB->ARMI
This will substitute \ARMI\ for \THUMB\ if a specified source file cannot be found.	

In the 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 required 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. 
Rom configuration support
BUILDROM has ROM configuration features to support building of multiple xip and non-xip ROMs for the same device.
First you must specify the ROM devices
The ROM_IMAGE keyword specifies a ROM image.  There can be up to 8 images.
ROM_IMAGE <id> <name> [size=<rom max size>] [xip | non-xip] [compress | no-compress] [extension]	where:
id = 0 .. 7
name = a name suitable as a suffix for the ROM image, oby and logs
xip = specifies an XIP ROM.  This is the default.
size = max size of the ROM.  Not required for XIP roms.
compress = Compress an XIP ROM.
extension = Indicates this image as an extension to the previous image.	

Including files
 To mark a file for inclusion in a ROM it is prefixed with the keyword
ROM_IMAGE[<id>]
eg.
ROM_IMAGE[2] data=ZSYSTEM\Apps\Calc\calc.INSTCOL_MBM System\Apps\Calc\Calc.mbm
 A Block of files can be included using '{' '}' braces.
eg.
ROM_IMAGE[2] {
#include "calc.iby"
#include "word.iby"
}
File blocks can be nested eg.
ROM_IMAGE[2] {
	#include "calc.iby"
	ROM_IMAGE[0] {
		#include "word.iby"
	}
	#include "video.iby"
}

General Structure of Obey file
The general syntax is:
obey-file : kernel-rom-section | core-image-statement [ extension-rom-list ]

kernel-rom-section : obey-statement-list

The core-image statement is valid for non XIP ROMs only and is only handled by ROFSBUILD.
core-image-statement: coreimage=core-image-filename

extension-rom-list : extension-rom-section | extension-rom-section extension-rom-list

extension-rom-section : extensionrom = rom-file-name obey-statement-list

obey-statement-list : obey-statement | obey-statement obey-statement-list

obey-statement : rom-information-statement | file-statement

The general syntax of a rom-information-statement is:
rom-information-statement : kernel-information-statement | generic-information-statement | rofs-information-statement

kernel-information-statement : 
romname = rom-file-name
| bootbinary = boot-file-name
| kerneldataaddress = hex-address
| kernelheapmin = hex-size
| kernelheapmax = hex-size
| singlekernel
| multikernel
| areas = number-of-areas
| kerneltrace = 32bit-hex-number
| kernelromname = rom-file-name

generic-information-statement : 
romnameodd = rom-file-name-odd
| romnameeven = rom-file-name-even
| srecordfilename = srec-file-name
| srecordbase = hex-address
| version = [ major ] [ .minor ] [ (build) ]
| romsize = hex-size
| romlinearbase = hex-address
| romalign = hex-alignment
| dataaddress = hex-address
| romchecksum = base-checksum
| time = dd/mm/yyyy hh:mm:ss
| trace = 32bit-hex-number
| debugport = 32bit-number
| collapse = cpu compiler mode
| ascii
| unicode
| coffwrapper
| compress
| defaultstackreserve = <default stack reserve>
| dlldatatop = <address of data region>
| memmodel = moving | direct | multiple <chunk size> <page size>
| nowrapper

rofs-information-statement:
autosize = <block size>
| extensionrofs
| extensionrofsname = <filename>
| rofsname = <filename>
| rofsize = <size in bytes>

The general syntax of a file-statement is:
file-statement : file-specification-statement | control-statement | rom-directory-statement

file-specification-statement : 
data[[HWVD]] = source-file destination-file [directory-attribute-list]    
| file[[HWVD]] = source-file destination-image-file [full-attribute-list] 
| primary[[HWVD]] = source-file destination-image-file [full-attribute-list]
| secondary = source-file destination-image-file [full-attribute-list]
| variant[HWVD] = source-file destination-image-file [full-attribute-list]
| device[[HWVD]] = source-file destination-image-file [full-attribute-list]
| extension[[HWVD]] = source-file destination-image-file [full-attribute-list]
| dll [[HWVD]] = source-file destination-image-file [full-attribute-list] 
| filecompress [[HWVD]] = source-file destination-image-file [full-attribute-list]
| fileuncompress [[HWVD]] = source-file destination-image-file [full-attribute-list]

control-statement : 
rem comments
| section = section-offset
| extensionrom = <rom filename>
| align = alignment
| area = name run-address maxlength
| stop

rom-directory-statement : 
hide[[HWVD]] = existing-file
| alias[[HWVD]] = existing-file destination-file [ directory-attribute-list ]
| rename[[HWVD]]= existing-file destination-file [ full-attribute-list ]

full-attribute-list : full-attribute | full-attribute full-attribute-list

full-attribute : directory-attribute | file-attribute

directory-attribute-list : directory-attribute | directory-attribute directory-attribute-list

directory-attribute : 
     attrib = [ s | S ][ h | H ][ r | R | w | W ] | hide

file-attribute : 
stack = hex-size
| reloc = hex-address
| heapmin = hex-size
| heapmax = hex-size 
| code-align = hex-number
| fixed
| priority = hex-number | keyword
| patched
| uid1 = uid
| uid2 = uid
| uid3 = uid
| stackreserve = hex-size
| area = name
Directory attributes
     attrib = [ s | S ][ h | H ][ r | R | w | W ] | hide
Files can 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 also made writeable, for example, if copied onto a CF card or a RAM file system.
Using the hide keyword indicates that the file should be included in the ROM but not recorded in the ROM filesystem. If it is a DLL, then it is still available to resolve DLL static links from other files in the same ROM, but is not available to RAM-loaded software or DLLs in an extension ROM.
File attributes
Executable files already have various settings such as UIDs and default stack size recorded when they were processed by petran, but rombuild allows these settings to be overridden, if necessary. There are also a number of other attributes which control the way that the executable is loaded into the ROM image.
stack
stack = hex-size
Overrides the default stack size for the executable.
reloc
reloc = hex-address
Supplies a new user-process data run address to which the file is relocated. This parameter is not allowed with files of type: device, extension and variant.
heapmin
heapmin = hex-size
Overrides the default minimum heap size for the executable.
heapmax
heapmax = hex-size
Overrides the default maximum heap size for the executable.
code-align
code-align = hex-number
Specifies the alignment for the executable's code.
fixed
fixed
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. The multiprocess keyword can be used to specify the chunk size used in allocating data space in high memory; it defaults to 1Mb.
priority
priority = hex-number | priority-keyword
Sets the priority of the process.
The priority can be a hexadecimal number, or one of the keywords listed below:
 
Keyword 	Process priority	
low	 EPriorityLow	
background	 EPriorityBackground	
 foreground	 EPriorityForeground	
 high	 EPriorityHigh	
 windowserver	 EPriorityWindowServer	
 fileserver	 EPriorityFileServer	
 realtimeserver	 EPriorityRealTimeServer	
 supervisor	 EPrioritySupervisor	
 
patched
patched
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.
Note that the original file is still required to guarantee consistency in the first section of the ROM.
For example, supposed we are replacing TESTEG.DLL in a UK ROM with TESTFR.DLL in a French one.
The original obey file might have a line such as:
file=\Epoc32\Release\Mcog\rel\testeg.dll System\Libs\TEST.DLL
The new obey file would look like this:
file=\Epoc32\Release\Mcog\rel\testeg.dll System\Libs\TEST.DLL patched
...
section = 0x200000
file=\Epoc32\Release\Mcog\rel\testfr.dll System\Libs\TEST.DLL
NB, it is not possible to patch any files which are listed before the primary or the secondary.
uid1, uid2, uid3
uid1 = uid-value
uid2 = uid-value
uid3 = uid-value
Overrides the UIDs for the executable.
area
area = name
Defines the area in which the executable will be relocated. The specified name must have been previously defined in the area control statement.
Common keywords
alias
alias[[HWVD]] = existing-file destination-file [ directory-attribute-list ]
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.
data
data[[HWVD]] = source-file destination-file [directory-attribute-list]
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.
file
file[[HWVD]] = source-file destination-image-file [full-attribute-list]
A standard executable file, i.e. 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.
Note that the HWVD is optional but, if specified, must be enclosed within square brackets.
hide
hide existing-file
Marks the existing file as hidden. The file is still available to resolve DLL static links.
rem
rem comment
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 ]
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.
romchecksum
romchecksum = 32 bit hex-number
The checksum in the final ROM image is made using the following algorithm:
checksum = romchecksum - sum of 32bit words in ROM image.
romsize
romsize = hex-size
The size of the entire ROM, in hex, e.g. 0x400000 for a 4MB ROM.
stop
stop
stops processing of the obey file. The rom image is not generarted
time
time = dd/mm/yyyy hh:mm:ss
If specified, overwrites the date-time stamp of the ROM image with this value. If not specified, the image is time and date stamped from the system clock of the build PC.
trace
trace = 32 bit hex-number
Turns on rombuild tracing. This is internal to Symbian.
version
version = [ major ] [ .minor ] [ (build) ]
The ROM version number. The version number is returned by Hal::RomVersion().
ROMBUILD specific keywords
align
align = <hex-number>
Specifies the alignment boundary for all subsequent files, or until another align control statement is met.
area
area = <name> <run-address> <maxlength>
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 areas is to relocate time-critical executables to internal or tightly-coupled RAM.
Directory attributes
ascii
ascii
Indicates that this is not a Unicode build.
bootbinary
bootbinary = <boot-file-name>
File name of the ROM's bootstrap code which, on ARM CPUs, appears at physical address 0x00000000 when the machine is booted.
coffwrapper
coffwrapper
Specifies that a COFF ROM wrapper is required.
collapse
collapse = <cpu> <compiler> <mode>
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
Compress the ROM image
dataaddress
dataaddress = <hex-address>
Linear address of data/bss chunks for all executables except the Kernel.
The recommended value is 0x400000.
debugport
debugport = <32bit-number>
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>
Specify the maximum size of the stack.
device
device[[HWVD]] = source-file destination-image-file [full-attribute-list]
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
dll[[HWVD]] = source-file destination-image-file [full-attribute-list]
Executable file whose entry point must be called
dlldatatop
dlldatatop = <address of data region>
Specify top of DLL data region
epocwrapper
epocwrapper
Specifies that an EPOC ROM wrapper is required
extension
extension[[HWVD]] = source-file destination-image-file [full-attribute-list]
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.
extensionrom
extensionrom = rom-file-name
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 
filecompress
filecompress[[HWVD]] = source-file destination-file [full-attribute-list]
Non-XIP Executable to be loaded into the ROM compressed
fileuncompress
data[[HWVD]] = source-file destination-file [full-attribute-list]
Non-XIP Executable to be loaded into the ROM uncompressed
kerneldataaddress
kerneldataaddress = hex-address
Kernel data/bss chunk base virtual address.
The recommended value is 0x80000000.
kernelheapmax
kernelheapmax = hex-size
Maximum size of the Kernel's heap. The Kernel heap grows in virtual address space until this value is reached: it can then grow no further.
The value is rounded up to a multiple of the virtual address space mapped by a single page directory entry - on ARM CPUs, this is 1MB.
Usually 1 page directory entry's worth of RAM is specified.
The default value is 0x100000; this is used if none is supplied.
kernelheapmin
kernelheapmin = hex-size
Minimum size of the Kernel heap, allocated immediately when the Kernel boots. Specify either a minimal value, or a working set size based on envisaged use.
The recommended value is 0x10000, and is the default value if none is explicitly supplied.
kernelromname
kernelromname = rom-file-name
ROM image on which extension ROM is based. This keyword is only valid for extension ROMs.
kerneltrace
kernelTrace = 32 bit hex-number
Initial value for the Kernel trace mask. The bit values are defined in k32std.h, and only apply to a debug Kernel
memmodel
memmodel = (moving | direct |multiple) <chunk size> <page size>
Specifies the memory model to be used at runtime
multikernel
multikernel
Specifies that the ROM image has multiple Kernel executables. These Kernels are specified with multiple primary keywords in the files-section.
nowrapper
nowrapper
Specifies that no ROM wrapper is required.
primary
primary[[HWVD]] = source-file destination-image-file [full-attribute-list]
A standard executable file that is loaded directly 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.
romalign
romalign = hex-alignment
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 to become so.
romlinearbase
romlinearbase = hex-address
Virtual address of the start of ROM, in hex.
The recommended value for ARM CPUs is 0x50000000.
romname
romname = rom-file-name
This is the name of the output file, and contains the ROM image that rombuild creates.
romnameeven
romnameeven = rom-file-name-even
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 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.
secondary
secondary = source-file destination-image-file [full-attribute-list]
A standard executable file that is loaded by the Kernel; this is the file server. All subsequent files can be loaded through the file server.
As with all standard executable files, this is loaded, relocated and stripped of its relocation information.
section
section = section-offset
ROMs can be sectioned into two parts allowing the upper part of the ROM to be switched for language variations and file patching. This is independent of the extension ROM mechanism.
This keyword appears at the point in the obey file where the ROM to be split. All files before this line appear in the first (constant) section, and files after appear in the second (patch/language) section.
singlekernel
singlekernel
Specifies that this ROM image has one Kernel executable within it. This is the default.
srecordbase
srecordbase = hex-address
Destination address for S-record download.
srecordfilename
srecordfilename = srec-file-name
rombuild can write an image in Motorola S-record format. This happens if a name for the output file is specified here. A filename of "*" can be specified, which means use the file name specified on the romname keyword and append .screc.
unicode
unicode
UNICODE ROM – this is the default
variant
variant[HWVD] = source-file destination-image-file [full-attribute-list]
Defines hardware variants. It should be applied to the variant DLL, i.e. the ecust.dll of each hardware variant to be supported, and must specify a suitable HWVD. Note that the HWVD must be enclosed within square brackets.
ROFSBUILD specific keywords
autosize
autosize=<block size>
The automatic sizing functionality will always reduce the size to a whole number of blocks where the size of the block has been specified in the autosize command. 
For example if the rofsize is set to 0x30000 and the actual image size is 0x1234 then the generated image size without autosize option will be 0x30000. If autosize=0x1000 is used then the generated image size will be 0x2000.
coreimage
coreimage=<core image file>
This coreimage keyword indicates to 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.
extensionrofs
extensionrofs
Start of definition of optional Extension ROFS
extensionrofsname
extensionrofs=<filename>
Specify the name of the 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.
rofsname
rofsname=<filename>
Specify the name of the core image.
rofsize
rofssize=<size in bytes>
Specify the maximum size of the core image, or the maximum size of the extension.

Building multi-boot ROMs
A multi-boot ROM exists when there is support for more than one hardware Variant in the ROM image. Such a ROM also has multiple root directories, one for each Variant supported. This automatically ensures that the file server only sees the files that are relevant to the hardware on which it is running.
There may, or may not, be multiple Kernels to support the multiple hardware variants. If there is more than one Kernel, then the keyword multikernel should be present in the rom-information-statement part of the obey file. The first and subsequent Kernels are specified in the file-statement part of the obey file with the primary keyword.
Hardware Variant Discriminator (HWVD)
rombuild uses a Hardware Variant Discriminator (HWVD) to decide which files in the file-statement part of the obey file are present in which directory structure.
This is an 8 digit (32 bit) hexadecimal number that may, optionally, appear after the file name. The number itself must be enclosed in square brackets. The number identifies the hardware variants to which the file is relevant.
The HWVD numbers have a structure which enables them to describe a tree. The top 8 bits are the "node" number, the next 8 bits are the "parent" node number, and the low 16 bits are the variant mask. These numbers together place the HWVD into a tree with the following structure:

The nodes above the dotted line are fixed:
1 is fully generic
2 is platform specific, i.e. the kp_* layer
3 is processor architecture, i.e. the kc_* layer.
The node numbers below the dotted line are specific to a given ROM, but live in two distinct layers:
4 and 7 represent a specific CPU core core, e.g. ARM7, SA-1.
5, 6 and 8 represent a specific ASSP
For HWVD numbers which refer to the ASSP nodes (5,6 & 8 in the diagram), the low 16 bits indicate which Variants are supported by the given file. There must be at least one file, the Variant DLL, which is marked as supporting only one Variant.
This tree is used to determine which files appear in the ROM directory structure for a given Variant, and also how the static DLL linkages are resolved. A file associated with a node in the tree can link to any DLL attached to the same node, or any DLL attached to one of the nodes in the path leading back to the root of the tree.
It is possible to have two or more files of the same name in the same directory provided that they have HWVDs which are mutually exclusive, so that the two files can never appear on the same machine.
For example:
0x01000000 - generic file, appears in directory tree for every variant
0x0504FFFF - file associated with node 5, supporting all variants
0x04030000 file associated with node 4
0x07030000 file associated with node 7
0x06070001 improper for the diagram shown - implies that node 7 is parent of node 6
0x06040001 file associated with node 6, supporting only the first variant.
In practice, the ROM-constrained nature of devices does not encourage extensive use of this facility, and it would be unusual to have more than one ASSP supported. 
Extension ROMs
An extension ROM is a ROM image which combines with a kernel ROM image to produce a larger overall ROM with a  modified ROM filesystem.
Each extension ROM section starts with a fresh copy of the ROM filesystem produced by the kernel ROM section of the OBEY file, and modifies it by adding files and possibly renaming or hiding the files in the kernel image. Once the section has been processed, the extension image is written to the filename specified in the extensionrom statement, including a directory structure which refers to files in both the extension and the kernel images: no changes are made to the kernel image, which is completely independent of any extension ROMs.
It is possible to extend a kernel ROM which used the section keyword to create a replaceable section, but the extension ROM will be very likely to contain the addresses of files in the second section, which are likely to change if a different second section is used. This won’t be a problem if the extension ROM is changed at the same time as the second section.
ROM image format
In this section we first explain the format of a Kernel ROM image, and then go on to show how this is altered when the ROM is sectioned.
Kernel ROM image format
The standard output from rombuild is an image on disk which consists of six sections:
TRomLoaderHeader - also known as the wrapper, this is discarded in the final blown ROM image
TRomHeader - the ROM header which remains in the ROM image
bootrom.bin - the Bootstrap binary image
TRomRootDirectoryList - a list of all the root directories, one for each Variant supported by this ROM image. In the Kernel ROM image, there is only one root directory and one variant.
the directory structure - the overhead supporting a full directory structure on the ROM.
the file images - the executables and data which go to make up the ROM image.
TRomLoaderHeader
This is a wrapper, which is used by the 486 boot loader and the Series 5 ROM programmer, and then discarded. It is possible to build a ROM without this header, by specifying the -no-header parameter to rombuild.
Offset (hex)	
Description of field	

00	
ROM image name (ascii text)	

10	
Version string (ascii text)	

14	
Build string (ascii text)	

18	
Size of ROM image	

1C	
Size of wrapper	

20	
Filler to size of wrapper (specified above, usually 0x100 bytes)	

TRomHeader
This data is created by ROMBUILD for later use by the Bootstrap program and the Kernel.
Offset (hex)	
Description of field	

00	
0x80 bytes reserved for a small amount of boot code if needed	

80	
ROM image build datetime.	

8C	
ROM virtual base address.	

90	
ROM image size in bytes (including the second section for sectioned ROMs).	

94	
Virtual address of the TRomRootDirList structure.	

98	
Kernel data virtual address (when in RAM).	

9C	
Kernel limit virtual address (when in RAM).	

A0	
Virtual address of (first) primary's TRomImageHeader.	

A4	
Virtual address of secondary's TRomImageHeader.	

A8	
Computed constant which causes the 32-bit checksum of the image to equal the value specified by the romchecksum keyword.	

AC	
Hardware - a unique number identifying the hardware for which this ROM image has been built.
NB This is only used for testing purposes.	

B0	
Languages - a bitmask identifying which of the languages are supported by the ROM image, as specified by the languages keyword. 
NB This is only used for testing purposes.	

B8	
Not Used	

BC	
Not Used	

C0	
Not Used	

C4	
ROM section header, a pointer to a TRomSectionHeader, if the ROM is sectioned.	

C8	
Total supervisor data size, the amount of memory mapped for the Kernel data chunk.	

CC	
Address of variant file TRomEntry.	

D0	
Address of TRomEntry for the first extension file, if it exists. If there is more than one extension, then the next extension field in the TRomImageHeader of the extension points to the TRomEntry for the next one.	

D4	
Address of the first area to be relocated into RAM, as defined using the area keyword.	

D8	
Initial value for the Kernel trace mask.	

DC	
User data address.	

E0	
Total user data size	

E4	
Value interpreted by the Bootstrap and Kernel as the debug port to use.	

E8	
Version	

EC	
Compression type used for image	

F0	
Size after compression	

F4	
Size before compression	

F8-FF	
Filler 	

The Bootstrap binary
The Bootstrap binary image is copied directly into the start of the ROM. It must, therefore, contain a "hole" at offsets 0x80 to 0xFF for the data members of the TRomHeader object. The first 4 bytes of the binary image typically contain a branch instruction which jumps to the code at offset 0x100. The Bootstrap is responsible for detecting the extension ROM, if present, and for passing the appropriate TRomRootDirectoryList address to the Kernel. For the MISA ASSP, the bootstrap binary is \Epoc32\Release\MISA\UREL\bootromba.bin
TRomRootDirectoryList
This structure allows you to find the root directories for each hardware Variant supported by the ROM. Usually, there is only one variant and one root directory, so this table normally has just three entries.
Sometimes, however, a ROM has multiple root directories and directory trees, one for each hardware Variant supported by the ROM. This automatically ensures that the file server only sees the files that are relevant to the hardware on which it is running. In this case, there are multiple entries in the table describing each root directory.
Offset (hex)	
Description of field	

00	
Number of root directories.	

04	
Hardware Variant for first root directory.	

08	
Address of first root directory.	

0C	
Hardware Variant for second root directory.	

10	
Address of second root directory.	

…	
…	

nn	
Hardware Variant for last root directory.	

nn+4	
Address of last root directory.	

The directory structure
Every directory is described by a TRomDir, including the root directories. Each directory is described twice; first by a sequence of variable length entries in the order that the directory members were mentioned in the obey file, and then as a pair of sorted tables suitable for binary search.
TRomDir
Offset (hex)	
Description of field	

00	
Number of bytes (N) occupied by the subsequent TRomEntry structures.	

04	
TRomEntry structure for file or directory 0.	

...	
TRomEntry structure for file or directory 1.	

...	
Etc. for each entry in the directory.	

N+04 	
Number of directory entries (D).	

N+06 	
Number of files (F).	

N+08 	
Table of 16-bit scaled offsets to the directory entries.	

(N+08+(2*D)) 	
Table of 16-bit scaled offsets to the file entries.	

The sorted tables contain unsigned 16-bit scaled offsets, which point to the start of the corresponding TRomEntry.
If the offset value is X then the corresponding TRomEntry is at address (4*X + (char*)(address of first entry)). For example, the first entry is at offset zero. The entries are sorted in order of the UTF-8 representation of the filenames in a case insensitive way (cf the 'C' function stricmp()). In effect, this folds upper and lowercase ASCII characters but leaves all other Unicode characters unchanged.
Each of the files or subdirectories within the TRomDir is described with a TRomEntry structure. The latter are always 4 byte aligned, and may include padding, if the length of the name doesn't cause the structure to be a multiple of 4 bytes in length.
TRomEntry
Offset (hex)	
Description of field	

00	
Size of file.	

04	
Virtual address of file, or of a TRomDir structure if the entry is another directory.	

08	
Attributes byte.	

09	
Length of name.	

0A	
Name.	

If the TRomEntry describes a file, then the field at offset 4 points at that file. If it describes a sub-directory, then it points to another TRomDir structure.
The file images
The structure of the file images is based on the native image file format, but this can be compressed in the ROM image, as the relocation information and the .idata section can be discarded once the file is fixed up.
A further optimisation is that the Import Address Table (IAT) is removed and each reference to an IAT entry is converted into a reference to the associated Export Directory entry in the corresponding DLL.
ROM files have the following sections:
TromImageHeader - the ROM file header
.text - code
.rdata - constant (read-only) data
.edata - the export directory
.data - initialised data that is copied to RAM when the executable runs
TDllRefTable - DLL reference table, a list of the libraries used by this executable.
TRomImageHeader 
Offset (hex)	
Description of field	

00	
UID 1.	

04	
UID 2.	

08	
UID 3.	

0C	
Checksum of UIDs.	

10	
Entrypoint of this executable (offset within this file).	

14	
Target code address for this executable.	

18	
Target data address for this executable.	

1C	
Code size (includes constant data).	

20	
Text size (code size - size of constant data).	

24	
Data size	

28	
BSS (Zero-filled data) size.	

2C	
Heap minimum size.	

30	
Heap maximum size.	

34	
Stack size.	

38	
Address of DLL reference table (a list of the DLLs which this executable needs to run). This is a TDllRefTable structure.	

3C	
Number of functions exported by this executable.	

40	
Export directory address. The export directory is a simple list of functions, which can be indexed by ordinal.	

44	
Security information.	

50	
Tools version.	

54	
Flags.	

58	
Priority of this process.	

5C	
Data and BSS linear base address, where this process expects its data chunk to be when it runs.	

60	
Address of the TRomEntry for the next extension file. This field is only used if there is more than one extension. The first extension is found using the TRomHeader.	

64	
A number denoting the hardware Variant, used to determine if this executable can run on any particular system.	

68	
Total data size including space reserved for DLLs	

6C	
Module version	

The export directory
The .edata section is a table supplying the fixed up address of each exported function or data item. The table is not null terminated as the number of entries in the table is available from offset 0x3c in the executable's TRomImageHeader.
Offset	
Description	

00	
Address of first function exported from this executable.	

04	
Address of second function exported from this executable.	

…	

Nn	
Address of last function exported from this executable.	

TDllRefTable
The TDllRefTable of an executable lists the DLLs that this executable needs in order to run. For each such DLL referenced, it has a pointer to a TRomImageHeader that describes the referenced DLL. This latter allows programs such as the DLL loader to search a dependency chain, and load all the required DLLs.
For example, if DLL A uses DLL B which uses DLL C, then recursing through the TDllRefTables of those DLLs, allows the loader to find DLL C.
Offset (hex)	
Description of field	

00	
Flags.	

02	
Number of entries in table.	

04	
Pointer to TRomImageHeader for first DLL referenced.	

…	
…	

Nn+4	
Pointer to TRomImageHeader for last DLL referenced.	

Format of extension ROMs
An extension ROM is an optional ROM which extends a kernel ROM and presents a filesystem which describes the combined ROM image. The underlying kernel ROM is self-sufficient and has no references to any extension ROM, and different extension ROMs can be built which extend the same kernel ROM.
The format of an extension ROM is similar to that of a kernel ROM: 
Section	Description	
TExtensionRomHeader	The ROM header which remains in the ROM image, and which contains “fingerprint” information to identify the associated kernel ROM.	
TRomRootDirectoryList	A list of all the root directories, one for each variant supported by the combined kernel+extenstion ROM image. 	
The directory structure	The full directory structure for the combined image.	
Files	The additional executables and data in the extension ROM.	
TExtensionRomHeader
This data is created by rombuild, for later use by the bootstrap program and the kernel.
Offset (hex)	Description of field	
00	Extension ROM image major version	
01	Extension ROM image minor version	
02	Extension ROM image build number	
04	Extension ROM linear base address	
08	Extension ROM image size in bytes	
0C	Linear address of TRomRootDirList structure for the combined kernel+extension ROM image	
10	Extension ROM image build datetime	
18	Checksum	
1C	Copy of Kernel ROM image major version	
1D	Copy of Kernel ROM image minor version	
1E	Copy of Kernel ROM image build number	
20	Copy of Kernel ROM image build datetime	
28	Copy of Kernel.ROM image checksum constant.	
2C	Compression type	
30	Size when compressed	
34	Size when not compressed	
38 - 7F	Filler	
Format of sectioned ROMs
Kernel Roms can be sectioned into two parts allowing the upper part of the ROM to be switched for language variations and file patching.
If the line section 0x200000 keyword appears in the obey file, then the ROM will be in 2 sections – the lower section will be identical to that in the original ROM, and the higher (second) section will contain all the files listed in the obey file after the section keyword. 
The format of sectioned ROMs is given in overview below.
Section	Description	
TRomLoaderHeader	Also known as the wrapper, this is discarded in the final ROM image which is blown.	
TRomHeader	The ROM header which remains on the ROM.	
BOOTROM.BIN	The bootstrap binary image (which logically encloses the TRomHeader)	
Files 1	The executables and data which go to make up the ROM image – those which appear before the section keyword.	
TRomSectionHeader	Appearing at the section address specified in the obey file	
EDATA and DllRefTables 	For files in the low section (Files 1)	
TRomRootDirectoryList	A list of all the root directories for each variant supported by this ROM. Usually, there is only one root directory and one variant.	
The directory structure	The overhead supporting a full directory structure on the ROM.	
Files 2	The rest of executables and data which go to make up the ROM image.	
TRomSectionHeader
Offset (hex)	Description	
00	ROM major version	
01	ROM minor version	
02	ROM build number	
04	Computed constant that causes the 32-bit checksum of the upper section to equal zero. All upper sections will checksum to zero, so the overall ROM checksum in the TRomHeader is unaffected by changing the second section.	
08	ROM datetime	
10	Language	
EDATA and DllRefTables
References from an executable to a function exported by a DLL involve reading the function address from the Export Directory of the DLL. In order to allow low section DLLs to be overridden, the Export Directory for each low section DLL must be stored in the second section.
EDATA1	Export Directory (if any) for first file in ROM	
DllRefTable1	DllRefTable for first file in ROM	
EDATA2	Export Directory (if any) for second file in ROM	
DllRefTable1	DllRefTable for second file in ROM	
..	…	
EDATAn	Export Directory (if any) for last file in first section of ROM	
DllRefTablen	DllRefTable for last file in first section of ROM