|
www.riscos.com Technical Support: |
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 |
R0 = 0
R1 = 0 to display OS version string, or 1 to return machine type
R0 preserved
R1 = machine type if R1 = 1 on entry
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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.
None
ByteV
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)
R0 - R6 preserved
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
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.
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 |
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.
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.
None
--
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 are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
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.
None
R0 = CRC continuation value, or zero to start
R1 = pointer to start of block
R2 = pointer to end of block
R3 = increment (in bytes)
R0 = CRC calculated
R1 - R3 preserved
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
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.
None
R0 = device address (bit 0 = 0 to write, bit 0 =1 to read)
R1 = pointer to block
R2 = length of block in bytes
R0 corrupted
R1 - R2 preserved
Interrupts are disabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
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).
None
None
Sets the configured module that will be run as an application at power on
*Configure Language module_no
module_no - the number of the module which will be run as an application at power on. The default is the desktop.
*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.
*Configure Language 0 Starts up in Command Line mode, with * prompt
*Configure Boot, *Desktop, *Modules, *Opt 4
None
None
*Help [keyword]
keyword - the command name(s) to get help on
*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.
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
None
None
None