BBC BASIC host interface summary
                             ================================

Registers holding parameters:
 A  - Action parameter in primary register,       eg 6502 A,  Z80 A,  PDP-11 R0, 80x86 AX
 HL - Address or parameter in secondary register, eg 6502 YX, Z80 HL, PDP-11 R1, 80x86 BX
 E  - Additional parameter in tertiary register,  eg          Z80 E,  PDP-11 R2

The absolute minimum that BASIC requires to get up and running is:
  OSASCI/OSWRCH - minimum of &0A, &0D, &20-&7F
  OSRDCH
  OSWORD 0
  OSBYTE &83,&84
Every other call can simply return with registers unchanged.


Housekeeping
~~~~~~~~~~~~
Initial PAGE           - OSBYTE &83    returns value in HL and A.b7=1 or AHL and A.b7=0
Initial HIMEM          - OSBYTE &84    returns value in HL and A.b7=1 or AHL and A.b7=0
Acknowledge Escape     - OSBYTE &7E

Some platforms will need additional actions to "register" as the current foreground application
and to claim errors, etc.

VDU actions
~~~~~~~~~~~
CLS                    - OSWRCH 12
CLG                    - OSWRCH 16
GCOL n                 - OSWRCH 18, 0, n
GCOL m,n               - OSWRCH 18, m, n
COLOUR n               - OSWRCH 17
COLOUR l,p             - OSWRCH 19, l, p, 0, 0, 0
COLOUR r,g,b           -
COLOUR l,r,g,b         - OSWRCH 19, l,16, r, g, b if l>=0
COLOUR l,r,g,b         - OSWRCH 19, l,24, r, g, b if l<0
COLOUR l,r,g,b,a       -
MODE n                 - OSWRCH 22, n
ON                     - OSWRCH 23, 1, 0, 0, 0, 0, 0, 0, 0, 0
OFF                    - OSWRCH 23, 1, 1, 0, 0, 0, 0, 0, 0, 0
DRAW x,y               - OSWRCH 25, 5, x AND 255, x DIV 256, y AND 255, y DIV 256
MOVE x,y               - OSWRCH 25, 4, x AND 255, x DIV 256, y AND 255, y DIV 256
PLOT x,y               - OSWRCH 25, 69,x AND 255, x DIV 256, y AND 255, y DIV 256
PLOT k,x,y             - OSWRCH 25, k, x AND 255, x DIV 256, y AND 255, y DIV 256
TAB(x,y)               - OSWRCH 31, x, y
VDU                    - OSWRCH arguments
Status messages        - OSASCI
numeric=GET            - OSRDCH                              returns byte in A, Cy=Escape
string=GET$            - OSRDCH                              returns byte in A, Cy=Escape
numeric=INKEY delay    - OSBYTE &81, HL=delay                returns value in HL, Cy=Escape
string=INKEY$ delay    - OSBYTE &81, HL=delay                returns value in L, Cy=Escape
numeric=POS            - OSBYTE &85                          returns byte in L
numeric=VPOS           - OSBYTE &85                          returns byte in H
numeric=MODE           - OSBYTE &87                          returns value in H
numeric=VDU offset     - OSBYTE &A0, HL=offset               returns word in HL
numeric=POINT(x,y)     - OSWORD 9, HL=>5-byte control block  returns sign-extended byte at (HL+4)

Later versions of BASIC add additional VDU commands which send sequences of VDU bytes.

ORIGIN x,y             - VDU 29, x AND 255, x DIV 256, y AND 255, y DIV 256
MOVE BY x,y            - PLOT 0,x,y
DRAW BY x,y            - PLOT 1,x,y
PLOT BY x,y            - PLOT 65,x,y

CIRCLE x,y,r           - MOVE x,y:PLOT 145,r,0
CIRCLE FILL x,y,r      - MOVE x,y:PLOT 153,r,0
ELLIPSE x,y,a,b        - MOVE x,y:PLOT 0,a,0:PLOT 193,0,b
ELLIPSE FILL           - MOVE x,y:PLOT 0,a,0:PLOT 201,0,b
FILL x,y               - PLOT 133,x,y
FILL BY x,y            - PLOT 129,x,y
LINE x1,y1,x2,y2       - MOVE x1,y1:DRAW x2,y2

RECTANGLE x,y,w        - MOVE x,y:PLOT 13,x+w,y:PLOT 13,x+w,y+w:PLOT 13,x,y+w:PLOT 13,x,y
RECTANGLE x,y,w,h      - MOVE x,y:PLOT 13,x+w,y:PLOT 13,x+w,y+h:PLOT 13,x,y+h:PLOT 13,x,y
RECTANGLE x1,y1,w   TO x2,y2      - MOVE x1,y1:MOVE x1+w,y1+w:PLOT 190,x2,y2
RECTANGLE x1,y1,w,h TO x2,y2      - MOVE x1,y1:MOVE x1+w,y1+h:PLOT 190,x2,y2
RECTANGLE FILL x,y,w              - MOVE x,y  :PLOT 101,x+w,y+w
RECTANGLE FILL x,y,w,h            - MOVE x,y  :PLOT 101,x+w,y+h
RECTANGLE FILL x1,y1,w   TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+w:PLOT 189,x2,y2
RECTANGLE FILL x1,y1,w,h TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+h:PLOT 189,x2,y2
RECTANGLE MOVE x1,y1,w   TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+w:PLOT 189,x2,y2
RECTANGLE MOVE x1,y1,w,h TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+h:PLOT 189,x2,y2
RECTANGLE SWAP x1,y1,w   TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+w:PLOT 191,x2,y2
RECTANGLE SWAP x1,y1,w,h TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+h:PLOT 191,x2,y2

