using-cmhg

name	using-cmhg
description	Describes the CMHG file format and CMunge usage. Use when CMHG files are required for RISC OS modules.
metadata	{"author":"[e-mail]"}
license	MIT
allowed-tools	Bash(riscos-prm:*)

CMunge Skill Summary

Purpose

CMunge is an enhanced, free alternative to the Acorn C Module Header Generator (CMHG). It generates ARM assembly "veneers" that allow RISC OS relocatable modules to be written in C or C++. It supports 26-bit, 32-bit, and 64-bit ARM architectures.

Command Line Usage

CMunge [options] <infile>

Key options:

• -o <file>: Output object (AOF) file.
• -s <file>: Output assembly file.
• -d <file>: Output C header file.
• -26bit: Target legacy 26-bit ARM (default).
• -32bit: Target 32-bit compatible ARM.
• -64bit: Target 64-bit (AArch64) ARM for GCC.
• -p / -px: Pre-process input file (standard / extended).
• -throwback: Enable error reporting to editors.
• -zoslib / -zoslibpath: Use OSLib header styles.

CMHG/CMunge Directives Summary

• title-string: Internal module name.
• help-string: Descriptive name and version.
• initialisation-code: C function called on load.
• finalisation-code: C function called on unload.
• module-is-initialised-early: (CMunge) Requests early initialization for ROM.
• service-call-handler: C function for service calls.
• swi-chunk-base-number: Base SWI number.
• swi-handler-code: Central SWI handler C function.
• swi-decoding-table: Lists SWI names and optional specific handlers.
• command-keyword-table: Defines *Commands and their handlers — see references/command-tables.md.
• generic-veneers: General purpose C wrappers.
• vector-handlers: Wrappers for claiming RISC OS vectors - see references/vectors.md
• event-handler: Wrappers for RISC OS events.
• error-base (CMunge): Base error number for the module.
• error-identifiers (CMunge): Automatically generates error definitions.
• vector-traps (CMunge): Advanced vector chaining handlers — see references/vector-traps.md.
• library-initialisation-code / library-enter-code: Override C library entry symbols.

Generic veneers reference index

These files describe common generic veneer usage patterns:

• Timers: OS_CallEvery, OS_CallAfter, and OS_RemoveTickerEvent.
• OS_AddCallBack/OS_RemoveCallBack deferred work.
• OS_SetVarVal type 16 read/write code variables.
• FilterManager and Internet filter callbacks.
• ImageFileConvert converter and miscellaneous-operation entries.
• ImageFileRender render, bbox, info, declare, start, and stop entries.
• colour-map workspace, function descriptors.
• DBResultManager provider callbacks.
• OS_DynamicArea handlers.
• Vectors claimed with OS_Claim.
• OS_ClaimOSSWI handlers.
• PPP, WebFTP, AUN, and network driver callback entries.
• SCSI provider operation callbacks.
• abort traps and ErrorV handling.
• hand-built callback trampolines and carry-capable:.

All of these use the same CMHG mechanism:

generic-veneers: EntryName/HandlerName

CMHG generates EntryName, which is the address passed to the OS or another module. The C function HandlerName is called by the veneer with:

_kernel_oserror *HandlerName(_kernel_swi_regs *r, void *pw);

The handler reads and writes the register block according to the owning API's ABI, not according to CMHG itself.

Service call reference index

General information on CMHG syntax, C handler ABI, claiming, and filtering is in the Service Calls overview.

These files describe common CMHG service-call-handler usage patterns:

• startup, shutdown, reset, and manager started/dying notifications
• ResourceFS related registration services
• Toolbox object/task lifecycle, Wimp start/shutdown, submenu mediation
• filing-system redeclaration, filer lifecycle, disc dismount, and MultiFS format negotiation
• mode changes, display changes/status, screen mode enumeration, and blanking
• SCSI, USB, buffers, sound, and other device/provider registrations
• DCI driver/protocol, Internet state, PPP, Freeway, and statistics services
• ImageFileConvert and ImageFileRender registry lifecycle services
• services used as synchronous extension interfaces by claiming and returning register values
• Service_UKCompression and Service_ModulePreInit patching hooks
• desktop banners, Wimp shutdown, TaskManager acknowledgements, and shutdown services
• Service_APCSBacktrace diagnostic extension and minidump hooks
• Service_ErrorStarting and related Wimp error-report monitoring hooks

Service information may often also be found through the riscos-prm --url Service_... command.

CMHG style guidelines

• Don't remove the comment sections that describe the file. They are useful for humans to know how to add new sections.
• Any definition which may be split across lines if the definition is incomplete. For example, a list of SWIs like:

swi-decoding-table: JUnitXML Create/SWI_Create TestSuite/SWI_TestSuite TestCase/SWI_TestCase Close/SWI_Close

Can be comma separated, thus:

swi-decoding-table: JUnitXML Create/SWI_Create, TestSuite/SWI_TestSuite, TestCase/SWI_TestCase Close/SWI_Close

And the comma separated parts can be split if the comma is the last entry on the line:

swi-decoding-table: JUnitXML Create/SWI_Create,
                             TestSuite/SWI_TestSuite,
                             TestCase/SWI_TestCase,
                             Close/SWI_Close

Which makes for nice aligned text.

• If services are required for the module, use the symbolic names where possible from the include file riscos/Services.h. This can be included using C preprocessor includes, like this:

#include "riscos/Services.h"

service-call-handler: Mod_Service Service_ModeChange

References

For more information on the CMHG file format, see references/cmhg-syntax.md.

For examples and detailed syntax of the *Command tables, see references/command-tables.md.

Vectors

• Vectors can be claimed or passed on. For detailed information on vectors including a worked example, see references/vector-traps.md.
• If you need to post-process the vector results after it is passed on, see the vector-traps docuemnt for a worked example in references/vector-traps.md.