Pyromaniac

Pyromaniac PRM: Modules (supplement for Pyromaniac)

Pyromaniac PRM: Modules (supplement for Pyromaniac)

RISC OS PyromaniacModules (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:

OffsetContainsFunction
00Offset to codeModule_Start
04Offset to codeModule_Initialise
08Offset to codeModule_Finalise
0COffset to codeModule_ServiceHandler
10Offset to stringModule_TitleString
14Offset to stringModule_HelpString
18Offset to tableModule_CommandTable
1CNumberSWI chunk base number (optional)
20Offset to codeSWI handler code (optional)
24Offset to tableSWI decoding table (optional)
28Offset to codeSWI decoding code (optional)
2COffset to stringMessage file pathname (optional)
30Offset to module feature tableModule_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.

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
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
0

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.

1

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.

2Reserved, must be zero
3Reserved, 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:

ValueMeaning
0ARM 32 bit (A32)
1ARM 64 bit (A64)
2x86 64 bit (x86-64)
3-14Reserved
15Python (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-31Reserved, 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.