Next: drawf Prev: riscospath Up: RISCOS ONLY Top: Top

13.3. Built-in Module swi

This module provides access to the RiscOS SWI interface. It provides a function swi that puts suitable values in the arm registers, calls the SWI and extracts values from registers.

As many SWIs manipulate blocks of memory a new object type is provided for handling blocks of memory and inserting and extracting values from them.

Errors are reported as exceptions; the usual exceptions are given for type, index and value errors, while errors reported by X versions of the system calls raise swi.error, described below.

Module swi defines the following data item:

error -- exception of module swi
This exception is raised when an RiscOS X SWI returns a RiscOS-related error (e.g., not for illegal argument types). Its string value is 'swi.error'. The accompanying value is a string returned by the SWI.
It defines the following functions:

swi (name,descriptor,...) -- function of module swi
Calls the swi given by name with registers given by descriptor. name can either be an integer SWI number, or a string SWI name. SWI names are case dependent. To call the X version of the SWI you should set the X bit in the number, or preceed the name with X.

descriptor is a string that determines the registers to be passed and returned. Values to pass are taken sequentially from the remaining arguments, they are assigned to registers starting from r0. Characters of descriptor indicate how to pass values.

Character
Meaning --- Argument Type

`i'
pass an integer --- int
`s'
pass a pointer to a string --- string
`b'
pass a pointer to the start of a block --- block
`e'
pass a pointer after the end of a block --- block
`0-9'
insert 0-9 in the register --- -
`-'
insert in the register --- -
`.'
skip a register --- -
Note: Strings are read--only. If you want to alter a buffer passed to a SWI you must use a block.

If the descriptor contains a semi--colon, characters after this refer to values returned by registers. A single value is returned as an object. Several values are returned as a tuple.

Character
Meaning --- Output Type

`i'
return an integer --- int
`s'
return a string --- string
`*'
return the carry flag --- int
`.'
skip a register --- -
Example: wimp_initialise

block (size [, initializer]) -- function of module swi
Returns a new block of size words. The initializer must be a string or a list of integers. The initializer is truncated to fit the block. If it is too short it is padded with zeros. If there is no initializer the content of the block is undefined.
The memory of a block is guaranteed not to move unless the block is deleted or resized.

Blocks support index and slice operations as for lists of integers, except that the block cannot change size, so assignments are truncated or padded as for initialization. Slices beyond the end of the block give index errors.

register (size,address) -- function of module swi
Registers a prexisting memory block of size words as a block. Returns a new block. The memory supplied will not be freed when the block is deleted, or moved when it is resized.
Block items support the following data items and methods.

length -- data of module swi
The length of the block in bytes. Equal to 4*len(block).
start -- data of module swi
The start address of the memory block.
end -- data of module swi
The address after the end of the memory block.
padstring (string,padchar [,x,y]) -- function of module swi
The string is copied into the block between bytes x and y-1. The string is truncated or padded with padchar as required. x and y default to 0 and block.length.
tostring ([x,y]) -- function of module swi
The bytes between x and y-1 are returned as a string. x and y default to 0 and block.length.
nullstring ([x,y]) -- function of module swi
The bytes between x and y-1 are returned as a string, the string is terminated before the first null character if any. x and y default to 0 and block.length.
ctrlstring ([x,y]) -- function of module swi
The bytes between x and y-1 are returned as a string, the string is terminated before the first control character if any. x and y default to 0 and block.length.
bitset (i,x,y) -- function of module swi
b.bitset(x,y) is equivalent to @verb{b[i]=(b[i]&y)^x}.
resize (size) -- function of module swi
Changes the size of the block. The new size is in words. If the block was created using register this just changes the recorded end of the block. Otherwise the block may move, and the data in the block is truncated or zero padded as neccesary.