RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

The rest of the kernel


Introduction

Kernel calls and commands are covered here that do not merit a chapter by themselves.

The following SWIs are described:

Name Meaning Page
OS_Byte 0 display OS version information OS_Byte 0
OS_HeapSort a fast and memory efficient sorting routine OS_HeapSort
OS_Confirm get a yes or no answer to a question OS_Confirm
OS_CRC calculate a cyclic-redundancy check for block OS_CRC
IIC_Control control of external IIC devices IIC_Control

The following * Commands are also described:

Name Meaning Page
*Configure Language select the language to use at power on *Configure Language
*Help get help on commands *Help

SWI Calls


OS_Byte 0
(SWI &06)

Display OS version or return machine type

On entry

R0 = 0
R1 = 0 to display OS version string, or 1 to return machine type

On exit

R0 preserved
R1 = machine type if R1 = 1 on entry
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

If this is called with R1=0, then an error is returned, the text of which shows the version number and creation date of the operating system. If this is called with R1 = 1, then the machine type is returned in R1. All RISC OS computers return a machine type of 6; earlier non-RISC OS Acorn machines return different values.

Related SWIs

None

Related vectors

ByteV


OS_HeapSort
(SWI &4F)

Heap sort a list of objects

On entry

R0 = number of elements to sort
R1 = pointer to array of word size objects, and flags in top 3 bits
R2 = type of object (0 - 5), or address of comparison routine
R3 = workspace pointer for comparison procedure (only needed if R2 > 5)
R4 = pointer to array of objects to be sorted (only needed if flag(s) set in R1)
R5 = size of an object in R4 (only needed if flag(s) set in R1)
R6 = address of temporary workspace of R5 bytes (only needed if R5 > 16k or bit 29 of R1 is set)

On exit

R0 - R6 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This SWI will sort a list of any objects using the heap sort algorithm. Details of this algorithm can be found in:

Sorting and Searching D.E. Knuth (1973) Addison-Wesley, Reading Massachusetts, pages 145 -149.

It is not as fast as a quicksort for average sorts, but uses no extra memory beyond that which is initially passed in.

Basic usage

Used in the simplest way, only R0, R1 and R2 need be set up. R0 contains the number of objects that are in the list. R1 points to an array of word-sized entries. The value of R2 controls the interpretation of this array:

R2 value Treat R1 as pointing to an array of...
0 cardinal (unsigned integer)
1 integer
2 pointer to cardinal
3 pointer to integer
4 pointer to characters (case insensitive)
5 pointer to characters (case sensitive)
>5 pointer to custom object
In this last case, R2 is the address of the comparison routine
Comparison routine

If the R2 value is less than 6, then this call will handle sorting for you. If you want to sort any other kind of object, then you must provide a routine to compare two items and say which is the greater. Using this technique, any complex array of structures may be sorted. If you wish to use a comparison routine, then R2 contains the address of it. R3 must be set up with a value, usually a workspace pointer.

When called, the comparison routine is entered in SVC mode, with interrupts enabled. R0 and R1 contain two objects from the array passed to this SWI in R1. What they represent depends on what the object is, but in most cases they would be pointers to a structure of some kind. R12 contains the value originally passed in R3 to this SWI. Usually this is a workspace pointer, but it is up to you what it is used for.

Whilst in this routine, R0 - R3 may be corrupted, but all other registers must be preserved. The comparison routine returns a less than state in the flags if the object in R0 is less than the object in R1. A greater or equal state must be returned in the flags if the object in R0 is greater than or equal to the object in R1.

Advanced features

In cases where R2 is greater than 1, then there are two arrays in use. The word sized array of pointers pointed to by R1 and the 'real' object array. You can supply the address of this real array in R4 and the size of each object in it in R5. If this is done, then a number of optional actions can be performed. The top bits in R1 can be used as follows:

Bit Meaning
29 use R6 as workspace
30 build word-array of pointers pointed to by R1 from R4,R5
31 sort true objects pointed to by R4 after sorting the pointers

Bit 30 is used to build the pointer array pointed to by R1 using R4 and R5 before sorting is started. It will create an array of pointers, where the first pointer points to the first object, the second pointer to the second object and so on. After sorting, these pointers will be jumbled so that the first pointer points to the 'lowest' object and so on.

Bit 31 is used to sort the real objects pointed to by R4 into the order described by the pointers in the array pointed to by R1 after sorting is complete.

Note: That setting bit 30 also causes the bit 31 action to be taken. Thus if you wish to sort only the pointers and not the records to which they point, you must build the pointer array yourself, rather than setting bit 30 to have this call build it.

