Table of Contents
The system monitor entry point is software interrupt 1. The handler reads a byte afterthe SWI instruction, and dispatch the call using the SWI table (which is in RAM and can be modified or moved).
So, the calling code is:
SWI FCB n
Most assemblers will allow this equivalent code:
CALL n
Note that you can add 0x80 to the syscall number. This will jump to it using a JMP instead of a JSR instruction. Since most system calls (except MENU) end with an RTS, be careful of what return address you left on the stack.
00 - Soft reset
This is equivalent to pressing the “initial prog” reset button and calls the reset vector. Most of the time, it gets you back to the BASIC or assembler menu.
02 - Put character
Inputs:
- B: ASCII code of character
Prints the character in register B at the current screen position (stored at 0x201B in monitor direct-page)
04 - Map color VRAM page
Map the color video memory so the CPU can write to it.
06 - Map shape VRAM page
Map the shape video memory so the CPU can write to it.
08 - Beep
Beep!
0A - Get character
Perform a keyboard scan and decode the key pressed.
Output:
- Flag Z set if no key pressed
- Variable KEY (0x2037) set to the basic token of the key (if BASIC modifier key was used), or the raw keycode.
- Reg B is set to the ASCII code of the pressed key.
0C - Keyboard test
Lowlevel keyboard scan.
Output:
- Flag Z is set if no key is pressed
- Reg B is set to raw keycode of first pressed key
- Reg A: modifier keys state:
- bit 0: BASIC key
- bit 1: CNT key
- bit 2: yellow key
0E - DRAW
Input:
- Reg X,Y: coordinates of endpoint
- Var CHDRAW (0x2036): character to draw, or 0 for graphics mode
- Var PLOTX, PLOTY (0x2032): start point
- Var SHAPE, COLOR (0x2029): shape/character and color to use
Draws a line from (PLOTX, PLOTY) to (X, Y).
- If CHDRAW = 0, uses graphic mode: color is defined by the SHAPE variable (go figure).
- Else, use text mode: SHAPE is the ASCII character to use, COLOR is the foreground color to use, and the coordinates are character ones.
Output:
- PLOTX and PLOTY are updated to the values of X and Y, and can be used to chain lines when drawing polygons.
10 - PLOT
Input:
- Reg X,Y: coordinates of endpoint
- Var CHDRAW (0x2036): character to draw, or 0 for graphics mode
- Var SHAPE, COLOR (0x2029): shape/character and color to use
Draw a pixel, or put a character, at the position set by X and Y. Works the same way as DRAW.
Output:
- PLOTX and PLOTY are updated to the values of X and Y, and can be used to chain lines when drawing polygons.
12 - Character plot
14 - Get pixel
Input:
- Reg X,Y: coordinates
Gets pixel color.If the pixel is set in shape memory, the foreground color for the block is returned. If pixel is not set, background color for the block is returned.
Output:
- Reg B: pixel color
16 - Lightpen test
Output:
- Flag C reflects the state of the lightpen button
18 - Lightpen scan
Output:
- Flag C is set if lightpen is not pointed at screen
- X,Y: coordinates of the lightpen
1A - Read character from screen
Input:
- Reg X,A: position of character to read
Set register B to the ASCII code of the character at given position, or 0 if unknown. Ifthe character is accented, you will get a value of 16. Calling GETC again with the same parameters will return the accent code, then the letter. Alternatively, those can be read from the SS2GET and SS3GET variables (0x205C).
Output:
- Reg B: result
1C - Joystick scan
Input:
- Reg A: ID of joystick to read (0 or 1)
Scan the joystick. This only works if a “sound and game” expansion is plugged.
Output:
- Flag C: joystick button state
- Reg B: joystick position; 0 is center, 1 is up, then clockwise until 8 which is up-left.
1E - Music generation
Input:
- Reg B: note to play (one octave range, from 0 to D)
- Variables at 0x203A: tempo, duration, timbre, octave settings.
Play one music note.
20 - Tape control
Input:
- Reg A: 0 for reading, 1 for writing
- Reg B: block type (0 = header, 1 = data, FF = EOF)
- Reg Y: data block pointer (points on block size, then data, then checksum)
Perform tape read or write
Output:
- Region at Y written with block, or block written to tape
- Reg A: checksum difference (0 if reading went ok).
22 - Tape motor
Input:
- Reg A: motor command
- bit 0: new motor status (0 to stop, 1 to start)
- bit 1: delay
Starts or stop the tape drive motor. If bit 1 is set, a delay of 1 second is done. Use this when writing to make sure the block is clearly separated from the previous and next ones, and that the loader has time to process the previous block while the tape continues running when reading.
Output:
- Flag C: set if tape drive isn't connected
Extensions
24 - Printer control
Input:
- Reg B: byte to send
- Var PROPC
- 1: Write single byte
- 2: screen dump
- 4: open
- 10: close
This requires the CC90 parallel port extension, and a printer.
Output:
- Flag C: error indicator
- Var PRSTA: error code
Disk ROM
The default SWI table maps all the following syscalls to the floppy ROM. If there isn't a floppy controller attached to the machine, these will jump to unmapped memory, and crash.
The floppy controller expansions are compatible with TO machines as well. Since the TO doesn't use SWI, but has programs jumping directly in a table at the start of the ROM, it's safe to call the disk ROM vectors that way (but then you won't use SWI overrides, if any)
26 - Disk control
Input:
- Var DKOPC (0x2048): Disk operation code
- Var 0x2049: disk drive number
- Var 0x204A: track number (on QDD, 0xFF means LBA access)
- Var 0x204C: sector number (this is 16-bit only for the QDD controller)
General low-level floppy control operation. This performs different actions depending on the value of the DKOPC (0x2048) variable.
Some of these can be combined, for example DKOPC = 88 is “check and write sector”.
DKOPC = 1: Reset
Input:
- Var 0x20E9: pointer to disk operations sector buffer
- Var 0x20ED: pointer to disk FAT buffer
Output:
- Flag C: set on error
- Var DKSTA (0x204E): status code
DKOPC = 2: Read sector
Input:
- Var 0x204F: pointer to destination
DKOPC = 4: Single density
DKOPC = 8: Write sector
Input:
- Var 0x204F: pointer to source
DKOPC = 10: Double density
DKOPC = 20: Seek track 0
DKOPC = 40: Seek track
DKOPC = 80: Check sector
28 - Boot from floppy
Reads the boot sector from the floppy, and runs it.
The default boot sector for DOS BASIC disk loads the DOS BASIC, then runs AUTO.BAT from the floppy if present. It then drops to the interactive DOS BASIC interpreter.
Output:
- DKSTA (0x204E) and 0x2080 are set on error
- This may never return, depending on what the boot sector does
2A - Format floppy
Input:
- Var 0x2048: if bit 7 is set, also verify the formatting
- Var 0x2049: drive number
- Var 0x204D: sector interleaving factor (1 to 15). Unused for QDD.
- Var 0x204F: working buffer pointer
Output:
- Flag C is set on error
- Var DKSTA (0x204E): error code
2C - Allocate block
Input:
- 0x20F6: directory entry pointer (as set by SWI 2E)
- Disk FAT must be loaded (using SWI 34)
Allocate a block in the FAT for the current file.
Output:
- Flag C: set if disk is full
- 0x20E5 is set to 5 (error code: disk full)
- 0x20F9 is set to the newly allocated block number
- The in-memory FAT buffer is updated to allocate the new block.
2E - Allocate directory entry
Input:
- 0x20E7: File descriptor pointer
- 0x20E9: sector working buffer
- 0x20EB: file type
- 0x20EC: file flag
- 0x20F0: file open mode (2 or 3)
Allocate a directory entry for creating a new file.
Output:
- Flag C is set on error
- 0x2045: software error code (directory full, …)
- 0x204E: hardware error code (no disk, sector not found, …)
- 0x20F6: allocated directory entry number
30 - Overwrite file with safe backup
32 - End transaction (Close file)
Input:
- 0x20E7: File descriptor
- 0x20F0: File access mode
- 0x20FE: sector buffer
Updates the disk FAT and catalog from the working copy in memory. This commits all changes done so far and make newly written files visible on disk.
This will not update the “sector count in last cluster” and “byte count in last sector”. If you need a precision greater than a cluster for your file sizes, you have to set them yourself. Other solutions are possible, such as padding ASCII files with EOF characters.
Note it is only useful to call this for file open modes 2 (write) and 3 (write with backup).
Output:
- Flag C: set on error
- 0x204E: error code
34 - Read disk FAT
Input:
- 0x20ED: FAT buffer pointer
Reads the disk FAT to the in-memory working copy
Output:
- Flag C is set on error
- The FAT buffer is filled with the data from the disk.
36 - Update cluster
38 - Open file
Input:
- 0x20E7: Pointer to file descriptor struct
- 0x20E9: Sector working buffer pointer
- 0x20EB: file type
- 0x20EC: file flag
- 0x20F0: open mode (1 = read?, 2 = write, 3 = save and erase)
Locate a file in the FAT and open it for reading or writing. Writing to a file truncates it. The “save and erase” mode opens a temporary file (named SCRATCH.DOS), which will replace the original directory entry when the file is closed.
Output:
- Flag C is set on error. It is NOT set if the file is not found.
- Var 0x20E5: error code (3 = IO error)
- Reg A: same as above.
- 0x20F5: sector counter (set to 0)
- 0x20F6: first block of file
- 0x20F7: byte count in last file sector
- 0x20FA: pointer to file entry in directory table
3A - Erase file
Erase the file from the disk directory, and free all the sectors allocated to it in the FAT. The file must be open first. This does not rewrite the working FAT to disk, for this you must use the “end transaction” call.
Output:
- Flag C is set on error
- 0X2025: error code
- Reg Y: FAT pointer.