SWIs in Matrix Brandy
=====================

A number of SWIs are supported in Matrix Brandy, most of which are emulations
of the equivalent RISC OS SWIs.  Where a RISC OS SWI is emulated, the SWI
number used is the same as that used by RISC OS, in order to allow code
that uses the number rather than the name for performance reasons to run
correctly.

In this document, the parameters listed are labelled as ARM registers as
if the SWI were called in RISC OS.

Where a parameter returns a pointer to a string, it MUST be picked up with a
string variable; picking it up with a numeric variable and attempting to
access the buffer will not work, due to Brandy's memory offsetting.

OS_xxx
======
OS_WriteC		R0: Send (R0 AND &FF) to the VDU stream.
			Matrix Brandy extension:
			   If R1 and R2 are both set to 42, the character is
			   output to the controlling terminal on the stderr
			   stream.

OS_Write0:		R0: Pointer to NULL-terminated string, to be sent to
			    the VDU stream.
			Matrix Brandy extension:
			   If R1 and R2 are both set to 42, the string is
			   output to the controlling terminal on the stderr
			   stream.

OS_NewLine		Sends \r\n (&0D, &0A) to the VDU stream.

OS_ReadC		Reads a character from the keyboard, returned in R0.

OS_ReadLine and

OS_ReadLine32		Returns a string input from the keyboard, pointed in R0.

OS_Mouse		Returns mouse state.

OS_ReadModeVariable	Read a mode variable into R2.

OS_ReadVduVariables	Read VDU variables requested in block pointed in R0
			into block pointed in R1. R0 and R1 may point to the
			same block.

OS_ReadMonotonicTime	Return centisecond timer in R0.

OS_Plot			Executes a PLOT function. Note that this bypasses the
			VDU driver so plotting this way will not be picked up
			by *SPOOL.

OS_ScreenMode		Only R0=0,1,7,8,9,10 are supported.

OS_WriteI block		(SWIs 256-511). Call by number.
			Matrix Brandy extension:
			   If R1 and R2 are both set to 42, the character is
			   output to the controlling terminal on the stderr
			   stream.

ColourTrans_xxx
===============
ColourTrans_SetGCOL
ColourTrans_GCOLToColourNumber
ColourTrans_ColourNumberToGCOL
ColourTrans_SetTextColour


BRANDY-SPECIFIC CALLS
=====================
Brandy_xxx  (SWI numbers start &140000)

&140000 Brandy_Version		Returns:
				R0: Major version number
				R1: Minor version number
				R2: Patchlevel number
				R3: Git commit SHA (if available)
				R4: Pointer to host OS name string
				R5: 1 if SDL build, otherwise 0.

&140001 Brandy_Swap16Palette	Returns nothing.
				In 16-colour modes, as Flash isn't supported,
				this swaps the dimmed colours at 8-15 with the
				standard brightness at 0-7. Calling again
				switches back. Some other BBC BASIC versions
				use 0-7 as dimmed colours.

&140002 Brandy_GetVideoDriver	Returns:
				R0: Pointer to SDL video driver name string
				R1: Length of string in R0
				R2: Offset pointer to screen memory base
				R3: Size of screen memory.
				R4: Base of MODE 7 frame buffer

&140003 Brandy_SetFailoverMode	R0: Set mode to be selected should chosen screen
				    mode be unavailable (instead of returning
				    "Screen mode is unavailable). Set to 255 to
				    disable.

&140004 Brandy_AccessVideoRAM	If R0=0, return pixel value at pixel offset R1
				   into R2.
				If R0 non-zero, write R2 into pixel offset R1.
				R1 is pixel offset, so each step of 1 is the
				   next pixel irrespective of screen mode.
				Note this writes directly to the 24bpp frame
				buffer so bypasses any screen mode palette or
				colour depth limit. The top 8 bits, which are
				ignored by SDL, are used to carry the logical
				colour number in paletted modes to support
				VDU19 palette changing.

&140005 Brandy_INTusesFloat	This enables a BB4W/BBCSDL extension that allows
				INT() to handle numbers > 2^31-1 by using a
				float if the number is out of range for a 32-bit
				signed integer.
				R0=1 to enable, 0 to disable. Default: disabled.

&140006 Brandy_LegacyIntMaths	This allows integer mathematics to be handled in
				the way BBC BASIC 1 to 4 on the Acorn 8-bit
				machines, and RISC OS ARM BBC BASIC V,
				including the rather questionable wrap-around
				on integers. RISC OS ARM BBC BASIC VI, BB4W
				and BBCSDL do not have this wrap-around issue
				and will promote to float when needed.
				R0=1 to enable, 0 to disable. Default: disabled.


RaspberryPi_xxx (SWI numbers start &140100)
 -- see also docs/raspi-gpio.txt

&140100 RaspberryPi_GPIOInfo	Returns:
				R0: 1 if available, 0 otherwise
				R1: If available, memory-mapped I/O base.

&140101 RaspberryPi_GetGPIOPortMode
				R0 contains GPIO port number
				Returns:
				R0 contains GPIO port mode:
					0: Input
					1: Output
					2: ALT5
					3: ALT4
					4: ALT0
					5: ALT1
					6: ALT2
					7: ALT3


&140102 RaspberryPi_SetGPIOPortMode
				R0 contains GPIO port number
				R1 contains GPIO port mode (as above).

&140103 RaspberryPi_SetGPIOPortPullUpDownMode
				R0 contains GPIO port number
				R1 contains GPIO Pull-Up/Pull-Down mode:
					0: Off
					1: Down
					2: Up

&140104 RaspberryPi_ReadGPIOPort
				R0 contains GPIO port number
				Returns:
				R0 contains GPIO port state

&140105 RaspberryPi_WriteGPIOPort
				R0 contains GPIO port number
				R1 contains GPIO port state

A few of the RISC OS GPIO module (SWI base &58F80) are also recognised:
&58FBE GPIO_GetBoard
  Returns board model code local to the module in R0,
  the board type string in R1
  and additionally, local to Brandy, the 32-bit model code from /proc/cpuinfo
  into R2.
&58F80 GPIO_ReadData: mapped to RaspberryPi_ReadGPIOPort
&58F81 GPIO_WriteData: mapped to RaspberryPi_WriteGPIOPort
&58F8F GPIO_ReadMode: mapped to RaspberryPi_GetGPIOPortMode
&58F90 GPIO_WriteMode: mapped to RaspberryPi_SetGPIOPortMode

