Pyromaniac PRM: Modules (supplement for Pyromaniac)

Introduction and Overview

This chapter documents the changes to the module format for RISC OS Pyromaniac.

Technical Details

Module header format

The module indicates to the system if and where it wishes to be called by a module header. This contains offsets from the start of the module to code and information within the body of the module:

Offset	Contains	Function
00	Offset to code	Module_Start
04	Offset to code	Module_Initialise
08	Offset to code	Module_Finalise
0C	Offset to code	Module_ServiceHandler
10	Offset to string	Module_TitleString
14	Offset to string	Module_HelpString
18	Offset to table	Module_CommandTable
1C	Number	SWI chunk base number (optional)
20	Offset to code	SWI handler code (optional)
24	Offset to table	SWI decoding table (optional)
28	Offset to code	SWI decoding code (optional)
2C	Offset to string	Message file pathname (optional)
30	Offset to module feature table	Module_FeatureTable

The following fields have been updated:

Module_Initialise

The flags used by the Module_Initialise entry point have been extended.

Bit(s)	Meaning
31	Module is compressed and must be decompressed before it can be initialised. This flag is not supported by RISC OS Pyromaniac and modules may not be compressed.
30	Module flags contains alternate architecture flags. This flag is present to force older versions of the operating system to reject the module header as invalid. This prevents modules which contain architecture incompatible implementations from loading on older systems.

Bit(s)

Meaning

Module is compressed and must be decompressed before it can be initialised.

This flag is not supported by RISC OS Pyromaniac and modules may not be compressed.

Module flags contains alternate architecture flags.

This flag is present to force older versions of the operating system to reject the module header as invalid. This prevents modules which contain architecture incompatible implementations from loading on older systems.

Module_SWIDecodingCode

The SWI decoding code was deprecated in Select 3 due to changes in the way that decoding was performed, and as its behaviour is rarely used. Pyromaniac does not support this entry point and it will never be called.

Module_FeatureTable

The feature flags have been extended to add an architecture flag. See the section Module_FeatureTable.

Entry Points

Module_FeatureTable30

Extension feature table

None

Interrupts are undefined

Fast interrupts are undefined

Processor is in undefined mode

Not defined

The feature table is used to provide additional information about the features of a module, beyond the originally defined header data. The initial word of this feature table consists of flags indicating the features of the module. The flags word is not faulted when unknown bits are present.

The feature table must be present in modules which support 32 bit operation, and so all preceding offsets must be included and must be 0 if they are unused.

The flags word consists of:

Bit(s)

Meaning

Module contains 32bit safe code.

This flag is required by RISC OS Pyromaniac when executing ARM code. It is required for 32 bit-only versions of RISC OS, and will be ignored on 26 bit-only versions. Non-ARM 32 bit modules should not set this flag.

ROM module should be initialised early.

This flag is used to sort modules which are required for early initialisation as part of the ROM. This bit avoids the need for specially placed modules in the ROM where they must happen early on. In particular this bit is used in RISC OS Select to initialise the Podule manager (and other extension modules). For non-ROM modules this has no meaning and will be ignored.

It is supported and used by RISC OS Select 3 and later, and by RISC OS Pyromaniac.

Reserved, must be zero

4-7

Module implementation architecture

This bit field is used to indicate the architecture the module has been implemented in. The use of the architecture flag allows modules which are for incompatible architectures to be identified. If the architecture is not ARM 32 (including ARM 26 bit), bit 30 of the Module_Initialise entry point should be set. This will prevent the module being recognised by earlier versions of RISC OS. When the architecture is not ARM 32, bit 0 is undefined and should be set to 0.

Currently defined architectures:

Value	Meaning
0	ARM 32 bit (A32)
1	ARM 64 bit (A64)
2	x86 64 bit (x86-64)
3-14	Reserved
15	Python (RISC OS Pyromaniac)

This architecture flags are recognised by RISC OS Pyromaniac after 0.22. Only A32 and Pyromaniac architectures are supported by RISC OS Pyromaniac.

No other RISC OS versions currently recognise this flag.

8-31

Reserved, must be zero

If a module is deemed to be unsuitable for execution, either because it contains 26 bit code, or is for a different architecture, it will not be initialised by the system. Such modules will enumerate the modules through OS_Module 19 and 20 with a status of -2, indicating that they are unsuitable.

Future versions of the feature table may include a subsequent extension block. The presence of such a block indicated in the flags word.