File formats: Relocatable Module (Rev #1)

Programmer's Reference Manuals

» Tables?

» Filetypes

» Module

Relocatable Modules

Modules (filetype &FFA) lie at the heart of RISC OS. A module extends the operating system, or replaces part of it.

For example, while we are used to periodically updating our ROM image on current hardware, on older machines the ROM was a physical ROM so it was common to load a later version of the SharedCLibrary which would replace the one supplied with RISC OS. Likewise, the “nested Wimp” would also be loaded from disc and would entirely replace the older and less capable Wimp supplied in ROM.

Asides from the replacement issue, modules can be used to extend system functionality. For instance, Fat32FS is an extended and more capable version of DOSFS. SparkFS provides a filing system interface to archive files, where they can be opened as if regular directories. A USB-MIDI module exists to permit simpler communication with MIDI keyboards using a USB interface. The options are nearly endless.

Module header

Modules consist of code and data in a single file that is prefixed by a header. The header provides offsets to various entry points and data.
An 26 bit module must have at least the first seven fields. A 32 bit module must have all fields present (as the last one is the 32 bit flag).
Fields that are not required may be zero. Most fields are offsets, and the offset must point within the module itself or the operating system will reject the module.

Start code

Calling OS_Module with either Run or Enter will enter a module through this offset, as will the *RMRun command.

On entry:

The processor is in User mode with interrupts enabled. This entry point is not re-entrant.

This call does not return.

On exit:
As this was started as the current application, it should exit by calling OS_Exit.

Note that the field need not actually be an offset. If it cannot be interpreted as an offset, it will instead be executed. This permits the first instruction to be a branch which may be useful to directly run the application code during development, as if it was a normal application and not a module.

This entry is important for having modules that can provide Wimp tasks.

Initialisation code

…

Finalisation code

…

Title string

…

Help string

…

Help and Command Keyword table

…

SWI chunk base number

…

SWI handler code

…

SWI decoding table

…

SWI decoding code

…

Messages file name

…

Module flags

…

See also

For more complete information on modules, please refer to the chapter on Modules in book 1 of the Programmer’s Reference Manuals. It’s a very big chapter.