Programmer

Extended C functions

For some time the SharedCLibrary core (library chunk ID 2) has provided two additional functions over those documented in the PRMs. The _clib_version function, used to read the C library details, has been expanded to give more detail on the components that make up the library. This document provides a description of these functions.

Functions

All these functions use APCS-R or APCS-32 (dependent on linkage) calling conventions.

Language support functions

Entry number 180: const char *_clib_version(void);

This function returns a read-only string giving information on the C library. The string is composed of a number of newline delimited fields. Each field describes a component of the shared library, with the first field describing the overall features of the library.

The initial field will take the form :

      "C library[<qualifiers>]"
   where <qualifiers> is a sequence of strings prefixed by a '/' character
   to indicate the facilities offered by the core library. The only defined
   qualifier at present is "/R" :
      /R   Indicates that the format of the jmp_buf array is fixed to the
           logical APCS-A bindings of registers. That is, the format is :
              v4-v6, fp, sp, sl, lr, f4-f7

Subsequent fields within the returned string describe the component versions in the form :

      "<component> vsn <version> (<date>)[<qualifiers>]"

The <version> is a 3 digit decimal number indicating the version number of that component.
The <date> is a standard RISC OS date string ("DD MMM YYYY") giving the date of this version of the component.
The <qualifiers> are formed in a similar manner to the overall features but the qualifiers should be interpreted on a component-specific basis. No qualifiers have been defined for any of the components. The current component names which may be used to construct the C library are :

       Kernel      The Run Time System Kernel which manages the environment
                   used by the C library
       Core        Core C library functions
       C99Low      Low-level C functions (primarily variable length arrays,
                   and 64bit operations)
       C99         High-level C functions (all other C99-specific features)
       RISC_OSLib  Name allocated, but unused
       Shared C Library
                   Indicates that the C library is part of the
                   'SharedCLibrary' module.

The prior definition of this function placed no meaning on the string returned, and did not declare that the returned string was const. This definition improves that description. Under earlier versions of the Shared C Library (and ANSILib), this function would return a string in the form :

      "[Shared ]C Library vsn <version>/R \[<cppdate>\]\n"

where <cppdate> is a date as produced by the C pre-processor __DATE__ macro (MMM DD YYY). The new format retains a similar style to this earlier form and so should be machine-parseable by code which previously interpreted the string value. The new format remains printable, so should be usable for diagnostic purposes.

Variadic SWI call

Entry number 183 : int _swi(int swi_number, unsigned int flags, ...);

Entry number 184: _kernel_oserror *_swix(int swi_number, unsigned int mask, ...);

These functions provide a generic method of calling RISC OS SWIs from C or C++.

Two functions are provided:

      _swi for calling SWIs without setting the X bit
      _swix which sets the X bit before calling the SWI.

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.
   bit 10:         Unused.
   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.
   bits 16-19:     Register number to be returned from a _swi call. This is only
                   applicable to _swi as _swix always returns either 0 or an error pointer.
   bit 20:         Unused.
   bit 21:         Set if the PC (including the flags) is to be output.
   bits 22-31:     Set if R(31-N) is output from the SWI (ie bit 31 corresponds to R0,
                   bit 22 corresponds to R9).

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 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

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015