Appendix41Appendix G: CMHG File Format

title-string

Defines the module's internal name, as shown by *Modules. It should normally be a single word and is best kept below about 16 characters.

title-string: MyModule

help-string

Defines the descriptive string shown by *Help Modules. The usual form is:

ModuleTitle VersionNumber Comment

The version number should normally be written as d.dd.

help-string: MyModule 1.00 (06 Apr 2026) Copyright 2026

date-string

CMunge extension. Supplies an explicit build date string when the date is not intended to be derived only from the help string.

date-string: 06 Apr 2026

initialisation-code

Names the C function called when the module is initialised or reinitialised.

C prototype: _kernel_oserror *init(const char *tail, int podule_base, void *pw);

Return NULL for success, or a pointer to an error block to abort initialisation. Finalisation code is not called if initialisation fails.

finalisation-code

Names the C function called when the module is being killed, just before the C library is shut down.

C prototype: _kernel_oserror *final(int fatal, int podule, void *pw);

Return NULL to allow termination, or an error pointer to refuse it.

service-call-handler

Names the C function that handles service calls. It may be followed by a list of service numbers to filter, which is usually preferable to receiving every service call.

C prototype: void *service(int number, _kernel_swi_regs *r, void *pw);

module-is-runnable

Declares that the module may be run as an application, so that the C main function can be entered in user mode.

C prototype: int main(int argc, char *argv[]);

module-is-not-reentrant

Declares that the module is not reentrant and must not be entered again while already running.

module-is-c-plus-plus

CMunge extension for modules containing C++ code built with the supported C++ toolchain arrangements.

module-is-initialised-early

CMunge extension for modules that must be initialised early in the boot sequence, mainly for ROM use.

swi-chunk-base-number

Supplies the base SWI number for the module chunk of 64 SWIs. The X bit must not be set in this value.

Two concrete rules follow from the chunk being 64 entries wide: the base number must be a multiple of 64 (its low 6 bits must be zero), and it must not have bit 17 (&20000, the "X bit") set. Allocated chunk ranges are &0-&3FFC0 for operating-system use, &40000-&7FFC0 for operating-system extensions, &80000-&BFFC0 for third-party applications, and &C0000-&FFFC0 for user applications; any chunk used in a distributed module must be registered.

swi-handler-code

Names the central dispatcher for SWIs in the chunk.

C prototype: _kernel_oserror *swi_handler(int number, _kernel_swi_regs *r, void *pw);

number is the 0 to 63 offset within the chunk.

swi-decoding-table

Defines the SWI prefix and the decoding names:

swi-decoding-table: MyMod, Get, Set, Reset/MyResetHandler

The first entry is the SWI prefix. Each later entry names one SWI and may optionally route that SWI to a specific handler with /<handler>.

swi-decoding-code

Provides custom name-to-number and number-to-name translation code. Both the older single-function interface and the newer two-function interface are supported.

command-keyword-table

Defines the module's * command table. The first parameter is the name of the central command handler function, or - if every command uses its own handler or explicitly has no handler.

C prototype for the default handler: _kernel_oserror *command(const char *arg_string, int argc, int number, void *pw);

Each command entry may use sub-keywords such as:

generic-veneers

Defines general callback veneers using the form EntryName[/HandlerName](...). Optional parameters include private-word: and carry-capable:.

vector-handlers

Defines veneers for claimable RISC OS vectors such as TickerV. The generated C header exports an extern void name(void) symbol whose address should be passed to OS_Claim or similar interfaces.

C prototype: int handler(_kernel_swi_regs *r, void *pw);

irq-handlers

Obsolete alias for vector-handlers: both CMHG and CMunge continue to accept it, mapped internally to the same handling, so existing CMHG files using it do not need to be changed to keep working. New descriptions should use vector-handlers directly.

vector-traps

CMunge extension for advanced vector chaining where the remainder of the vector chain must be callable explicitly from the handler.

event-handler

Defines an event veneer. Only one entry may appear in a single directive, but the directive may be repeated. Event-number filtering is supported and is recommended for performance.

C prototype: int handler(_kernel_swi_regs *r, void *pw);

error-chunk-base-number / error-base

CMunge extension that defines the module's base error number. The value is also exported as ERROR_BASE in the generated header.

The example value below is illustrative only. A real module distributed outside this project should have its error base registered with the RISC OS Open allocation service rather than chosen arbitrarily, the same as a SWI chunk; see the allocating-resources skill for the registration process.

error-chunk-base-number: &12345

error-identifiers

CMunge extension for defining named error constants that are exported to the C header.

library-initialisation-code

Overrides the C library initialisation symbol. The replacement routine must be written in assembly and must still call the normal _clib_initialisemodule.

library-enter-code

Overrides the module entry symbol normally provided by the C library support code.

international-help-file

Embeds a literal path to the Messages file used for internationalised help and syntax text.