Introduction To SWIs (changes)

Showing changes from revision #11 to #12: Added | Removed | Changed

Programmer's Reference Manuals

» Introduction to SWIs

Software Interrupts, or SWIs for short, are a set of powerful instructions to allow developers to interact with the Operating System, without allowing any direct control in Supervisor Mode. The process of using a SWI is as follows:

1. Program issues a specific SWI instruction
2. ARM leaves the program and jumps to a fixed location in memory where there is normally a branch instruction into the RISC OS kernel
3. SWI instruction is examined the particular OS routine to be run is determined
4. The OS routine is called, as specified by the SWI
5. Control returned back to program

A SWI consists of a unique name, number, and usually requires parameters to be passed. Because RISC OS is modular, different modules implement specific SWIs.

SWI Names and Numbers

A SWI can be used by either referring to its unique name or number. The 24-bit number, known as the SWI number, is used by RISC OS to identify the routine. The exact method that RISC OS uses to decode the SWI is unimportant. As long as the correct SWI name or number, along with any parameters (if required), are used, then the correct result will be returned.

It is generally advised to use the SWI names when calling SWIs as it improves readability and helps create code that can be updated more easily. It is also important to note that SWI names are case sensitive. They must be typed exactly as documented, otherwise RISC OS will not identify the SWI, and an error will be returned. The names usually follow ‘Camel Case’ rules; e.g. “BinaryToDecimal”.

SWI Numbers

A SWI instruction is allocated a unique number. 24-bits are used to specify the SWI number (0 – &FFFFFF), although only SWIs from &40000 (bit 19 must be set) upwards are available for 3^rd party use, as the others are assigned for internal use by RISC OS (although only a small percentage are currently used).

Modules can also provide their own SWIs, and must provide unique SWI numbers. This feature allows for SWIs that perform related functions to be grouped together as part of a module.

If a program executes a SWI that is not recognised, the OS calls a special routine called the ‘Unused SWI Vector’, or UKSWIV, for short. This usually returns the generic ‘No such SWI’ error message. However, it is possible for an application to claim this vector, and if the SWI number is recognised by the program, perform the appropriate task.

24-bit Address Field

The 24-bit SWI number consists of the following:

SWI Groups

SWI Names

SWI names are broken into two discrete parts separated by the underscore character ‘_’. The prefix specifies which part of the system will deal with the SWI. The prefix name usually specifies by the module which implements the SWI (e.g. Wimp, Font, ADFS, FileCore, etc.).

The suffix specifies the function of the SWI, and when added to the prefix forms the chunk name . The chunk name is usually the name of the module that provides the SWI, although it is dependent on the name when registering the SWI. Some examples are shown below:

Parameters and Results

The ARM registers R0-R9 are used to pass parameters and results to and from SWI routines. Unlike the APCS? standard that’s used with most C code, there is no global standard for how the registers are used by SWIs – you must consult the documentation of each SWI call to determine whether a register is an input or an output. However, it is always the case that a SWI which returns an error will return the error block pointer in R0 (see Error handling)

For the OS SWIs documented on this wiki, it’s generally the case that any register which isn’t used as an input or an output will be preserved across the SWI call. However for some SWIs certain registers will be corrupted – these cases will be noted in the SWI documentation.

PSR fields as inputs

• On 26bit OS versions, SWI handlers are entered with R14 containing the caller’s NZCIF flags.
• On 32bit OS versions, there is no way for a SWI to determine the caller’s NZCIF flags.
• For all OS versions, the SWI handler is entered with the V flag clear (in both the PC/PSR and R14, as appropriate).
• For all OS versions, there is no way to determine the caller’s processor mode.

The above rules do not apply to kernel SWIs, which are able to fully examine the caller’s PSR.

PSR fields as outputs

NZC flags

Some SWIs use the NZC flags to return values. Normally this is limited to just returning a value in the C flag, but the N and Z flags can be used as well.

If a value isn’t explicitly being returned in an NZC flag, the behaviour differs by OS version:

• For 26bit OS versions, the convention is for modules (including 32bit compatible modules) to preserve the flags. However because this is dependent on the implementation of the module, there are no guarantees as to the behaviour.
• For 32bit OS versions, flags should always be considered to be corrupt (because the SWI handler is not passed the original flags on entry).

V flag

The V flag is used to indicate an error state (see Error handling). If the SWI generates an error the V flag will be set; if the SWI does not generate an error then the V flag will be cleared, even if the flag was set on entry.

Other fields

Only kernel SWIs are able to return to the caller in a different CPU mode or with altered interrupt states. However there are a number of SWIs which will temporarily enable IRQs or FIQs during execution.

Error handling

RISC OS provides error handling facilities for SWIs. There are two possible steps to the error checking process:

1. Check if an error occurred during the execution of the SWI routine
   • If an error has been generated by the SWI routine, the V flag is set, and R0 points to an error block on exit, and then proceed to the second step in the error checking process
   • If no error has been generated by the SWI routine, the V flag is clear on exit
2. Check if the X bit (bit 17) of the SWI instruction was set prior to entering the SWI routine
   • If the X bit was set before the routine, then RISC OS returns control back to the program, which must then deal with the error. The V flag remains set, and R0 points to an error block on exit (known as error-returning)
   • If the X bit was clear before the routine, then RISC OS deals with the error itself. It does this by passing the error to the error handler used by the program (known as error-generating)

The state of the X bit determines how RISC OS deals with a SWI error. It is sometimes useful for RISC OS to deal with an error, while other times it is best if your own program deals with an error. An error-returning SWI can be specified by two different methods:

• Add the value &20000 to the SWI number
• Add the letter ‘X’ in front of the SWI name; thus OS_WriteC becomes XOS_WriteC

As the most common method of using SWIs is by name.

A detailed summary of how RISC OS handles Error-generating SWIs is provided below, although it is not usually necessary to understand this low-level information.

1. RISC OS informs modules of the error using OS_ServiceCall (service number 6) so that it can tidy up. e.g. close files, and so on, before RISC OS handles the error
2. RISC OS then calls the error vector (ErrorV?), so it may tidy up (if required). The vector can be claimed, however, the error handler must deal with the error, and not your program

Error numbers

If an error has been generated, R0 points to an error block that identifies the type of error. The format of the error block is described here

The error number contained as part of the error block specifies the type of error. The error number is a 32-bit number, and is divided into three discrete parts:

• The bottom byte is known as the basic error number
• The middle two bytes identifies the cause of the error
• The top byte contains flags; as detailed below

Generating errors

It is possible to generate an error by calling OS_GenerateError. The error will be passed to the current error handler, and the SWI call will not return to the caller.

Writing system extension code

When writing system extension code, such as a module or interrupt handler, it is vital that it does not generate errors. This is because users expect it to ‘just work’. When issuing SWIs in system extension code, they must always have their X bit set. i.e. either add the value &20000 to the SWI number, or add the letter ‘X’ in front of the SWI name.

The exception to the rule is when reporting exception-type errors (i.e. when bit 31 of the error number is set, indicating a serious error).

Allocating SWIs

For software that is to be released to the general public, SWI names and numbers must be allocated through RISC OS Open using their Allocate tool (RISC OS software only), available here.

When registering a SWI, a Chunk Name must be provided, and this will be used as part of the SWI name. e.g. ChunkName_Function.

For software which is for private use only, the author is free to pick any SWI names and chunk numbers, so long as the ‘User Applications’ SWI group (bits 18-19 set to 2_11) is used. In this case, it is the author’s responsibility to ensure the name and chunk does not clash with any other SWIs on their system.

See also

• SWI Error Block