Concepts

This section provides the concepts often used in building ROM images.

Typical ROM image

Typical ROM image


Typical ROM image

The figure above shows that a typical ROM image contains the information as follows:

  • The header of a ROM image. The header contains a set of vectors. The first vector points to the bootstrap binary. The header also contains pointers to the primary binary, secondary binary and variant binary in the ROM directory listing.

    Note: The primary does not have to be the first binary in the ROM image as the bootstrap can find it by using the iPrimaryFile pointer from the ROM header and the directory list. For more information about the header, see the TRomHeader class in \epoc32\include\e32rom.h.

  • The bootbinary in the ROM image which is often called Symbian bootstrap. This is where it jumps on a reset.

  • A directory which lists all the file and directory entries. Each entry includes the file or directory name, size and the position in the ROM after it is mapped to the vitrual address space.

  • The binaries. ROMBUILD removes the E32ImageHeaderf32image.h. Instead it uses a smaller TRomImageHeadere32rom.h. ROMBUILD knows the position where the binary will be located in the virtual address space, and it removes superfluous data, such as time or relocation data.

OBY and IBY files

The input to BUILDROM is one or more text files containing the description of the ROM image. The files are called obey files and have the extension .oby. An obey file can include any number of sub-files. Obey-include files have the extension .iby.

Symbian components and applications are supplied in various binary forms with an associated, component-specific IBY file for inclusion in a device-specific OBY file. The IBY file ensures that the files required by each component are included at the correct location in the ROM or ROFS image. The following is a sample IBY file for a component:

file=ABI_DIR\BUILD_DIR\charconv.dll                 sys\bin\charconv.dll
file=ABI_DIR\BUILD_DIR\convnames.dll                sys\bin\convnames.dll
data=ZRESOURCE\charconv\basic.snm                   resource\charconv\basic.snm
data=MULTI_LINGUIFY(RSC ZRESOURCE\charconv\builtin resource\charconv\builtin)

The OBY files contain information about the configuration of the ROM image such as its size, its location, the location of key XIP files, values for patchable constants, default paging and compression information, the memory model to be used, language support information and debug support information. The following is a sample OBY file:

romname=h4hrp_001.techview.img
romsize=0x20000000
kerneltrace 0x80000000
Memmodel multiple 0x100000
multikernel
version=0.01
bootbinary=\epoc32\release\ARMV5\_h4hrp_bootrom.bin
romlinearbase=0x80000000
kerneldataaddress=0xC8000000
kernelheapmin=0x01000
kernelheapmax=0x00FFF000
dataaddress=0x400000
defaultstackreserve=0x200000
files=
primary[0x09080004]=\e\r\a\u\..._h4hrp_ekern.exe Sys\Bin\ekern.exe
variant[0x09080004]=\e\r\a\u\_h4hrp_ecust_tv.dll Sys\Bin\ecust.dll
secondary=\epoc32\release\ARMV5\urel\efile.exe Sys\Bin\efile.exe
device[0x09080004]=\e\r\a\u\_h4hrp_ecommdma.ldd Sys\Bin\ecomm.ldd
extension[0x09080004]=\e\r\a\u\_h4hrp_lcd.dll Sys\Bin\lcd.dll
file=\epoc32\release\ARMV5\urel\efsrv.dll Sys\Bin\EFSrv.dll
data=\epoc32\rom\h4hrp\quicknand.bat quicknand.bat

Both OBY and IBY files can share the OBY file syntax, except that the OBY file can include IBY files. BUILDROM merges these input files into one OBY file which is used by ROMBUILD or ROFSBUILD to generate the ROM image or the ROFS image.

OBY/IBY files can contain built-in macros, for example ONENAND, or user defined macros. When the OBY/IBY files are passed through the C preprocessor, these macros are processed based on the BUILDROM command-line parameters.

Note: Command line parameters for BUILDROM can override some of the instructions in the OBY files.

Symbian supplies obey files for each of its hardware reference platforms in epoc32/rom.

Hardware Variant Discriminator (HWVD)

A multi-boot ROM exists when there is support for more than one hardware variant in the ROM image. Hardware Variant Discriminator (HWVD) is then used to identify files for different hardware variants in the OBY or IBY file. ROMBUILD uses HWVD to decide which files in the FileStatement part of the obey file are present in which directory structure.

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, the keyword multikernel must be present in the RomStatement part of the obey file. The first and subsequent Kernels are specified in the FileStatement part of the obey file with the primary keyword.

