SYS calls in Matrix Brandy
==========================

On RISC OS builds, all host SWIs are available. Additionally, the Brandy-
specific calls which are implemented by Matrix Brandy are also recognised
and are available for use.

A number of SYS calls are supported in Matrix Brandy, some 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.

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_ReadPalette          Read the colour palette. Only R1=16 supported.

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.
                        Matrix Brandy extension:
                           As the centisecond timer is centiseconds since the
                           start of the instance, the offset from the raw
                           value is returned in R1.

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_SWINumberToString    Returns SWI string from number.
                        On RISC OS this is NOT intercepted so it does not
                        recognise Brandy-specific calls.

OS_SWINumberFromString  Returns SWI number from name.
                        On RISC OS this call is intercepted so we can also
                        recognise Brandy-specific calls.

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.

OS_Byte                 R0, R1, R2 are A, X and Y.
                        Calls the OSBYTE system call, see docs/osbyte.txt

OS_Word                 R0 is A, R1 is the address of the data block.
                        Only R0=9, 10, 139, 140 are supported.
                        139 and 140 are specific to Matrix Brandy and
                        BBCSDL. Details in docs/Mode7.txt

OS_File                 Calls 0, 6, 7, 8, 12, 14, 16, 19, 24 and 255 only.
                        Calls 12, 14, 16 and 255 are identical (for now).
                        Implementation is incomplete.

OS_SetColour            Implemented mostly, apart from calls relating to
                        ECF (which Matrix Brandy does not support), and
                        the call to read the colour, as this is undocumented
                        in RISC OS aside from its existence.

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.
                                R6: Returns a fixed 64-bit value on 64-bit
                                    hardware (truncated on 32-bit):
                                    &123456789ABCDEF0
                                R7: 1 if 64-bit 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: Pointer to screen memory base
                                R3: Size of screen memory.
                                R4: Base of MODE 7 frame buffer
                                R5: SDL surface handle (pointer)
                                R6: Pointer to SDL_PixelFormat structure of
                                    the display surface.
                                R7: OS-native window handle

&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.

&140007 Brandy_Hex64            This controls whether Brandy renders and
                                interprets Base 16 (Hexadecimal) values as
                                64-bit.
                                R0=1 to enable, 0 to disable.
                                Default: disabled.

&140008 Brandy_DELisBS          Toggles whether the DEL key functions as
                                backspace (DELETE in old BBC terminology).
                                R0=1 to enable, 0 to disable.
                                Default: Enabled on UNIX text-mode builds,
                                         Disabled otherwise.

&140009 Brandy_PseudovarsUnsigned
                                Only effective on 32-bit hardware. Toggles
                                whether memory pseudo-variables (e.g. PAGE,
                                HIMEM etc) return large positive numbers
                                above &7FFFFFFF.
                                R0=1 to enable, 0 to disable.
                                Default: disabled.

&14000A Brandy_TekEnabled       Only effective on the 'tbrandy' build,
                                ignored without error on other builds.
                                This switch enables Tektronix graphics to
                                be generated for graphics operations, with
                                particular reference to the Tek emulation
                                in xterm.
                                R0=1 to enable, 0 to disable.
                                Default: disabled
                                R1=simulated baud rate, 0 to run at full
                                speed.

&14000B Brandy_uSleep           Calls the OS function usleep(R0).

&14000C Brandy_dlopen           Calls the OS function
                                dlopen(R0,RTLD_NOW|RTLD_GLOBAL).
                                Handle is returned in R0.

&14000D Brandy_dlcall           Locates the symbol in R0, and calls it with
                                parameters from R1..R9.

&14000E Brandy_MAlloc           Allocates memory from system call
                                malloc(R0).
                                Pointer to base returned in R0.
                                DEPRECATED, please use DIM HIMEM instead.

&14000F Brandy_Free             Frees memory pointed to in R0 from earlier
                                malloc. Nothing returned.
                                DEPRECATED, please use DIM HIMEM <var> -1
                                instead.

&140010 Brandy_BitShift64       This controls whether Brandy calculates bit
                                shifts in 64-bit space. 32-bit space is used
                                when disabled as per ARM BBC BASIC VI.
                                R0=1 to enable, 0 to disable.
                                Default: disabled.

&140011 Brandy_Platform         Similar to Brandy_Version, but more focused
                                on the platform Brandy is running on.
                                R0: Pointer to host OS name string
                                R1: Pointer to CPU family string
                                R2: 64-bit? (1 or 0)
                                R3: SDL build? (1 or 0)
                                R4: Machine type (as returned by OSBYTE 0)
                                R5: "Legacy" INKEY-256 (e.g. &F9 for Linux)
                                R6: The PID of the current process.
                                R7: The Parent PID of the current process.
                                    Note: PPID not returned on Windows.

&140012 Brandy_CascadedIFtweak  Change behaviour of cascaded IF calls to try
                                to match the behaviour of Richard Russell's
                                BBC BASICs. Enabled by default, but can be
                                disabled to match the Acorn behaviour.
                                As this affects the parser and tokeniser, if
                                the block of code has been seen before this
                                call, then the behaviour won't be changed.
                                If used, it is recommended this be called at
                                the top of a program as it affects the way
                                the tokeniser updates jumps as the program
                                is scanned upon first execute..

&140013 Brandy_MouseEventExpire Sets the mouse event expiry time in
                                centiseonds, 0 disables.
                                With a zero event expiry time, a maximum
                                event queue length is used (7 events) which
                                mirrors RISC OS behaviour.

&140014 Brandy_dlgetaddr        Fetches the address of the library function
                                call given in R0, with the library handle
                                from Brandy_dlopen optionally provided in R1,
                                and returns the address in R0. If the symbol
                                isn't found and the X flag  is set, R0
                                contains -1, else an error is raised.

&140015 Brandy_dlcalladdr       Similar to Brandy_dlcall (above), but takes
                                the address of the symbol in R0 instead of
                                the symbol name.

&140016 Brandy_Strict           Enable/disable strict execution mode (as
                                also set by command-line -strict/-ignore
                                options).
                                Default: Disabled if built with
                                DEFAULT_IGNORE otherwise enabled.

&140017 Brandy_TranslateFNames  Enable/disable transparent translation of
                                filenames between Linux and RISC OS formats.
                                R0=0: No translation happens.
                                R0=1: Autodetect on read, translate on write
                                      (OPENUP follows read behaviour)
                                R0=2: Autodetect on read, no translation on
                                      write, but if translation required on
                                      read this value is changed to 1.
                                Any other value is ignored.
                                Return: R0 contains old value.
                                Default value: 2

&140018 Brandy_MemSet           Writes a value to a block of memory.
                                This call fills the first R1 bytes of the
                                memory area pointed to by R0 with the
                                constant byte R2.
                                This calls memset(R0, R2, R1).

&140019 Brandy_AllowLowercase   This sets whether or not Brandy accepts
                                keywords in lowercase. This may also be set
                                using the '-lck' command line option or the
                                'lowercase' config file option.
                                Default: R0=0 (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

