65X-DOS/doc/syscalls.md

System Calls

The system API is exposed to user code using the COP interrupt. The B accumulator is loaded with a function number; the other registers are loaded with call-specific data (or nothing), and any return values are placed in the same registers.

What follows is a list of the system calls, their numbers, and register arguments they take, and what if any values they return.

The system API is based loosely on, but not compatible with, that of CP/M-3 and MSX-DOS 2.

0x00: Terminate with Error Code

Arguments: C: 0x00 X: Error code

Return Values: This call does not return.

This call exits the calling program, setting the exit status code for the system on its way out. Program control will be returned to the command shell.

0x01: Console Input

Arguments: C: 0x01

Return Values: C: Character read from stdin

This call reads one character from standard input. If there is no character ready, this call waits until there is one. The read character will also be echoed to the screen, just as if it had been passed to the Console Output call.

This call traps certain sequences of characters for "terminal control" purposes. When this call traps such a character, it outputs nothing an continues waiting for another character to be ready.

0x02: Console Output

Arguments: C: 0x02 X: Character to output

Return Values: None

This call sends a single chracter to the standard output, which is usually the terminal emulator. The character will be parsed by the terminal emulator to handle control characters and escape sequences.

0x03: Direct Console Input

Arguments: C: 0x03

Return Values: C: Character value

This call does direct (raw) console input; if there is a character ready, it will be read, and if not, NULL will be returned.

0x04: Direct Console Output

Arguments: C: 0x04 X: Character value

Return Values: C: Character value

This call does direct (raw) console output; the value supplied will be treated as the value to write to screen memory, and will not be interpreted for terminal control.

0x05: String Output

Arguments: C: 0x05 X: Address of string (15:0) Y: Address of string (23:16)

Return Values: None

This call uses the 0x02 call "Console Output" above to send a NULL-terminated string to stdout.

0x06: Buffered Line Input

Arguments: C: 0x06 X: Address of buffer (15:0) Y: Address of buffer (23:16)

Return values: C: Error code

This call will read up to 255 characters from stdin, or up to the first newline, whichever comes first. While taking input, a simple line editor is presented to the user. When the 255th character has been entered into the buffer, any further input will be ignored until a newline is entered.

The newline in the resulting buffer will be replaced with a NULL to terminate the string.

0x07: Console Status

Arguments: C: 0x07

Return Values: C: Status Code

This call checks stdin for a character to read. If there is none, this call will return zero in A; if there is a character ready, it will return nonzero in A.

0x08: Return Version Number

Arguments: C: 0x08

Return Values: C: Major version X: Minor version Y: Micro version

This call returns the version number of the kernel.

0x09: Get Date

Arguments: C: 0x09 X: Bank of buffer Y: Address of buffer

Return Values:
None

This call fills in the specified buffer with the current date, in the following format:

struct {
    uint16_t year // Current year
    uint8_t month; // 1 = January..12 = December
    uint8_t day; // 1..31
    uint8_t weekday; // 0 = Sunday..6=Saturday
}

0x0A: Set Date

Arguments: C: 0x0A X: Bank of buffer Y: Address of buffer

Return Values:
None

This call sets the system date from the data in the specified buffer, which must be in the following format:

struct {
    uint16_t year // Current year
    uint8_t month; // 1 = January..12 = December
    uint8_t day; // 1..31
    uint8_t weekday; // 0 = Sunday..6=Saturday
};

0x0B: Get Time

Arguments: C: 0x0B X: Bank of buffer Y: Address of buffer

Return Values: None

This call fills in the specified buffer with the current time, in the following format:

struct {
    uint8_t hour; // 0..23
    uint8_t minute; // 0..59
    uint8_t second; // 0..59
};

0x0C: Set Time

Arguments: C: 0x0C X: Bank of buffer Y: Address of buffer

Return Values: None

This call sets the current time from the provided buffer, which must be in the following format:

struct {
    uint8_t hour; // 0..23
    uint8_t minute; // 0..59
    uint8_t second; // 0..59
};

0x0D: Open File

Arguments: C: 0x0D X: Bank of pathname string Y: Address of pathname string

Return Values: C: File handle or error code

This call attempts to open the file referred to by the provided NULL-terminated string, which must contain a fully-qualified pathname -- something of the form [drive]:/[dir]/[dir2]/filename.ext, such as sd0:/games/kaboom/readme.ansi.

If the file is successfully opened, the carry flag will be cleared and the C accumulator will contain the file handle. On error, the carry flag will be

0x0E: Close File

Arguments: C: 0x0E X: File handle

Return Values: C: Error code

This call attempts to close the file referred to by the provided file handle. On success, the carry flag will be cleared, and the C accumulator will contain a status code of 0x0000. On error, the carry flag will be set, and the C accumulator will contain an error code.

0x0F: Duplicate File Handle

Arguments: C: 0x0F X: File handle

Return Values: C: File handle or error code

This call attempts to duplicate the provided file handle. The new file handle will be exactly identical to the provided one, and either may be used at any time. On success, the carry flag will be cleared, and the C accumulator will contain the duplicate file handle. On error, the carry flag will be set, and the C accumulator will contain an error code.