ROM image format (changes)

Showing changes from revision #7 to #8: Added | Removed | Changed

This page serves as a summary of the internal format of RISC OS 5 ROM images. This format is similar to that used in other versions of RISC OS developed by Acorn and RISCOS Ltd.

Overview

There are four main sections to a RISC OS 5 ROM image. In order from the start of the image, these are:

1. The HAL. This contains the initial entry point to the image and basic low-level hardware drivers. The HALSize parameter in the Env file specifies how much space to reserve in the image for the HAL. If the HAL is smaller than the allocated size then padding bytes (0xff) will be inserted after it in order to expand it to the correct size.
2. The ROM module chain. This contains all the ROM modules, in a linked list structure.
3. After the ROM modules will be a number of padding bytes (0xff), which are used to pad the image out to the predetermined size listed in the Env file (the ImageSize parameter). This area may also be used to store large blocks of data, such as the ROM debug symbols.
4. Finally there is the ROM footer. This is a small data structure inserted at the end of the image. It is used to store metadata about the image and its contents.

The amount of padding inserted before the footer is adjusted so that the total size of the image is exactly the ImageSize parameter specified in the Env file.

Note that for historical reasons, by default the ROM linker tool will overwrite locations 0×60-0×63 with a word containing the size of the ROM image. However this will overwrite part of the HAL, and one of the design goals of the HAL was to have it free from any formatting constraints. To combat this a ‘noimagesize’ option was added to romlinker 0.04 to suppress this behaviour. In order to use this option with Builder/srcbuild, make sure that romlinker is used as the %Joiner and %JoinerFormat options in the Components file, and then add a new %noimagesize option (see the top of the OMAP3 components file for an example)

ROM footer

The ROM footer has the following format. The entries below are listed in increasing address order, i.e. the end of the 64 bit CRC will be the end of the image file.

Checksums

Two checksums are stored, a 32bit 32 bit negative checksum and a 64bit 64 bitCRC.

TODO – Describe how they’re stored and what data they cover.

ROM signature

Historically this field was used to differentiate between different ROMs intended for different machines/markets. E.g. NCOS builds used to have a signature of 0×534F434E (‘NCOS’ in host byte order). Current builds just use a signature of 0xffffffff.

POST word

For IOMD and before, this word was used as part of the power-on self test.

TODO – How was it used?

Extended ROM footer

This is a new structure supported by romlinker 0.04 and above. It stores a list of variable-length items identified by tags. In increasing address order, each entry in the footer begins with a 1-byte tag ID field, a 1-byte length field, and then the variable-length data payload. The length field excludes the length of the two header bytes.

To identify the length and validity of the extended ROM footer, the item list is terminated by a footer word. This word contains the length of the extended ROM footer in the low two bytes (not including the length of this word) and a 16-bit CRC in the top two bytes (not including the contents of this word).

If an extended ROM footer is present in the image then the footer word will be located at offset -24 from the end of the image, i.e. directly before the POST word. Individual items within the footer will be byte-aligned.

Starting with RISC OS 5.23, OS_ReadSysInfo 15 can be used to enumerate the footer entries at runtime.

Defined tag IDs

The following tag IDs are currently in use:

Compressed ROMs

The current ROM compression scheme involves compressing everything in the ROM image apart from the HAL and kernel. The ‘rompress’ tool will append a new ROM footer with valid checksums (to help HALs that perform a checksum of the ROM image, e.g. the Tungsten HAL), along with an extended ROM footer containing tag ID 1. The presence of this extended footer helps the softload tool to quickly and easily identify if a compressed ROM matches an uncompressed ROM.

See also

• Developer documentation
• Developer's guide to RISC OS builds
• Compressed ROMs