ClaimASWI
=========
The ClaimASWI Module
Version 0.0.0 (29 Apr 2007)

Introduction
------------
Some versions of RISC OS provide an API for claiming software interrupts
from within the initial block of 256 which are reserved for use by the
operating system. The API consists of the SWIs OS_ClaimSWI, OS_ReleaseSWI
and OS_ClaimOSSWI. The purpose of this module is to add that functionality
to versions of RISC OS which do not otherwise support it.

Background
----------
Traditionally the accepted method for claiming an OS software interrupt was
to patch the SWI despatch table. For early versions of RISC OS this was a
straightforward matter because the address of the table was fixed at
&01F033FC. The table had 256 entries and was indexed by SWI number, with
each entry being a pointer to the corresponding handler function. Return
from the function was by jumping to the address immediately after the end of
the table.

RISC OS 5.00 moved the despatch table into a much higher area of memory in
order to make space for an enlarged application area. The structure and
meaning of the despatch table were not changed. OS_ReadSysInfo was extended
to provide access to the address of the table, but since this extension is
not supported by most earlier versions of RISC OS there is no single
procedure for locating the table which is guaranteed to work across all
systems.

Using an API to modify the despatch table has the advantage of hiding these
complications. Unfortunately there are even fewer versions of RISC OS that
support the API than there are which support the extended OS_ReadSysInfo,
however that can now be remedied by installing this module on machines where
it is needed.

Some other (possibly more important) benefits of the API are that it allows
a private word to be passed in R12 to the SWI handler function, and does not
require that the handler function preserve R14. These points are significant
because they make it possible for the handler function to be written in C.

SWI Handler Functions
---------------------
Entry and exit conditions for SWI handler functions installed using this API
are the same as those for a SWI handler which is part of a module, except
that the SWI number passed in R11 will be in the range &00 to &FF rather
than &00 to &3F.

OS_ClaimSWI (&62)
-----------------
Claim a software interrupt

On entry
 R0 = software interrupt number
 R1 = address of claiming routine
 R2 = value to be passed in R12 when the routine is called

On exit

Use
This call claims a software interrupt in the range &00 to &FF. It is
equivalent to calling OS_ClaimOSSWI with a reason code of 0, except that
different registers are used on entry and nothing is returned on exit.

OS_ReleaseSWI (&63)
-------------------
Release a software interrupt

On entry
R0 = software interrupt number
R1 = previous address of claiming routine
R2 = value previously passed in R12 when the routine was called

On exit

Use
This call releases a software interrupt previously claimed using
OS_ClaimSWI. It is equivalent to calling OS_ClaimOSSWI with a reason code of
1, except that different registers are used on entry and nothing is returned
on exit.

OS_ClaimOSSWI (&77)
-------------------
Claim a software interrupt

On entry
 R0 = reason code
 Other registers depend on reason code

On exit
 R0 = preserved
 Other registers depend on reason code

Use
This call claims or releases a software interrupt in the range &00 to &FF.

R0 = 0 claim software interrupt
   = 1 release software interrupt

OS_ClaimOSSWI (&77) 0
---------------------
Claim a software interrupt

On entry
 R0 = 0
 R1 = software interrupt number
 R2 = address of claiming routine
 R3 = value to be passed in R12 when the routine is called

On exit
 R2 = previous address of claiming routine
 R3 = value previously passed in R12 when the routine was called

Use
This call claims a software interrupt in the range &00 to &FF.

OS_ClaimOSSWI (&77) 1
---------------------
Release a software interrupt

On entry
 R0 = 1
 R1 = software interrupt number
 R2 = previous address of claiming routine
 R3 = value previously passed in R12 when the routine was called

On exit

Use
This call releases a software interrupt previously claimed using
OS_ClaimOSSWI 0.