65X-DOS/doc/syscalls.md

# System Calls

The system API is exposed to user code using the `COP` interrupt.
The `C` 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.

Most calls return a status code in C. This code has one value,  `STATUS_OK`,
which applies to all such calls; this value indicates that the call was
successful. Any other value will indicate some specific error.

## 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 or  `NULL`

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:
 - None

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`: Status 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 C; if there is a character ready, it will return nonzero in C.

## 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:  
 - `C`: Status code

Argument Structure:

```
    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
    };
```

This call sets the system date from the data in the argument structure.

## 0x0B: Get Time

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

Return Values: 
 - `C`: Status code

Argument Structure:

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

This call fills in the specified argument structure with the current time.

## 0x0C: Set Time

Arguments:
 - `C`: `0x0C`
 - `X`: Bank of argument structure
 - `Y`: Address of buffer

Return Values: 
 - `C`: Status code

Argument Structure:

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

This call sets the current time from the provided argument structure.

## 0x0D: Open File

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

Return Values: 
 - `C`: Status code
 - `X`: File handle

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 C accumulator will contain  `STATUS_OK`, and
the X register will contain the file handle. On error, the C accumulator will contain 
a negative value indicating which error has occured.

## 0x0E: Close File Handle

Arguments:
 - `C`: `0x0E`
 - `X`: File handle

Return Values: 
 - `C`: Status code

This call attempts to close the file referred to by the provided file handle.
On success, the C accumulator will contain a status code of  `STATUS_OK`. On error, 
the C accumulator will contain a negative value, indicating an error has occured.

## 0x0F: Duplicate File Handle

Arguments:
 - `C`: `0x0F`
 - `X`: File handle

Return Values: 
 - `C`: Status code
 - `X`: Duplicate of file handle

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 C accumulator will contain a status code of  `STATUS_OK`, and the X
register will contain the duplicate file handle. On error, the C accumulator will 
contain a negative value, indicating an error has occured.

## 0x10: Read from File

Arguments:
 - `C`: `0x10`
 - `X`: Bank of argument block
 - `Y`: Address of argument block

Return Values:
 - `C`: Status code
 - `X`: Number of bytes actually read

Argument Structure:

```
    struct {
        void *dest; // Pointer to the buffer to use.
        uint16_t file; // File handle.
        size_t length; // Maximum number of bytes to read.
    };
```

This call attempts to read up to `length` bytes from the file handle `file`, into
the buffer pointed to by `dest`. On success, the C accumulator will contain  `STATUS_OK`,
and the X register will contain the number of bytes actually read. On error, the C
accumulator will contain a negative value indicating the specific error, and the X
register will contain the number of bytes actually read.

## 0x11: Write to File

Arguments:
 - `C`: `0x11`
 - `X`: Bank of argument block
 - `Y`: Address of argument block

Return Values:
 - `C`: Status code
 - `X`: Number of bytes actually written

Argument Structure:

```
    struct {
        void *src; // Pointer to the buffer to use.
        uint16_t file; // File handle.
        size_t length; // Maximum number of bytes to write.
    };
```

This call attempts to write up to `length` bytes to the file handle `file`, from
the buffer pointed to by `src`. On success, the C accumulator will contain  `STATUS_OK`,
and the X register will contain the number of bytes actually written. On error, the C
accumulator will contain a negative value indicating the specific error, and the X
register will contain the number of bytes actually written.

## 0x12: Seek in File

Arguments:
 - `C`: `0x12`
 - `X`: Seek value
 - `Y`: Seek origin
   - `0x00`: Seek relative to the beginning of the file
   - `0x01`: Seek relative to the current position in the file
   - `0x02`: Seek relative to the end of the file

Return value:
 - `C`: Status code
 - `X`: New file position (`31:16`)
 - `Y`: New file position (`15:0`)

This call moves the internal file pointer, the position in the specified file from
which data can be read or to which data can be written. On success, this call returns
 `STATUS_OK` in C, and the new file position in X and Y. On error, C will contain a negative
value indicating the specific error, and the new file position in X and Y.

## 0x13: Device I/O Control

This call performs driver-specific functions.

## 0x14: Delete File

Arguments:
 - `C`: `0x14`
 - `X`: Bank of pathname
 - `Y`: Address of pathname

Return Values:
 - `C`: Status code

This call attempts to delete the file indicated by the given  `NULL`-terminated string,
which must contain a fully-qualified pathname. On success, this C will contain
 `STATUS_OK`. On failure, C will contain a negative number indicating the specific
error.

## `0x15`: Move File

Arguments:
 - `C`: `0x15`
 - `X`: Bank of argument structure
 - `Y`: Address of argument structure

Return Values:
 - `C`: Status code

Argument Structure:

```
    struct {
        char *src; // Fully-qualified source pathname.
        char *dest; // Fully-qualified destination pathname.
    };
```

This call attempts to move or rename the specified `source` file to `dest`. On success,
C will contain  `STATUS_OK`. On error, C will contain a negative value indicating the
specific error.