_swi & _swix
------------

These functions provide a generic method of calling RISC OS SWIs from C. They
are the preferred method of calling SWIs.

Two functions are provided _swi, for calling SWIs without setting the X bit
and _swix which sets the X bit before calling the SWI.

The definitions for these functions are

extern int _swi(int swi_no, unsigned int mask, ...);

extern int _swix(int swi_no, unsigned int mask, ...);

swi_no is the number of the SWI to be called. This should never have the X bit
set.

mask is a word containing an input and output register mask, a return register,
and a block parameter register.

The arrangement of mask is as follows:

Bits 0 -  9:  Set if R(N) is passed to the SWI.
Bits 22 - 31: Set if R(31-N) is output from the SWI (ie bit 31
              corresponds to R0, bit 22 corresponds to R9).
Bit 21:       Set if the PC (including the flags) is to be output.
Bits 16 - 19: Register no. to be returned from a _swi call. This is only
              applicable to _swi as _swix always returns either 0 or an error
              pointer.
Bit 11:       Set if a local block parameter is to be passed to the SWI
Bits 12 - 15: Register number for local block parameter if bit 11 set.

If a register is specified as a return register (bits 16-19) it must not also
be specified as an output register in the output register mask (bits 22-31).

If a register is specified as a local block parameter register it must not also
be specified as an input register in the input register mask (bits 0-9).

If the PC is specified as a return register (ie bits 16-19 = 15) or as an
output registers (bit 21 = 1) the value returned will contain the flags in bits
28 to 31 (28 = V, 29 = C, 30 = Z, 31 = N).

The remainder of the variadic arguments are as follows (in order):

The word value of each input register in order from 0 to 9 as specified by bits
0 to 9 of the mask.

The address of a word to be written for each output register in order from
0 to 9 as specified by bits 31 downto 22 of the mask.

The address of a word to be written with the PC value on exit from the SWI if
bit 21 of the register mask is set.

If bit 11 is set the remainder of the arguments are placed in order in a
parameter block and the address of the parameter block is passed to the SWI in
the register specified by bits 12-15.

The functions are declared in the header swis.h along with some macros for
constructing masks and a complete list of system SWI definitions.

The macros are as follows:

_IN(n)       - Specifies that R(n) is used on input
_OUT(n)      - Specifies that R(n) is output
_BLOCK(n)    - Specifies that R(n) is a block parameter
_RETURN(n)   - Specifies that R(n) is returned from _swi.

The values of the macros should be ORed together to produce the value for the
mask.

The following constants are defined

_FLAGS       - the register containing the flags (currently 15)
_C           - mask for the C bit in _FLAGS
_Z           - mask for the Z bit in _FLAGS
_N           - mask for the N bit in _FLAGS

Please use these constants as they may change on ARM 600.

Example calls:

    _swi(OS_NewLine, 0);   /* Must specify 0 register mask */

    _swi(OS_Write0, _IN(0), "Hello, World");

    task_handle = _swi(Wimp_Initialise, _IN(0)|_IN(1)|_IN(2)|_RETURN(1),
                       300, *(int *)"TASK", "Test");

    e = _swix(Wimp_LoadTemplate, _IN(1)|_IN(2)|_IN(3)|_IN(4)|_IN(5)|_IN(6)|_OUT(2)|_OUT(6),
              template_buffer, workspace, workspace_end, -1, "MyWind", next,
              &workspace_end, &next);

    e = _swix(Wimp_SetExtent, _IN(0)|_BLOCK(1), w, minx, miny, maxx, maxy);