Concepts
This section provides the concepts often used in building ROM images.
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
E32ImageHeader
–f32image.h
. Instead it uses a smaller
TRomImageHeader
–e32rom.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:
The node numbers below the dotted line are specific to a given ROM, but
live in two distinct layers:
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
Level | Description |
---|
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.
|