CALL
CALL is a BASIC statement to call (execute) a machine code routine in
memory or a BBC MOS API entry. The routine can be given access to certain
named BASIC variables, and may change their values. On most non-6502
platforms, BBC BASIC intercepts calls to the standard BBC MOS API entries
and translates them to an equivalent action.
| Availability | Present in all versions of BBC BASIC. |
| Syntax | CALL <numeric>{,<num-var>|<string-var>}
|
| Token (hex) | D6 (statement)
|
| Description | Sets up a structure in memory representing the given argument variables
(if any), sets certain CPU registers to the values of the resident integer variables, and jumps into a machine code routine at the address given in the <numeric>. The routine is permitted to read and write to the BASIC variables described in the table, and should exit with the normal subroutine return instruction. After the routine exits, BASIC continues executing the current program or command line. |
| Associated keywords | ?, !, $, USR
|
Description
CALL allows a BASIC program to use a piece of machine code
as part of its operation. Machine code is a program in the form of binary
data that can be run directly by the central processing unit (CPU).
CALL is one of the ways to access functions of the MOS (its
Application Programming Interface, or API.) Advanced programmers
can also use CALL to improve the performance of a BASIC program
by rewriting the most time-consuming parts in machine code, as it runs much,
much faster than the equivalent BASIC code.
Because CALL is involved with the low level architecture of the
computer, its precise function depends on which CPU is running BASIC:
6502 BASIC
BASIC sets up a data structure in its workspace, starting from location
&600. Apart from the <numeric> call address, this structure contains details
of all the variables listed after the CALL keyword, if any. The
routine may not change this structure, but can alter the variables it
references:
| Location | Meaning | |
|---|---|---|
| &600 | Number of variables | |
| &601..2 | First variable | Address |
| &603 | Type | |
| &604..5 | Second variable | Address |
| &606 | Type | |
| ... | ... | |
The Type byte may be one of the following:
| Type | Object at the given Address |
|---|---|
| &00 | An unsigned, 8-bit byte. |
| &04 | A signed, little-endian, 32-bit integer. |
| &05 | A 40-bit float in 6502 BASIC format. |
| &80 | A CR-terminated ASCII string. |
| &81 | A string descriptor block, consisting of: 1 × 16-bit address of the start of the string; |
Finally BASIC sets the state of the CPU as follows, and jumps into the user's routine:
| Register | Value |
|---|---|
| A | Set to the low 8 bits of A%.
|
| X | Set to the low 8 bits of X%.
|
| Y | Set to the low 8 bits of Y%.
|
| D | Reset to 0, meaning decimal mode is off. |
| I | Left in its current state. |
| C | Set to the lowest bit of C%.
|
| S | Points to the top of the 6502 stack (in use by BASIC.) On top of the stack is a return address (suitable for RTS) to continue with the current BASIC statement or program.
|
| PC | Set to the low 16 bits of the first, <numeric> argument to CALL.
|
| N,V,B,Z | Undefined. |
6809 BASIC
BASIC sets the state of the CPU as follows, and jumps into the user's routine:
| Register | Value |
|---|---|
| A | Set to the low 8 bits of A%.
|
| B | Set to the low 8 bits of B%.
|
| U | Set to the low 16 bits of U%.
|
| X | Set to the low 16 bits of X%.
|
| Y | Set to the low 16 bits of Y%.
|
| I | Left in its current state. |
| C | Set to the lowest bit of C%.
|
| S | Points to the top of the 6809 stack. On top of the stack is a return address (suitable for RTS) to continue with the current BASIC statement or program.
|
| PC | Set to the low 16 bits of the first, <numeric> argument to CALL.
|
| N,V,B,Z | Undefined. |
Z80 BASIC
BASIC sets up a data structure in the string buffer pointed to by IX. Apart
from the <numeric> call address, this structure contains details of all the
variables listed after the CALL keyword, if any. The routine
may not change this structure, but can alter the variables it references:
| Location | Meaning | |
|---|---|---|
| IX+0 | Number of variables | |
| IX+1 | First variable | Type |
| IX+2..3 | Address | |
| IX+4 | Second variable | Type |
| IX+5..6 | Address | |
| ... | ... | |
The Type byte may be one of the following:
| Type | Object at the given Address |
|---|---|
| &00 | An unsigned, 8-bit byte, eg ?X. |
| &04 | A signed, little-endian, 32-bit integer, eg !X or X%. |
| &05 | A 40-bit float, eg V. |
| &80 | A CR-terminated ASCII string, eg $X. |
| &81 | A string variable, eg A$. The address points to a String Descriptor Block, consisting of: 1 × 16-bit address of the start of the string; |
Finally BASIC sets the state of the CPU as follows, and jumps into the user's routine:
| Register | Value |
|---|---|
| A | Set to the low 8 bits of A%.
|
| F | Set to the low 8 bits of F%.
|
| B | Set to the low 8 bits of B%.
|
| C | Set to the low 8 bits of C%.
|
| D | Set to the low 8 bits of D%.
|
| E | Set to the low 8 bits of E%.
|
| H | Set to the low 8 bits of H%.
|
| L | Set to the low 8 bits of L%.
|
| IX | Set to address of parameter block. |
| IY | Set to address of machine code routine (=PC). |
| SP | Points to a return address on the Z80 stack (suitable for RET) to continue with the current BASIC statement or program.
|
If the call address is in the range &FF00 to &FFFF, and there is no parameter block passed, the CPU registers are set as follows:
| Register | Value |
|---|---|
| A | Set to the low 8 bits of A%.
|
| E | Set to the low 8 bits of E%.
|
| H | Set to the low 8 bits of Y%.
|
| L | Set to the low 8 bits of X%.
|
| IY | Set to address of machine code routine (=PC). |
| SP | Points to a return address on the Z80 stack (suitable for RET) to continue with the current BASIC statement or program.
|
In Z80 BASIC the string buffer is in different locations in different versions. Consequently, the only way for code such as Tokeniser can find the string buffer is to call some machine code and return the value in IX with:
PUSH IX POP HL EXX RET
32000 BASIC
BASIC sets up a data structure in the string buffer pointed to by R1 and R2
holding the number of parameters. Apart from the <numeric> call address,
this structure contains details of all the variables listed after the
CALL keyword, if any. The routine may not change this
structure, but can alter the variables it references:
| Location | Meaning | |
|---|---|---|
| R1+0..3 | First variable | Address |
| R1+4 | Type | |
| R1+5..8 | Second variable | Address |
| R1+9 | Type | |
| ... | ... | |
The Type byte may be one of the following:
| Type | Object at the given Address |
|---|---|
| &00 | An unsigned, 8-bit byte, eg ?X. |
| &01 | A signed, little-endian, 32-bit integer, eg !X or X%. |
| &02 | A 40-bit float, eg V. |
| &03 | A string variable, eg A$. The address points to a String Descriptor Block. |
| &04 | A CR-terminated ASCII string, eg $X. |
32016 BASIC does not pass the integer variables to the called code. If not calling a BBC MOS API, the state of the CPU is set as follows:
| Register | Value |
|---|---|
| R1 | Address of parameter block. |
| R2 | Number of parameters. |
| R3 | undefined. |
| R4 | undefined. |
| R5 | undefined. |
| R6 | undefined. |
| R7 | undefined. |
| SP | Points to a return address on the user stack (suitable for RET) to continue with the current BASIC statement or program.
|
If the call address is in the range &FF00 to &FFFF, and there is no parameter block passed, the CPU registers are set as follows:
| Register | Value |
|---|---|
| R1 | Set to the low 8 bits of A%.
|
| R2 | Set to all 32 bits of X%.
|
| R3 | Set to the low 8 bits of Y%.
|
| SP | Points to a return address on the user stack (suitable for RET)
to continue with the current BASIC statement or program. |
From examination of code, it appears that CALL to a non-API address with no parameters
erroneously jumps to the parameter buffer instead of to the destination address. To force
a correct call at least one parameter must be passed, eg CALL dest,A%.
ARM BASIC
BASIC sets up a data structure in the stack, passing to the routine its
location in R9, and the number of records in R10. Apart from the <numeric>
call address, this structure contains details of all the variables listed
after the CALL keyword, if any. The routine may not change this
structure, but can alter the variables it references:
| Location | Meaning | |
|---|---|---|
| R9 + 0..3 | Last variable | Address |
| R9 + 4..7 | Type | |
| R9 + 8..11 | Second-to-last variable | Address |
| R9 + 12..15 | Type | |
| ... | ... | |
The Type value may be one of the following:
| Type | Object at the given Address (unaligned) |
|---|---|
| &00 | An unsigned, 8-bit byte. |
| &04 | A signed, little-endian, 32-bit integer. |
| &05 | A 40-bit float in 6502 BASIC format. |
| &08 | A 64-bit float in BASIC V format. |
| &80 | A CR-terminated ASCII string. |
| &81 | A string descriptor block, consisting of: 1 × 32-bit address of the start of the string; |
Finally BASIC sets the state of the CPU as follows, and jumps into the user's routine:
| Register | Value |
|---|---|
| R0..R7 | Set to the resident integer variables.
R0=A%, R1=B%, R2=C%, R3=D%, R4=E%, R5=F%, R6=G%, R7=H%. |
| R8 | Set to ARGP, a pointer to the BASIC workspace. |
| R9 | Points to a structure representing the variables following the <numeric> (if any). |
| R10 | Set to the number of variables following the <numeric>. |
| R11 | Points to 256 bytes of workspace, used by BASIC to receive text input and compute strings. |
| R12 | Points to within a few bytes of the CALL or USR token that called this routine.
|
| R13 | The stack pointer. Points to the top of the BASIC stack (FD type.) |
| R14 | The link register. Contains a return address (suitable for copying to R15) to continue with the current BASIC statement or program. At the return address is a B instruction to jump into BASIC proper, followed by a list of offsets to internal BASIC variables (to be added to ARGP in R8), and B instructions to jump to BASIC routines. In this way the variables and routines are made officially available to the user's machine code routine.
|
| R15 | The program counter. Set to the first, <numeric> argument to CALL.
|
BBC MOS API Access
To ensure cross-platform compatibility, most non-6502 implementations of BBC
BASIC translate CALLs to MOS API entries to an equivalent call
to the underlying MOS. The only address that are supported by this are those
listed below. The values in A%, X% and Y%, or the data or control block
pointed to by X%, are passed in an appropriate manner to the underlying
system.
| Address | MOS call | Action |
|---|---|---|
| &FFF7 | OSCLI | Execute *command. |
| &FFF4 | OSBYTE | Various byte-wide functions. |
| &FFF1 | OSWORD | Various control block functions. |
| &FFEE | OSWRCH | Write character to output stream. |
| &FFE7 | OSNEWL | Write NewLine to output stream. |
| &FFE3 | OSASCI | Write character or NewLine to output stream. |
| &FFE0 | OSRDCH | Wait for character from input stream. |
| &FFDD | OSFILE | Perform actions on whole files or directories. |
| &FFDA | OSARGS | Read and write information on open files or filing systems. |
| &FFD7 | OSBGET | Read a byte from an a channel. |
| &FFD4 | OSBPUT | Write a byte to a channel. |
| &FFD1 | OSGBPB | Read and write blocks of data. |
| &FFCE | OSFIND | Open or close a file. |
Register usage
| CPU | Registers on entry | Result returned by USR |
|---|---|---|
| 6502 | A=A%, X=X%, Y=Y%, Cy=b0 of C% | b0-7=A b8-15=X b16-23=Y b24-31=P |
| 6809 | A=A%, B=B%, U=U%, X=X%, Y=Y%, Cy=b0 of C% | b0-7=A, b8-15=X b16-23=Y, b24-31=CC |
| Z80 | A=A%, B=B%, C=C%, D=D%, E=E%, H=H%, L=L% | b0-b15=HL' b16-b31=HL |
| Z80 BBC API call |
A=A%, L=X%, H=H%, E=E% | b0-b7=A b8-b23=HL b24-31=F |
| 32000 | R1=A%, R2=B%, R3=C%, R4=D%, R5=E%, R6=F%, R7=G% | b0-b31=R1 |
| 32000 BBC API call |
R1=A%, R2=X%, R3..R7=contents of control block at X% |
b0-b7=R1 b8-b23=R2 |
| PDP-11 | R0=A%, R1=B%, R2=C%, R3=D%, R4=E%, R5=F% | b0-b15=R0 b16-b31=R1 |
| PDP-11 BBC API call |
R0=A%, R1=X%, R2=Y% | b0-b7=R0 b8-b23=R1 |
| ARM | R0=A%, R1=B%, R2=C%, R3=D%, R4=E%, R5=F%, R6=G%, R7=H% |
b0-b31=R0 |
| ARM BBC API call |
R0=A%, R1=X%, R2=Y%, or R1..R5=contents of control block at X% |
b0-b7=R0 b8-b31=R1 |
When passing the address of a data structure or control block, code similar to the following should be used.
DIM ctrl% 31 :REM Control block, may be anywhere in 32-bit memory space X% = ctrl% :REM X% holds full 32-bit address Y% = X% DIV 256 :REM Y% holds 32-bit address, shifted right 8 bits
On 8-bit platforms the high 24 bits of X% and Y% are ignored, and the control block is found with X%+256*Y%. On platforms with larger registers, the control block is found at X%, ignoring Y% completely. Some platforms will check if X%<256 and use X%+256*Y%, though this should not be relied on.
An additional advantage is that the control block is easily accessed with X%, for example, X%!2=load%, etc.
Notes
32000 passes A%=R1, etc., not R0.
When calling &FFCE with A%=0 to close a file, 6502 BASIC requires the
channel to be passed in Y% but in ARM BASIC the channel must be passed in
X%. When calling from BASIC, the CLOSE# statement
should be used.
References
- BBC BASIC RISC OS 3 Programmer's Reference Manual: BBC BASIC (PDF)
- Usenet post Roger Wilson's Usenet post of changes in BASIC V 1.04
-- beardo 22:50, 25 June 2007 (BST)
