www.riscos.com Technical Support: Acorn Assembler

Writing relocatable modules in assembler

Relocatable modules are the basic building blocks of RISC OS and the means by which RISC OS can be extended by a user.

The relocatable module system provides mechanisms suitable for

• providing device drivers
• extending the set of RISC OS *commands
• providing shared services to applications (eg the shared C library)
• implementing 'terminate and stay resident' (TSR) applications.

All these projects require code either to be more persistent than standard RISC OS applications or to be used by more than one application, hence resident in the address space of more than one application. If your program does not have these requirements it is not recommended to put it in modules, as relocatable modules are more persistent consumers of system resources than applications, and are also more difficult to debug.

This chapter is not intended to provide a complete set of the technical details you need to know to construct any relocatable module. For more information on such details, see the RISC OS 3 Programmer's Reference Manual. The points covered here are intended to provide help for constructing relocatable modules specifically in assembly language.

For more details of memory management in relocatable modules, you should again see the RISC OS 3 Programmer's Reference Manual.

Unlike the construction of relocatable modules in high level languages, no tools are provided to generate substantial standard portions of code. This means that you have to construct the module header table, workspace routines, etc. yourself.

Note that some of the relocatable module entry points are called in SVC mode. Such routines may use SWIs implemented by other parts of RISC OS, but unlike being in user mode, SWIs corrupt R14, so this must be stored away. Floating point instructions should not be used from SVC mode.

Assembler directives

ObjAsm can be used to assemble a module from a set of source files, a link step being required to join the output object files to form the usable module. The separation of routines into separately assembled files has several advantages.

It can be a good idea to construct a module with the module header and the small routines/data associated with it in one source file, to be linked with the code forming the body of the module.

Such a module header file must be linked so that it is placed first in the module binary. To do this it should contain an AREA directive at its head such as:

        AREA |!!!Module$$Header|, CODE, READONLY

Areas are sorted by type and name; a name beginning with '!' is placed before an alphabetic name, so the above can be used to ensure first placing.

The module header source needs to contain IMPORT directives making available any symbols referenced in the module body. In addition, the initialisation routine should call __RelocCode, a routine added by the linker which relocates any absolute references to symbols when the module is initialised. If the module header source contains the initialisation routine, it must use the IMPORT directive to make __RelocCode available.

The module header must be preceded by the ENTRY directive:

        ENTRY

Module_BaseAddr
        DCD     RM_Start    - Module_BaseAddr
        DCD     RM_Init     - Module_BaseAddr
        DCD     RM_Die      - Module_BaseAddr
        DCD     RM_Service  - Module_BaseAddr
        DCD     RM_Title    - Module_BaseAddr
        DCD     RM_HelpStr  - Module_BaseAddr
        DCD     RM_HC_Table - Module_BaseAddr

Example

This product is supplied with the source for an example relocatable module that provides an extra soft screen mode: Mode 63. This has to be done via service call handling, and to be useful must be persistent, so providing a typical use of relocatable modules.

There are two source files held in AcornC_C++.Examples.AsmModule.s:

• The ModeExHdr file produces the module header, and may be useful for you to copy and edit to form headers for your own modules.
• The other file, ModeExBody, is the source for the main module body.

To build the module, use ObjAsm to assemble the source. Then link the resultant object files using Link, remembering first to set the Module option on its Setup dialogue box.

The module is specific to VIDC1 and VIDC1a, and so will not work on Acorn computers that are fitted with later versions of VIDC - such as the Risc PC.