TINT a,t                          - VDU 23,17,a,t,0,0,0,0,0,0
COLOUR c TINT t                   - VDU 17,c,  23,17,0+(c DIV 128),t,0,0,0,0,0,0
GCOL c TINT t                     - VDU 18,0,c,23,17,2+(c DIV 128),t,0,0,0,0,0,0
GCOL a,c TINT t                   - VDU 18,a,c,23,17,2+(c DIV 128),t,0,0,0,0,0,0
=TINT(x,y)                        - platform dependant


Filing actions
~~~~~~~~~~~~~~
CHAIN string           - OSBYTE &82, OSFILE A=&FF, HL=>control block
LOAD string            - OSBYTE &82, OSFILE A=&FF, HL=>control block
SAVE string            - OSBYTE &82, OSFILE A=&00, HL=>control block
BPUT#channel,byte      - OSPBUT A=byte, H=channel
INPUT#channel          - Multiple calls to OSBGET
PRINT#channel          - Multiple calls to OSBPUT
CLOSE#channel          - OSFIND &00, H=channel
OSCLI string           - OSCLI HL=>string
EXT#channel=numeric    - OSARGS &03, HL=>numeric, E=handle
PTR#channel=numeric    - OSARGS &01, HL=>numeric, E=handle
numeric=BGET#channel   - OSBGET H=channel                     returns A, Cy=EOF
numeric=EOF#handle     - OSBYTE &7F, L=handle                 returns L
                      or OSARGS &05, HL=>data, E=handle       returns data at HL
numeric=EXT#handle     - OSARGS &02, HL=>data, E=handle       returns data at HL
numeric=PTR#channel    - OSARGS &00, HL=>data, E=handle       returns data at HL
numeric=OPENIN string  - OSFIND &40, HL=>string               returns value in A
numeric=OPENOUT string - OSFIND &80, HL=>string               returns value in A
numeric=OPENUP string  - OSFIND &C0, HL=>string               returns value in A

Later versions of BASIC add the following filing commands and functions:

BPUT#channel,string    - repeated calls to BPUT#channel, followed by BPUT#channel,10
BPUT#channel,string;   - repeated calls to BPUT#channel, with nothing following.
string=GET$#channel    - multiple calls to BGET#channel until 10, 13 or EOF
numeric=OSCLI string   - OSCLI HL=>string                     returns value in A

Some platforms allow use of channel 0 to write to OSWRCH (eg the VDU) and read from OSRDCH
(eg the keyboard). Platforms with 32-bit or larger registers pass OSFILE and OSARGS data
directly in the registers. Other platforms point to the data in memory. For instance, on ARM:
  OSFILE R0=action, R1=>filename, R2,R3,R4,R5=control block contents
  OSARGS R0=action, R2=channel, R3=data


Sound actions
~~~~~~~~~~~~~
ENVELOPE env,p1,p2,p3,p4,p5,p6,p7,p8,p9,p10,p11,p12,p13
                        - OSWORD 8 with HL=>14-byte parameter block
SOUND chn,vol,pitch,dur - OSWORD 7 with HL=>8-byte parameter block
SOUND ON                - OSBYTE 210,0,0
SOUND OFF               - OSBYTE 210,255,0


Time & Date actions
~~~~~~~~~~~~~~~~~~~
TIME=numeric           - OSWORD &02, HL=>numeric
TIME$=string           - OSWORD &0F, HL=>LEN(string), HL+1=>string
numeric=TIME           - OSWORD &01, HL=>control block        returns data at HL
string=TIME$           - OSWORD &0E, HL=>0                    If HL=>0, null string returned
                                                              If HL=><>0, HL=>string

Other actions
~~~~~~~~~~~~~
CALL address           - Call MOS routine if &FF00-&FFFF
numeric=USR address    - Call MOS routine if &FF00-&FFFF      returns Cy:H:L:A
numeric=ADVAL channel  - OSBYTE &80, HL=channel               returns HL

A%=0:X%=nonzero:Z%=((USR&FFF4)AND&FF00)DIV256 should return a bitmap that reflects the
  filing system structure:
    %000x0xxx Filenames are directory.filename/extension, eg BBC, RISC OS
    %000x1xxx Filenames are directory/filename.extension, eg Unix, CP/M
    %nnnxxxxx Filenames are directory\filename.extension, eg DOS, Windows 

See BeebWiki for allocated numbers.