HWVD algorithm

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

  • 3 is processor architecture.

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.

  • 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.

Symbol files

After a ROM or ROFS image is built, a log file is generated. The tool MAKSYM or MAKSYMROFS reads the log file to make a text .symbol file. The symbol file is useful for debugging purpose.

MAKSYM reads the log file which is created by ROMBUILD when building a ROM image. MAKSYMROFS reads the log file which is created by ROFSBUILD when building a ROFS image.

The code snippet below shows part of the symbol file generated with the MAKSYM tool located at \epoc32\tools\maksym. The symbol file lists the file name, virtual address, start address, length and the symbol.

From    \Epoc32\Release\ARMV5\UDEB\_H2_EKERN.EXE

F802e5c0    00ac    K::Init3()                 _h2_ekern.in(.text)
f802e66c    0030    SupervisorThread(void*)    _h2_ekern.in(.text)
f802e69c    0018    DebuggerInit()             _h2_ekern.in(.text)
f802e6b4    0ac8    K::InitialiseMicrokernel()  _h2_ekern.in(.text)
f802f17c    014c    KernelMain()                _h2_ekern.in(.text)
f802f2c8    000c    Kern::ColdStart()          _h2_ekern.in(.text)
 ...
From    \Epoc32\Release\ARMV5\UDEB\EUSER.DLL

f80df200    0008   Exec::WaitForAnyRequest()     euser.in(.emb_text)
f80df208    0008   Exec::Heap()                  euser.in(.emb_text)
f80df210    0008   Exec::HeapSwitch(RAllocator*) euser.in(.emb_text)
f80df218    0008   Exec::PushTrapFrame(TTrap*)   euser.in(.emb_text)



        

XIP

XIP stands for eXecute In Place. It means code and data in ROM are always available and do not require to load into memory. Prerequisites for XIP are as follows:

  • Code or data must be relocated during ROM building to map the virutal address space. It then can run.

    The code or data before the relocation is often referred to as relocatable code or data. The relocated code or data is often referred to as eXecute In Place(XIP) code or data.

  • The hardware must support XIP.

    NOR flash allows the code to be executed in place in the same way as traditional ROM, but NAND flash does not allow XIP. This is a major difference between NOR flash and NAND flash.

The table below compares the ROM image with the ROFS image. For more information about ROM, refer to Symbian Developer Library > Symbian OS Guide > ROM Guide.

Image

File System

Code

Hardware

ROM image

ROMFS

XIP code (relocated)

NOR flash

Note: For NAND-only device, XIP code can be saved on NAND, but must be loaded to RAM to execute.

ROFS image

Note: In Symbian platform, the underlying media for data is physically writeable(RAM or flash memory), but the file system is read-only. Data behaves like it is stored in the read-only memory (ROM). In this sense, both a ROFS image or a ROM image can be called as a ROM image.

ROFS

Non-XIP code (relocatable, but not relocated yet)

NAND flash

Configuration Levels

You can define the code and data paging settings using the keywords in the four configuration levels explained in the following table:

Configuration LevelDescription

MMP file

Includes paged, pagedcode, pageddata, unpaged, unpagedcode, and unpageddata keywords. You can use these keywords in an MMP file to define the paging settings for each executable in the process. For details, see Symbian Developer Library » Symbian OS Tools And Utilities » Build tools reference » MMP file syntax.

Per-file settings in OBY file

Includes paged, pagedcode, pageddata, unpaged, unpagedcode, and unpageddata keywords. You can use these keywords in an OBY file to define the code and data paging settings for each executable in the process.

The description for the per-file settings in OBY file configuration keywords is same as MMP file configuration keywords.

Note: The settings defined at this configuration level override the settings defined at the MMP file configuration level.

Per-OBY file

Includes pagingoverride, codepagingoverride, and datapagingoverride keywords. You can use these keywords to define the code and data paging settings common for all the files in an OBY file.

The settings defined at this configuration level override the settings defined at the MMP file and per-file settings in OBY file configuration levels.

OBY file global

Includes pagingpolicy, datapagingpolicy, and codepagingpolicy keywords. You can use these keywords to set the code and data paging settings for the whole system.

The settings defined at this configuration level override the settings defined at the MMP file, per-file settings in OBY file, and per-OBY file configuration levels.