13.3. Built-in Module swi

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.

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

>>> from swi import *

>>> msgs=block(2,[0x600c0,0])

>>> pname="myprog"

>>> wimpver,taskhand=swi(0x600c0,"iisb;ii",310,0x4b534154,pname,msgs)

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.

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.

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.