14 : Operating System Calls

The Archimedes Operating Systems, Arthur and RISC OS, provide a wealth of routines that may be called by the user program, even from within BASIC. In fact, the only way to exploit the full potential of the machine is by making use of these detailed routines. Some Operating System functions are packaged up in BASIC for convenience, such as the VDU calls and the PLOT commands. Further functions are available in the form of star commands, though for greater flexibility these are often called from within basic programs using the OSCLI call.

However, to make full use of all the system functions available, they must be called more directly. Previous versions of BBC basic relied on the use of CALL (and sometimes USR) to access system functions, but BASIC V provides a new, general purpose call to do this. This is the SYS function, and it has its direct counterpart in ARM assembler in the form of the SWI call.

A SWI call is a SoftWare Interrupt. When a SWI call is executed, the ARM processor leaves the current program and jumps to a fixed location in memory. This in turn contains a branch instruction into the Operating System ROM where the SWI call is decoded and the correct routine entered, with appropriate parameters. Once execution of the call is complete, control is returned to the user's program.

Every legitimate SWI call has a number to identify it, but the name of the SWI can be used instead (it must be precisely specified including use of upper and lower case characters), and this is much to be preferred for readability. The name must be enclosed in inverted commas, as with any string. The SWI call also allows parameters to be passed to the routine called, and provides for information to be returned.

SYS Calls

In BASIC V, SYS is the exact counterpart of the SWI call, and should be used to access all Operating System routines. The general format of a SYS call is as follows:

    SYS <name/number>,<parameters> TO <variables> ;<flags>

Again, note that the name of the SYS call, the same name as for the corresponding SWI call, must be in inverted commas. Up to eight 'input' parameters may be specified immediately following the SYS call name or number, and these values are assigned, in order, to the first eight registers, R0 to R7. If a parameter supplies a numeric value, this is converted to integer format and stored in the corresponding register; if the parameter supplies a string, a zero byte is added to the end of the string, and the string stored on BASIC's stack at a word-aligned start address, and a pointer to the string placed in the appropriate register.

Following the keyword TO, a list of 'output' variables can be included, which will be used to return values to the calling program. These operate as the counterpart of the input parameters, that is, each variable in turn is associated with the registers R0 to R7. If the variable is numeric, the value in the corresponding register is returned in the appropriate format, real or integer, to the variable. If the variable is of type string, the contents of the corresponding register are treated as a pointer to a string stored in memory, and this string is then assigned to the string variable.

The first parameter is separated from the SYS function name by a comma, and subsequent parameters are separated from each other by further commas. For the output variables, the first is separated from the 'TO' by a space, the remainder by commas. Both parameters and variables in sequence may be omitted provided the commas are included. Therefore:

    SYS "DummyFunction",,b,c,,e TO A,,,,E

would result in the input values supplied by b, c, and e being linked to registers Ri, R2 and R4, with the output variables A and E being linked to registers R0 and R4. Notice, on the input side, the comma immediately following the SYS function name indicating that the value which would be linked to register ro has been omitted. By this means, any of the registers R0 to R7 can be linked to input parameters or output variables as required, even if intermediate registers are not used. Depending on how some SYS functions are used, you may find that you use different register combinations in different contexts with the same sys call. Some more examples of sys call syntax are given at the end of this chapter.

The same variables may be included on both the input and output sides of the SYS call, and will result in the input parameters being overwritten. The only point to watch, if this is followed, is that a return string cannot exceed the length of an input string where the same variable is to be used for both.

You will find, in practice, that some SYS calls need no parameters at all, some need input parameters, some output parameters and some both. In addition, if a variable is specified following a semi-colon at the end of a SYS call, this will be set to the processor flag bits on return. These are the bits NZCV from the arm status register. The input parameters may be values or expressions, including simple variables, but the output parameters, because they are used to return values, must always be specified as variables.

Three particular SWI, or SYS, calls are worth mentioning individually. The call OS_CLI is directly equivalent to OSCLI, and passes a string to the Command Line Interpreter. The calls OS_Byte and OS_Word each provide a variety of different functions, and are provided in this form for the sake of compatibility with similarly named calls on the BBC Micro and Master series.

All the SWI calls are documented in the Programmer's Reference Manual, and this is essential reading if you want to take full advantage of them. Remember also that some SWI calls directly reference routines in the Operating System ROM, while others call routines in relocatable modules. In practice the two are indistinguishable, and all such calls can be thought of as system calls.

As an indication of what can be achieved, I have listed some of the SWI calls below.

There are many more sys calls to the Wimp manager.

    Font_FindFont      Get pointer to a font
    Font_LoseFont      Remove font definition

Again there are many more SYS calls to the Font manager and also to the sound scheduler.

Finally, I have included a number of SYS calls taken from working programs to show how they might appear within a program.

    SYS "Wimp_OpenWindow",,offset
    SYS "Wimp_CreateWindow",,block% TO handle
    SYS "Sound_QSchedule",Beats%,&F0401C6,A%
    SYS "Sound_InstallVoice" TO ,NVoices%
    SYS "OS_File",5,F$ TO F%,,,,C%,A%
    SYS "OS_ReadPalette",pixel,16 TO ,,foreground,background

Notice the ways in which commas have been used in the above examples to select which registers are to be used for parameter passing.