What do you need to run BBC BASIC?
I have put together this information to give some guidance and help on using
BBC BASIC (80) converted for the Sinclair Spectrum on other similar
platforms. This was originally written to cover porting BBC BASIC (80) to
Spectrum-like platforms, such as the Spectrum SE and Sprinter, but the same
information is relevant to using this conversion of BBC BASIC (80) on any
Z80-based platform.
The small host source at BBCBasic can be used as a demonstration and a
source of ideas.
This describes the minimum requirements. An ideal full environment is
described here.
Code image
----------
The interpreter resides in memory from &0100 to &34FF. It should be entered
at &0100 to start. Registers do not need to be set to anything on entry, but
the interpreter looks at &FF86 for the address of any command tail
specifying a program to load and run. All registers, including the
alternative registers, are used. If any system or interupt routines claim
certain registers for their own use, verneers will have to built around
them.
Memory usage
------------
The interpreter uses absolute workspace at &F000-&F2FF. Memory is also used
at &F3CE-&F3DF to pass control blocks to and from the host. This control
block memory is not used at any other time.
BBC BASIC uses memory between the inital PAGE and HIMEM to store the program
and variables. PAGE and HIMEM are initialised with calls to OSBYTE.
Host interface
--------------
BBC BASIC interfaces with the host by calling, examining and setting memory
at &FFxx. This is a subset of the Acorn Z80Tube host interface as described
in mdfs.net/Docs/Comp/Z80Tube/MOSEntries.
&FF80 ESCFLG Escape flag
The host should set bit7 when in Escape state.
&FF82 FAULT FAULT address
When the host generates an error it should set this to point to an
error block, then jump to the address in BRKV. An error block is:
DEFB error number
DEFM error string
DEFB &00 ; error string terminator
If possible, you should also allow RST &38 to be used to generate an
error. The RST &38 code should do:
POP HL:LD (&FF82),HL:LD HL,(&FFFA):JP (HL)
&FF86 CMDPTR Command line tail
The host should set this to point to a CR-terminated string of any
file to run on starting BBC BASIC when BBC BASIC is entered at &0100.
&FFCE OSFIND Open or close a file
If A=0, H=file handle to close
If A=&4x, HL=>filename to open for input, return handle in A
If A=&8x, HL=>filename to open for output, return handle in A
If A=&Cx, HL=>filename to open for update, return handle in A
&FFD1 OSGBPB Multiple byte file access
&FFD4 OSBPUT Put a byte to a file
H=file handle, A=byte to output
&FFD7 OSBGET Get a byte from a file
H=file handle. Return byte in A, Cy=1 if EOF met.
&FFDA OSARGS Read or set file arguments
A=0/1, E<>0 Read/Write PTR of channel in E, value in memory at HL+0-3
A=2/3, E<>0 Read/Write EXT of channel in E, value in memory at HL+0-3
A=0, E=0 Read current filing system, returned in A
A=1, E=0 Read address of command line tail to HL+0-3
&FFDD OSFILE Load or save file, HL+0/1=>filename
A=0 Save file:
HL+2-5=>start, HL+6-9=>end+1, HL+10-13=>execute, HL+14-17=load
A=&FF Load file:
HL+2-5=>start, HL+6=0 to load to HL+2-5, HL+6<>0 to ignore HL+2/5
The control block at HL should be updated with the file's information
after loading or saving. Specifically, BBC BASIC expects the length field
at HL+10-13 to be set.
&FFE0 OSRDCH Input a character
Wait for a keypress, returning it in A, with Cy set if an Escape state set.
&FFE3 OSASCI Print a character, with CR converted to LF,CR
&FFE7 OSNEWL Print a LF,CR sequence
&FFEE OSWRCH Print a character
Send the character in A to the current output stream.
&FFF1 OSWORD Do an OSWORD call, HL=>control block
A=0 Read a line of text, HL+0/1=address to store text
A=1/2 Read/Write TIME
A=7 SOUND
A=8 ENVELOPE
A=9 POINT
A=14/15 Read/Write TIME$
&FFF4 OSBYTE Do an OSBYTE call
A=0 Read host. Return L=&1F for Spectrum.
A=&7C Clear Escape state with no side-effects.
A=&7D Set Escape state.
A=&7E Acknowlede Escape state with side effects.
A=&7F Read EOF on channel in L. Return L=0 for false, L=&FF for true.
A=&80 HL=ADVAL(HL).
A=&81 HL=INKEY(HL), Cy=Escape state
If HL<&8000, wait up to HL centiseconds for a keypress.
If key pressed, H=&00, L=key
If no key pressed, HL=&FFFF
If HL>&FF00, scan for keypress.
If key pressed, HL=&FFFF, else HL=&0000
The scan should use the BBC keyboard map as closely as possible.
If HL=&FF00, return hardware type. Return HL=&00E0 for Spectrum.
A=&82 Machine high order address. HL should return &0000.
A=&83 HL=lowest available memory address, used to initialise PAGE
A=&84 HL=highest available memory address, used to initialise HIMEM
A=&85
A=&86 Return H=VPOS, L=POS
A=&87 Return H=MODE, L=character on screen at cursor position
&FFF7 OSCLI Interpret a command
Execute the command in the CR-terminated string at HL. Any leading '*'s
and spaces should be skipped. Errors should return via BRKV with an
error block pointed to. A useful minimum set of commands would be
*QUIT to return to calling process and *BASIC (filename) to enter
BBC BASIC.
&FFFA BRKV FAULT vector
The host should jump to this address when a host error occurs.
VDU
---
The screen/vdu is controlled by writing characters to OSWRCH at &FFEE.
BBC BASIC sends the following character sequences:
10 Line feed Move down one line without changing the column.
12 CLS Clear screen.
13 Carriage return Move to column 0 of the current line.
16 CLG Clear graphics window.
17,n COLOUR n Set text colour, foreground if n<&80,
background if n>&7F.
18,a,c GCOL a,c Set graphics colour.
19,l,p,r,g,b COLOUR l,p or COLOUR l,r,g,b
Set palette mapping.
22,n MODE n Set screen mode and clear screen to initial state.
25,k,x1,x2,y1,y2 PLOT/MOVE/DRAW k=4 - MOVE to x,y
k=5 - DRAW to x,y
k=69 - PLOT at x,y
31,x,y TAB(x,y). Move text cursor to x,y.
Colours should be based on RGB values, rather than the GBR values native to
the Spectrum. Graphics commands should see the screen as a portal 1280
pixels wide and 1024 pixels high, and should scale coordinates to fit the
screen.
I have also used COLOUR &C0+n to set the border, as in the VDUEcho program.
Strictly speaking, this should be set via 19,l,p,r,g,b.
Filesystem
----------
BBC BASIC does not impose any expectations on the file system used to access
files. BBC BASIC just passes a filename or handle to the host and expects
the host to do the requested action.
The host I have been developing uses the HiSoft filename convention:
[d:]filename, where d can be 'T' for tape or '1' to '8' for microdrives 1 to
8. When [d:] is ommited, the current device is used.
For example, "T:tapefile", "1:mdrivefile", "afile".
Host implementations should use:
':' to specify a drive,
'/' to specify a drive's root,
'/' to separate directories,
'.' to separate optional extensions.
For example, "T:tapefile", "A:/folder/file", "net:/home/files/test1.html".
The host should provide a *D: command to specify the current drive/device,
for example:
*T:
SAVE "FRED"
would save "FRED" to tape.
Copyright
---------
Documentation MUST include the following:
"The [platform] version of BBC BASIC (Z80) is made available for free
download on the condition that it always be distributed with the above
files. BBC BASIC (Z80) and the accompanying files remain the Copyright (C)
of R.T.Russell, 1982-2000. Please see http://www.rtrussell.co.uk/"
The conversion should include the demonstration files in BBCTube.zip.
I am working on tweeking them to be more suitable for distributing with a
Spectrum conversion.
Hosted by Force9 Internet
- Authored by J.G.Harston
- Last update: 12-Nov-2003