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.
documentations/monitor/syscalls.txt · Last modified: 2015/02/28 18:08 (external edit)
CC0 1.0 Universal
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0