If the size in R5 is greater than 16 Kbytes or if bit 29 is set in R1, then a pointer to workspace must be passed in R6. This points to a block R5 bytes in length. One reason for setting bit 29 is that this SWI will otherwise corrupt the RISC OS scratch space.

Related SWIs

None

Related vectors

None


OS_Confirm
(SWI &59)

Get a yes or no answer

On entry

--

On exit

R0 = key that was pressed, in lowercase
the C flag is set if an escape condition occurred
the Z flag is set if the answer was Yes

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This SWI gets a yes or no answer from the user. If the mouse pointer is visible, then it changes it to a three button mouse shape. The left button indicates yes, while the other two indicate no. On the keyboard, a key appropriate to the territory indicates yes, and any other key indicates no.

You should always check whether the answer was yes or no by testing the Z flag, rather than the value returned in R0; this ensures that your program will not need modifying for use with different territories.

The result in R0 is returned in lowercase, irrespective of the keyboard state. It is made available should you need to reflect a character to the screen.

An escape condition will abort the SWI and return with the C flag set.

Related SWIs

None

Related vectors

None


OS_CRC
(SWI &5B)

Calculate the cyclic-redundancy check for a block of data

On entry

R0 = CRC continuation value, or zero to start
R1 = pointer to start of block
R2 = pointer to end of block
R3 = increment (in bytes)

On exit

R0 = CRC calculated
R1 - R3 preserved

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

This SWI calculates the cyclic-redundancy check value for a block of data. This is used to check for errors when, for example, a block of data is stored on a disk (although ADFS doesn't use this call) or is sent across a network and so on. If the CRC calculated when checking the block is different from the old one, then there are some errors in the data.

The block described in R1 and R2 is exclusive. That is, the calculation adds R3 to R1 each step until R1 equals R2. If they never become equal, then it will continue until crashing the machine. For example R1=100, R2=200, R3=3 will never match R1 with R2 and is not permitted.

The value of the increment in R3 is the unit that you wish to use for each step of the CRC calculation. Usually, it would be 1, 2 or 4 bytes, but any value is permitted. Note that the increment can be negative if you require it.

Related SWIs

None

Related vectors

None


IIC_Control
(SWI &240)

Control IIC devices

On entry

R0 = device address (bit 0 = 0 to write, bit 0 =1 to read)
R1 = pointer to block
R2 = length of block in bytes

On exit

R0 corrupted
R1 - R2 preserved

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call allows reading and writing to IIC devices. IIC is an internal serial protocol. It is used in RISC OS machines for writing to the clock chip and IIC compatible devices on expansion cards.

The possible error is 'No acknowledge from IIC device' (&20300).

Related SWIs

None

Related vectors

None

*Commands


*Configure Language

Sets the configured module that will be run as an application at power on

Syntax

*Configure Language module_no

Parameters

module_no - the number of the module which will be run as an application at power on. The default is the desktop.

Use

*Configure Language sets the configured module that will be run as an application at power on. The module is specified by its module number, as returned by the *Modules command. You should use that command to check the number you're configuring, especially if you have added or removed modules. You should also be aware that module numbers may differ between versions of RISC OS.

Note that the Desktop module checks on entry if a file - such as a boot file - is being run using *Exec, and if so exits. This means your machine will fail to enter the desktop if you've configured your machine both to use the desktop as its start up language, and to run a boot file at power-on using *Exec. The cure is either to select the desktop at the end of the boot file using the *Desktop command, or to configure the machine to boot from an Obey file.

The unusual use of the word 'language' in this command's name dates from earlier Acorn operating systems, and is preserved for backwards compatibility.

Example

*Configure Language 0 Starts up in Command Line mode, with * prompt

Related commands

*Configure Boot, *Desktop, *Modules, *Opt 4

Related SWIs

None

Related vectors

None


*Help

Gives brief information about each command

Syntax

*Help [keyword]

Parameters

keyword - the command name(s) to get help on

Use

*Help gives brief information about each command in the machine operating system, including its syntax. It also has help on some special keywords:

*Help Commands lists all the available utility commands
*Help FileCommands lists all the commands relating to filing systems
*Help Modules lists the names of all currently loaded modules, with their version numbers and creation dates
*Help Station displays the current network and station numbers of your machine
*Help Syntax explains the format used for syntax messages

The usual use of *Help is to confirm that a command is appropriate for the job required, and to check on its syntax (the number, type and ordering of parameters that the command requires). When you issue the *Help command at the normal Command Line prompt, 'paged mode' is switched on: the computer displays a screenful of text, then waits until you press Shift before moving on.

Example

The specification of the keyword can include abbreviations to allow groups of commands to be specified. For example:

*Help Con. produces information on *Configure and *Continue

*Help . gives help on all subjects

Related commands

None

Related SWIs

None

Related vectors

None

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015