pre-release 0.2 Edited By Dr Phibes
STOS Manual: APPENDIX D
Using Assembly Language
CALL
address Allows a machine code program at address, which can also refer
to a memory bank number, to be executed.
Calling A Machine Code Program
-
Reserve some memory for the routine using: RESERVE AS DATA.
-
load the program using the line: load"filename.prg",address[bank]
-
Pass any input parameters using the pseudo variables AREG(0-6) and DREG(0-7)
-
Call the program using a line like: CALL address[bank]
Your assembly language program may subsequently change any 68000 registers
with the sole exception of A7, and must terminate with an RTS instruction.
It must NEVER call the Gemdos traps SET BLOCK, MALLOC, MFREE, KEEP PROCESS
or any other memory management function.
Machine Code Control Instructions
AREG(r)
An array of six pseudo variables used to hold a copy of the 68000's address
registers. r may range from 0-6 and indicates the number of the address
register which is stored in the variable.
DREG(r)
An array of seven pseudo variables used to hold a copy of the 68000's data
registers. r may range from 0-7 and indicates the number of the data register
which is stored in the variable.Whenever the CALL or TRAP functions are
called, the above variables are copied into the appropriate registers,
and on return to basic, the current values of the registers are transferred
into the variables.
TRAP n[,parameters]
Allows a call to be made to one of the TRAP functions.n refers to the TRAP
number and may range from 0 to 15.n=0,1,13,14 (The Gemdos functions)n=3,5,6,7
(The Stos functions)The optional parameters specify the data which is to
be placed on the 68000's stack before the TRAP function is executed. As
a default these are assumed to be of size WORD. You can set the size directly
from the TRAP function using a statement such as W,expression or L,expression.expression
can be any list of WORDS or LONG WORDS which need to be loaded onto the
stack when the function is called.If a string variable is included in the
expression then the address of the string, and not the string, will be
placed on the stack. A chr$(0) will be automatically added in this case
to convert it to the correct format.
Stos Assembly Language Interface
TRAP 4
The function number is placed in register D0 and any other data in registers
D1 and A0. After the routine has executed, these registers return the results,
if any, of the call. All other registers are unchanged. Here is a list
of the TRAP 4 routines:
$00 SCONIN
Get a character from the keyboardinput parameters D0=$0output parameters:Bottom
byte of D0.W holds Ascii code of key, top byte contains SCANCODE
$01 SCONIN WITH ECHO
As above with echo to the screen.output parameters: As SCONIN.
$02 SCONOUT
Prints a character on to the screen.input parameters:D1=Ascii code of character
to be printed.
$03 READLINE
Reads a string from the keyboard.input parameters:D1=Maximum number of
characters to be input A0=Address of buffer to hold string.output parameters:A0=Pointer
to buffer.
$04 SPRT
prints out a character to the printer.input parameters:D1=Ascii code of
character.output parameters:D0=0 if an error occurred.
$05 SPRINT LINE
prints a line of text to the screen, accepts standard escape codes.input
parameters:A0=Address of string to be printed. The string must be terminated
by a zero.
$06 SPRINT VID
As SPRINT LINE but escape codes are not translated.input parameters:as
SPRINT LINE
$07 BINHEX
Converts a binary number to a hexadecimal string.input parameters:D1=Number
to be converted.output parameters:A0=Address of hexadecimal string.
$08 HEXBIN
Converts a hexadecimal string to a binary number.input parameters:A0=Address
of string to be converted. output parameters:D0=Binary result.
$09 BINDEC
Converts a binary number to a decimal string.input parameters:D1=Number
to be converted.output parameters:A0=Address of decimal string.
$0A DECBIN
Converts a decimal string to a binary number.input parameters:A0=Address
of decimal string.output parameters:D0=Binary result.
$0B UPPER
Converts a string of characters to upper case.input parameters:A0=Address
of string.output parameters:A0=Address of upper case string.
$0C EXIST
Searches the current drive to see if filename is on the disc
input parameters:A0=Address of filename(terminated with a 0)output parameters:D0=length
of file or -1 if file not found.
$0F CLS
Clears the ST's screen.
$10 LOCATE
Moves the cursor to the desired position on the screen.input parameters:Top
half of D1=X coordinate Bottom half=Y.
$11 BREAK
Prints out the contents of D0-D7 and A0-A6 in hexadecimal.Note D0 is printed
out as D0*4 by this function.
$12 READ
Reads a file from the disc.input parameters:A0=pointer to a parameter block.
Parameter block=pointer to input buffer filename.
output parameters:D0=-1 if the file does not exist.
$13 WRITE
Writes a file to the disc.input parameters:D1=number of bytes to be written.
A0=pointer to parameter block = pointer to input buffer filename.output
parameters:D0=-1 if the file does not exist.
$14 CHDRIVE
Change the current drive.input parameters:D1=drive number(0-3).
$15 CHDIR
Change the current directory.input parameters:A0=pointer to string containing
pathname.
$16 MKDIR
Install a new subdirectory on the disc.input parameters:A0=pointer to string
containing the new directory name.
$17 RMDIR
Delete a subdirectory.input parameters:A0=pointer to string containing
the name of the directory to be replaced.
$18 KILL
Erases a file or a group of files from the disc.input parameters:A0=pointer
to string containing the name or the pathname of the file(s) to be erased.
$19 ASCII
Dumps a buffer containing Ascii text to the printer. Only bytes between
$20 and $7f are printed out. Any other characters are replaced with a [
. ] character.input parameters:D1=Number of bytes to be printed. A0=Address
of print buffer.
$1A FLOPR
Reads one or more sectors from the disc.input parameters:D1=Read parameters.
Lowest word contains the starting sector, the next byte holds the number
of sectors to be read, and the top byte is set to the drive number(0,1,2)
A0=Data buffer.
$1B FLOPW
Writes one or more sectors to the disc. Identical to FLOPR
except the function number is $1B.
$1C MUL32
Multiply two 32 bit numbers.input parameters:A0=Address of a buffer area
containing 1 long word for the result, and 2 long words holding the 2 numbers
to be multiplied. output parameters:D0=result of the calculation.
$1D DIV32
32 by 32 bit division.input parameters:A0=pointer to a buffer of 5 long
words.Longword 1=0Longword 2=dividendLongword 3=divisorLongword 4=0Longword
5=0output parameters:D0=0 if error occurred,non 0 if no error D1=ResultA0=pointer
to 2 long words containing the quotient and the remainder of the division.
$1E DIV64
Performs a 64/32 bit divisioninput parameters:A0=pointer to a buffer of
5 long words. Longword 1=bottom half of dividend. Longword 2=top half of
dividend.Longword 3=divisor.Longwords 4 & 5=0output parameters:D0 &
D1 as DIV32.A0=pointer to 2 long words containing the quotient and 1 holding
the remainder.
$FFFF SET USER
Install a user defined function.input parameters:D0=$FFFFA0=Address of
the start of the new routine.
$1F USER
Calls the user function defined by SET USER.output parameters:UP to you.