Appendix43Appendix I: RISC OS execution formats

26/32-bit AIF header

ARM Image Format (AIF) consists of a fixed, 128-byte (32-word) header followed by the image's code and initialised static data. Executable AIF is the common case: the header is part of the image, and is itself entered at its first word. Non-executable AIF instead describes an image to be prepared and entered by a separate loader; the two are distinguished by the fourth header word, which is a branch instruction for executable AIF and a plain entry-point offset for non-executable AIF.

This table can be checked against a real file. Building a minimal command skeleton and dumping its header shows every field in place:

riscos-project create --name MyCommand --type command --skeleton

riscos-amu BUILD32=1

riscos-dump aif32/MyCommand,ff8

Offset   :   0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F  : Text

    8000 :  00 00 A0 E1 00 00 A0 E1 0C 00 00 EB 85 02 00 EB  : ................

    8010 :  11 00 00 EF 70 13 00 00 14 00 00 00 00 00 00 00  : ....p...........

    8020 :  64 0E 00 00 00 00 00 00 00 80 00 00 00 00 00 00  : d...............

    8030 :  20 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  :  ...............

    8040 :  00 00 A0 E1 0F C0 4E E0 0C C0 8F E0 0F 00 9C E9  : ......N.........

riscos-dump labels each row with the image's load address, &8000, so the table's file offsets map directly onto these rows by subtracting that base. Reading off a few fields confirms the table: offset +0 and +4 are both 00 00 A0 E1 (MOV r0, r0, the canonical ARM NOP encoding), so neither decompression nor self-relocation is in use; +10 is 11 00 00 EF (SWI &11), the linker's default exit instruction; +14 is 70 13 00 00, a little-endian read-only size of &1370 bytes; +20 is 64 0E 00 00, a zero-initialised size of &0E64 bytes; +28 is 00 80 00 00, an image base of &8000, matching the load address; and +30 is 20 00 00 00, an address mode whose least significant byte, &20 (32 decimal), confirms a 32-bit image.

If the image is self-relocating, the linker appends self-move and self-relocation code immediately after the image, followed by a relocation list of word offsets terminated by -1. These follow the image body rather than forming part of the fixed header.

64-bit AIF extension

The 64-bit AIF format reuses the same 32-word, 128-byte header described above, with the same field meanings at the same offsets, but with content fixed so that a 32-bit RISC OS loader sees a normal, harmless AIF file:

• Words at +0, +4, and +8 are all NOP: the image is never compressed, self-relocating, or zero-initialised in a way a 32-bit loader needs to act on.
• The entry branch at +0C goes to +40, the header's debug-initialisation slot, which is repurposed to begin an ARM32 error-reporting stub rather than a real debug hook.
• The exit instruction at +10 is SWI OS_Exit, reached only if the error report returns.
• The address mode word at +30 is &40, a value with no defined 26-bit or 32-bit meaning. This is what a 64-bit loader recognises to identify the image as AArch64, in place of the 26 or 32 values used by AArch32 absolutes.
• The zero-initialisation code area at +44-+7B is repurposed to hold the ARM32 error-report sequence's error block and message text, rather than genuine zero-initialisation code.

A 32-bit RISC OS loader therefore sees a normal AIF file whose entry point reports the "AArch64 binaries cannot be run on 32-bit RISC OS" error and exits. A 64-bit loader recognises the &40 address mode and instead transfers control to the AArch64 code beginning at +&100, beyond the end of the standard header.

26/32-bit module header

A relocatable module begins with a header of offsets from the start of the module to code and data within its body. All offsets up to and including the help-and-command-table offset are required; later fields may be zero if unused, except where noted:

All code offsets must be word-aligned and within the module's own code area; all table and string offsets must similarly lie within the module. RISC OS rejects a module whose header fails these checks.

Module feature table and 32-bit safety

The feature table is a separate structure, addressed by the header's Module_FeatureTable offset, whose first word is a flags word describing the module's safety and architecture. The flags word is not faulted when unknown bits are set, and the feature table must be present (with this word at least) for any module that supports 32-bit operation:

A module that is deemed unsuitable for execution, either because it contains 26-bit code on a 32-bit-only system, or because its architecture is incompatible, is not initialised. Such modules are enumerated by OS_Module 19 and 20 (see RISC OS PRM: OS_Module 19, Enumerate ROM modules, which documents the original status values -1 (unplugged), 0 (dormant), 1 (active), and 2 (running)) with a status of -2. This value is a later addition, described in the RISC OS 6 PRM: OS_Module changes page as "a diagnostic aid for locating non-32bit modules within podules", indicating that they are unsuitable.

