OS_Byte Introduction (changes)

Showing changes from revision #1 to #2: Added | Removed | Changed

Programmer's Reference Manuals

» Part 1 - Introduction?OS_Byte & OS_Word

» OS_Byte IntroductionOS_Byte & OS_Word

Overview

RISC OS provide numerous SWIs that perform many different operations. Most SWIs functions are specified by their name. e.g. OS_RemoveCursors removes cursors. However, there are two SWIs that perform a wide variety of different operations. They are OS_Byte and OS_Word.

This document provides information on OS_Byte.

The OS_Byte SWI uses at most three registers. The registers upon entry are detailed below:

The name OS_Byte originates from the use of one byte per parameter (values of 0 to 255). It is important to note that the register actually passes the value as 32-bit parameters, and mask out the top 24-bits.

Any routine written to implement or decode OS_Byte calls, must preserve the top 24-bits, at least in R0. This can be achieved by masking the parameters into temporary registers instead of back into the passed parameters.

Some operations of OS_Byte result in returned values too large to fit into a single byte, and should be treated as whole words.

Reason codes

The value passed by R0 specifies the operation to be performed. The reason code must be a value from 0 to 255. Although a large number of different operations are available, the reason codes are grouped by parameter usage.

Reason codes 0 – 127

Where the reason code is between 0 and 127 (inclusive), only R1 is used to pass information to the SWI routine. However, R2 is sometimes used as a temporary register that is corrupted during the SWI routine.

Reason codes 128 – 165

Where the reason code is between 128 and 165 (inclusive), both R1 and R2 are used to pass values to the SWI routine. They may also be used to return values upon exit.

They are often used to return information, rather than perform a particular action.

Reason codes 166 – 255

Where the reason code is between 166 and 255 (inclusive), both R1 and R2 are used to pass values to the SWI routine. In addition, R0 is also used as an index pointer into the RAM which holds the status variables, which are held in consecutive memory locations. i.e. When R0 = 166, points to the first status variable, R1 = 167 points to the second status variable, and so on.

The contents of R1 and R2 determines what happens to the status variable. The formula below shows how the new value of the status variable is calculated:

New_Value = (Old_Value AND R2) EOR R1

On exit:

• R1 = old value of status variable
• R2 = value of status variable in the next adjacent memory location (except when R0 = 255)

To read a value without being altered, the following Register values should be used:

• R1 = &00
• R2 = &FF

To write a specific value, the following Register values should be used:

• R1 = New_Value
• R2 = &00

To alter specific bits, the following Register values should be used:

• R1 = Set the bits to the new value you want them to have
• R2 = Clear the bits that you wish to alter

e.g. If bits 5,6 & 7 are to be changed, to the binary pattern 101, then the following binary values should be used:

• R1 = 10100000 (bits to set)
• R2 = 11100000 (bits to alter)

Interrupt handling

OS_Byte is a vectored SWI, but before its vector is called, interrupts are disabled. Most OS_Byte routines are so short that there is no need to re-enable interrupts, and instead rely on RISC OS to do this when control is returned to the program that issued the SWI.

Because the interrupts are not re-enabled, the routines are also used by interrupt handling routines.

If you wish to replace an OS_Byte routine, you must ensure that the replacement routine:

• does not change the way it alters the interrupt status
• does not take so long that interrupts are disabled for unreasonable period of time

Adding OS_Byte calls

Because the OS_Byte is a vectored SWI, it is possible to add your own OS_Byte calls by installing a routine on the software vector that OS_Byte uses.

For more information, read the Software Vectors section.

*Command

Because OS_Byte performs a lot of very useful functions, RISC OS provides a *Command to call the routine directly. The command is *FX.

Because *FX cannot display any return values, it is not possible to use the command to read the values of status variables.

See also

• OS_Byte
• OS_Word
• *FX