Separately, bit 30 of the Module_Initialise offset (header offset +4) can be set to indicate that the module's architecture is given by the feature table rather than being plain AArch32 code. This is a deliberately invalid offset value, which forces older versions of RISC OS that do not understand the feature table's architecture field to reject the module header outright, rather than attempting to run incompatible code.

Revised service-call-handler table (RISC OS 4 and later)

From RISC OS 4, the kernel supports a revised form of the Module_ServiceHandler entry point that lets it distribute service calls more efficiently, while remaining backward compatible with older kernels that only understand the original entry point. The revision is specified in RISC OS 6 PRM: OS_Module changes.

The meaning of the Module_ServiceHandler offset itself is unchanged. The revision instead gives meaning to the word immediately before the handler code, and optionally to a separate table that word points to:

Here svc is the address of the handler code, found from Module_ServiceHandler as usual. A kernel that does not recognise this revision simply executes the magic instruction (a no-op) and falls through to the handler code, so the revision is harmless on older systems. A module may set the anchor word to 0 to omit the service table, but should provide one wherever possible.

When provided, the service table lists the specific service call numbers the module is interested in, so the kernel can skip calling modules that have not registered interest in a given service:

The service call numbers in the table must be listed in strictly ascending order; RISC OS rejects a module whose table is not sorted. The handler code reached via the table entry may skip the logic that rejects uninteresting service call numbers, since the kernel will not call it for those; the original handler code reached directly via Module_ServiceHandler must still include that rejection logic, for kernels that do not use the table.

64-bit module extension

A 64-bit (AArch64) module sets the architecture field above to 1 and sets bit 30 of its Module_Initialise offset, as described. The gerph/riscos64-clib specification documents the following additional, 64-bit-specific behaviour:

• Feature flags bit 2 (ModFlags_ZeroInitPresent) indicates that a zero-initialisation size word is present immediately following the feature flags word; when set, the module loader extends the module's allocated memory by that many bytes and zero-fills the extension before initialisation. Confirmed directly against Pyromaniac's module loader (riscos/modules/__init__.py, reading the size word at flags_offset + 4) and the flag's definition (riscos/constants/modhand.py), where it is commented as Pyromaniac's 64-bit zero-init mechanism. The currently published Pyromaniac modules supplement documents feature-table bits 2 and 3 as reserved and required to be zero; that description predates this mechanism and is being corrected separately.
• The module is always allocated on a page boundary plus 4 bytes, so its base address always ends in 004 in hexadecimal. This allows code within the module to address its own workspace using ADRP.
• The module is never multiply instantiated.

All 64-bit module entry points follow the CMHG entry-point register assignments, rather than the original AArch32 module register assignments, with the exception of the private word pointer, which remains in r12 (as x12):

Any entry point that can return an error pointer must return it in r0, or 0 for success; the V flag need not be set. This follows the CMHG entry-point convention rather than the original AArch32 module convention. All interfaces are assumed to use the frame pointer for a call chain, and must not zero it on entry.

26/32-bit utility header

Transient utilities were not originally required to carry any header. Utilities intended to run on 32-bit systems must include the header below, which begins with a branch instruction and a pair of magic values chosen to make it unlikely that a non-conformant file is mistaken for a header:

If supplied, both size values must be word aligned. Because transient utilities are relocatable by design, a suitable header can be added by automated tools after the fact; such tools should assume the entire utility is read/write, since the original PRM does not require the TransientUtility module to enforce the read-only and read/write region sizes it is given.

64-bit utility extension

The 64-bit utility format keeps the same entry instruction and magic values, but replaces the 26-or-32 literal with a bitness-and-flags word, and inserts an additional field giving the offset of the AArch64 entry point. The ARM32 code that follows is correspondingly an error-report stub rather than the start of the utility's own ARM32 code:

A 64-bit loader transfers control to the AArch64 code at the offset given at +&18. A 32-bit loader instead runs the ARM32 code, which reports the "AArch64 binaries cannot be run on 32-bit RISC OS" error and returns.

This specification may be extended in future to require that 64-bit utilities, like modules, be loaded at a page boundary plus 4 bytes. Loaders and tools should not currently rely on that alignment for utilities.