65X-DOS/doc/syscalls.md

550 lines
14 KiB
Markdown
Raw Normal View History

2024-07-08 06:42:08 +02:00
# System Calls
2024-07-09 05:43:57 +02:00
The system API is exposed to user code using the `COP` interrupt.
The `C` accumulator is loaded with a function number;
2024-07-08 06:42:08 +02:00
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.
2024-07-08 23:14:01 +02:00
The system API is based loosely on, but not compatible with, that of
CP/M-3 and MSX-DOS 2.
2024-07-08 23:09:29 +02:00
2024-07-09 05:46:14 +02:00
Most calls return a status code in C. This code has one value, `STATUS_OK`,
2024-07-09 05:54:43 +02:00
(equal to `0x0000`) which applies to all sxuch calls; this value indicates
2024-07-09 05:46:14 +02:00
that the call was successful. Any other value will indicate some specific
error.
2024-07-09 05:25:34 +02:00
2024-07-09 05:45:26 +02:00
## `0x00`: Terminate with Error Code
2024-07-08 23:09:29 +02:00
2024-07-09 05:25:58 +02:00
Arguments:
2024-07-09 05:31:07 +02:00
2024-07-09 05:43:57 +02:00
- `C`: `0x00`
- `X`: Error code
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:31:07 +02:00
- This call does not return.
2024-07-08 23:09:29 +02:00
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.
2024-07-09 05:45:26 +02:00
## `0x01`: Console Input
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x01`
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Character read from stdin
2024-07-08 23:09:29 +02:00
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.
2024-07-09 05:45:26 +02:00
## `0x02`: Console Output
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x02`
- `X`: Character to output
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:31:39 +02:00
- None
2024-07-08 23:09:29 +02:00
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.
2024-07-09 05:45:26 +02:00
## `0x03`: Direct Console Input
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x03`
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Character value or `NULL`
2024-07-08 23:09:29 +02:00
This call does direct (raw) console input; if there is a character ready, it
2024-07-09 05:43:57 +02:00
will be read, and if not, `NULL` will be returned.
2024-07-08 23:09:29 +02:00
2024-07-09 05:45:26 +02:00
## `0x04`: Direct Console Output
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x04`
- `X`: Character value
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:31:39 +02:00
- None
2024-07-08 23:09:29 +02:00
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.
2024-07-09 05:45:26 +02:00
## `0x05`: String Output
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x05`
2024-07-09 06:18:07 +02:00
- `X`: Bank of string
- `Y`: Address of string
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:33:09 +02:00
- None
2024-07-08 23:09:29 +02:00
2024-07-09 05:43:57 +02:00
This call uses the 0x02 call "Console Output" above to send a `NULL`-terminated
2024-07-08 23:09:29 +02:00
string to stdout.
2024-07-09 05:45:26 +02:00
## `0x06`: Buffered Line Input
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x06`
2024-07-09 06:18:07 +02:00
- `X`: Bank of buffer
- `Y`: Address of buffer
2024-07-08 23:09:29 +02:00
Return values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
2024-07-08 23:09:29 +02:00
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.
2024-07-09 05:43:57 +02:00
The newline in the resulting buffer will be replaced with a `NULL` to terminate the
2024-07-08 23:09:29 +02:00
string.
2024-07-09 05:45:26 +02:00
## `0x07`: Console Status
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x07`
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status Code
2024-07-08 23:09:29 +02:00
This call checks stdin for a character to read. If there is none, this call will return
2024-07-09 04:06:32 +02:00
zero in C; if there is a character ready, it will return nonzero in C.
2024-07-08 23:09:29 +02:00
2024-07-09 05:45:26 +02:00
## `0x08`: Return Version Number
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x08`
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Major version
- `X`: Minor version
- `Y`: Micro version
2024-07-08 23:09:29 +02:00
This call returns the version number of the kernel.
2024-07-09 05:45:26 +02:00
## `0x09`: Get Date
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x09`
- `X`: Bank of buffer
- `Y`: Address of buffer
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:33:09 +02:00
- None
2024-07-08 23:09:29 +02:00
This call fills in the specified buffer with the current date,
in the following format:
2024-07-09 05:38:14 +02:00
```
2024-07-08 23:09:29 +02:00
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
}
2024-07-09 05:38:14 +02:00
```
2024-07-08 23:09:29 +02:00
2024-07-09 05:45:26 +02:00
## `0x0A`: Set Date
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x0A`
- `X`: Bank of buffer
- `Y`: Address of buffer
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
2024-07-08 23:09:29 +02:00
2024-07-09 04:15:36 +02:00
Argument Structure:
2024-07-08 23:09:29 +02:00
2024-07-09 05:38:14 +02:00
```
2024-07-08 23:09:29 +02:00
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
};
2024-07-09 05:38:14 +02:00
```
2024-07-08 23:09:29 +02:00
2024-07-09 04:15:36 +02:00
This call sets the system date from the data in the argument structure.
2024-07-09 05:45:26 +02:00
## `0x0B`: Get Time
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x0B`
- `X`: Bank of buffer
- `Y`: Address of buffer
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
2024-07-08 23:09:29 +02:00
2024-07-09 04:15:36 +02:00
Argument Structure:
2024-07-08 23:09:29 +02:00
2024-07-09 05:38:14 +02:00
```
2024-07-08 23:09:29 +02:00
struct {
uint8_t hour; // 0..23
uint8_t minute; // 0..59
uint8_t second; // 0..59
};
2024-07-09 05:38:14 +02:00
```
2024-07-08 23:09:29 +02:00
2024-07-09 04:15:36 +02:00
This call fills in the specified argument structure with the current time.
2024-07-09 05:45:26 +02:00
## `0x0C`: Set Time
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x0C`
- `X`: Bank of argument structure
2024-07-09 06:05:07 +02:00
- `Y`: Address of argument structure
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
2024-07-08 23:09:29 +02:00
2024-07-09 04:15:36 +02:00
Argument Structure:
2024-07-08 23:09:29 +02:00
2024-07-09 05:35:17 +02:00
```
2024-07-08 23:09:29 +02:00
struct {
uint8_t hour; // 0..23
uint8_t minute; // 0..59
uint8_t second; // 0..59
};
2024-07-09 05:35:17 +02:00
```
2024-07-08 23:09:29 +02:00
2024-07-09 04:15:36 +02:00
This call sets the current time from the provided argument structure.
2024-07-09 05:45:26 +02:00
## `0x0D`: Open File
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x0D`
- `X`: Bank of pathname string
- `Y`: Address of pathname string
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
- `X`: File handle
2024-07-08 23:09:29 +02:00
2024-07-09 05:43:57 +02:00
This call attempts to open the file referred to by the provided `NULL`-terminated
2024-07-08 23:09:29 +02:00
string, which must contain a fully-qualified pathname -- something of the form
`[drive]:/[dir]/[dir2]/filename.ext`, such as `sd0:/games/kaboom/readme.ansi`.
2024-07-09 05:55:35 +02:00
If the file is successfully opened, `C` will contain `STATUS_OK`, and
the `X` register will contain the file handle. On error, `C` will contain
2024-07-09 04:15:36 +02:00
a negative value indicating which error has occured.
2024-07-08 23:24:17 +02:00
2024-07-09 05:45:26 +02:00
## `0x0E`: Close File Handle
2024-07-08 23:24:17 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x0E`
- `X`: File handle
2024-07-08 23:24:17 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
2024-07-08 23:24:17 +02:00
This call attempts to close the file referred to by the provided file handle.
2024-07-09 05:55:35 +02:00
On success, `C` will contain a status code of `STATUS_OK`. On error,
`C` will contain a negative value, indicating an error has occured.
2024-07-08 23:24:17 +02:00
2024-07-09 05:45:26 +02:00
## `0x0F`: Duplicate File Handle
2024-07-08 23:24:17 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x0F`
- `X`: File handle
2024-07-08 23:24:17 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
- `X`: Duplicate of file handle
2024-07-08 23:24:17 +02:00
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.
2024-07-09 05:55:35 +02:00
On success, `C` will contain a status code of `STATUS_OK`, and the `X`
register will contain the duplicate file handle. On error, `C` will
2024-07-09 04:15:36 +02:00
contain a negative value, indicating an error has occured.
2024-07-09 05:45:26 +02:00
## `0x10`: Read from File
2024-07-09 04:15:36 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x10`
- `X`: Bank of argument block
- `Y`: Address of argument block
2024-07-09 04:15:36 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
- `X`: Number of bytes actually read
2024-07-09 04:15:36 +02:00
2024-07-09 05:38:14 +02:00
Argument Structure:
2024-07-09 04:15:36 +02:00
2024-07-09 05:38:14 +02:00
```
2024-07-09 04:15:36 +02:00
struct {
void *dest; // Pointer to the buffer to use.
uint16_t file; // File handle.
size_t length; // Maximum number of bytes to read.
};
2024-07-09 05:38:14 +02:00
```
2024-07-09 04:15:36 +02:00
This call attempts to read up to `length` bytes from the file handle `file`, into
2024-07-09 05:55:35 +02:00
the buffer pointed to by `dest`. On success, `C` will contain `STATUS_OK`,
2024-07-09 05:54:43 +02:00
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`
2024-07-09 05:07:36 +02:00
register will contain the number of bytes actually read.
2024-07-09 05:45:26 +02:00
## `0x11`: Write to File
2024-07-09 05:07:36 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x11`
- `X`: Bank of argument block
- `Y`: Address of argument block
2024-07-09 05:07:36 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
- `X`: Number of bytes actually written
2024-07-09 05:07:36 +02:00
2024-07-09 05:38:14 +02:00
Argument Structure:
2024-07-09 05:07:36 +02:00
2024-07-09 05:38:14 +02:00
```
2024-07-09 05:07:36 +02:00
struct {
void *src; // Pointer to the buffer to use.
uint16_t file; // File handle.
size_t length; // Maximum number of bytes to write.
};
2024-07-09 05:38:14 +02:00
```
2024-07-09 05:07:36 +02:00
This call attempts to write up to `length` bytes to the file handle `file`, from
2024-07-09 05:55:35 +02:00
the buffer pointed to by `src`. On success, `C` will contain `STATUS_OK`,
2024-07-09 05:54:43 +02:00
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`
2024-07-09 05:14:59 +02:00
register will contain the number of bytes actually written.
2024-07-09 05:45:26 +02:00
## `0x12`: Seek in File
2024-07-09 05:14:59 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `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
2024-07-09 05:14:59 +02:00
Return value:
2024-07-09 05:43:57 +02:00
- `C`: Status code
- `X`: New file position (Low word)
- `Y`: New file position (High word)
2024-07-09 05:14:59 +02:00
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
2024-07-09 05:54:43 +02:00
`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`.
2024-07-09 05:24:40 +02:00
2024-07-09 05:45:26 +02:00
## `0x13`: Device I/O Control
2024-07-09 05:24:40 +02:00
This call performs driver-specific functions.
2024-07-09 05:45:26 +02:00
## `0x14`: Delete File
2024-07-09 05:24:40 +02:00
Arguments:
2024-07-09 05:43:57 +02:00
- `C`: `0x14`
- `X`: Bank of pathname
- `Y`: Address of pathname
2024-07-09 05:24:40 +02:00
Return Values:
2024-07-09 05:43:57 +02:00
- `C`: Status code
2024-07-09 05:24:40 +02:00
2024-07-09 05:43:57 +02:00
This call attempts to delete the file indicated by the given `NULL`-terminated string,
2024-07-09 05:54:43 +02:00
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
2024-07-09 05:24:40 +02:00
error.
2024-07-09 05:44:16 +02:00
## `0x15`: Move File
2024-07-09 05:24:40 +02:00
Arguments:
2024-07-09 05:38:53 +02:00
- `C`: `0x15`
- `X`: Bank of argument structure
- `Y`: Address of argument structure
2024-07-09 05:24:40 +02:00
Return Values:
2024-07-09 05:38:53 +02:00
- `C`: Status code
2024-07-09 05:24:40 +02:00
Argument Structure:
2024-07-09 05:38:14 +02:00
```
2024-07-09 05:24:40 +02:00
struct {
char *src; // Fully-qualified source pathname.
char *dest; // Fully-qualified destination pathname.
};
2024-07-09 05:38:14 +02:00
```
2024-07-09 05:24:40 +02:00
This call attempts to move or rename the specified `source` file to `dest`. On success,
2024-07-09 05:54:43 +02:00
`C` will contain `STATUS_OK`. On error, `C` will contain a negative value indicating the
2024-07-09 05:24:40 +02:00
specific error.
2024-07-09 06:23:28 +02:00
2024-07-09 07:12:42 +02:00
## `0x16`: Set File Attributes
2024-07-09 06:23:28 +02:00
Arguments:
- `C`: `0x16`
2024-07-09 06:31:24 +02:00
- `X`: File handle
2024-07-09 06:23:28 +02:00
- `Y`: File attribute bitmask
Return Values:
- `C`: Status code
This call alters the file attributes of the specified file. The `Y` register should
contain the result of a bitwise OR operation on any or all of the following values:
- `FILE_READ_ONLY`
- `FILE_HIDDEN`
- `FILE_SYSTEM`
- `FILE_ARCHIVE`
2024-07-09 06:31:24 +02:00
Passing `0x0000` in the `Y` register will clear all attributes.
## `0x17`: Get Current Directory
Arguments:
- `C`: `0x17`
- `X`: Bank of string
- `Y`: Address of string
Return Values:
- `C`: Status code
Argument Structure:
```
struct {
char *drive; // The volume name of the drive to check
char *dest; // Buffer for the returned directory path
};
```
This call attempts to create a `NULL`-terminated string with the path of
the current directory in the drive with the volume name specified in the
`drive` argument, and puts that string into the buffer pointed to by
`dest`. On success, `C` will contain `STATUS_OK`. On failure, `C` will
2024-07-09 06:42:09 +02:00
containe a negative value indicating the error type.
## `0x18`: Set Current Directory
Arguments:
- `C`: `0x18`
- `X`: Bank of string
- `Y`: Address of string
Return Values:
- `C`: Status code
This call attempts to change the current directory on a the drive specified
in the supplied `NULL`-terminated string to the directory listed in that
string. On success, `C` will contain `STATUS_OK`. On failure, `C` will
2024-07-09 08:12:34 +02:00
containe a negative value indicating the error type.
## `0x19`: Assign Device Alias
Arguments:
- `C`: `0x19`
- `X`: Bank of argument structure
- `Y`: Address of argument structure
Return Values:
- `C`: Status code
Argument Structure:
```
struct {
char *device; // The name of the device to alias
char *alias; // The alias to assign to it
};
```
2024-07-09 17:55:22 +02:00
Device drivers in 65X-DOS identify themselves to the kernel by
means of their "major number" -- the index into the internal
device driver table at which the device driver's address can
be found. Specific devices managed by a driver are distinguished
from each other by "minor number" -- an arbitrary number which
holds meaning only to the driver.
2024-07-09 08:12:34 +02:00
Each device driver in 65X-DOS registers one or more major/minor
2024-07-09 17:55:22 +02:00
number pairs to one or more "default" names. These aliases are
2024-07-09 08:12:34 +02:00
what appear in a fully qualified pathname for a file before the
2024-07-09 17:55:22 +02:00
`:` separator character. You might compare this to a "drive letter"
in MS-DOS type systems, or to entries in the `/dev` directory on
a Unix-like system. For example, the SD card driver might register
the device name `sd0` for the first SD card. Drivers which do not
expose file-like functionality still expose default names, because
they use the `ioctl` interface to control their settings.
2024-07-09 08:12:34 +02:00
This call attempts to add a secondary name to an existing device.
This alias will work exactly like the default name, which will still
be valid. A device can have any number of aliases assigned to it.
These aliases are strings which contain any character except `NULL` or
`:`.
This call will fail if the `device` argument is not an exact match to
any device alias, or if the `alias` argument value is already in use
as a device alias.
On success, `C` will contain `STATUS_OK`. On error, `C` will contain
2024-07-09 17:49:08 +02:00
a negative value which indicates the specific error type.
## `0x1A`: Get Environment Variable
Arguments:
- `C`: `0x1A`
- `X`: Bank of argument structure
- `Y`: Address of argument structure
Return Values:
- `C`: Status code
Argument Structure:
```
struct {
char *name; // The name of the variable to read
char *value; // Buffer for the value of the variable
};
```
This call gets the value of an environment variable specified by the
`name` field of the argument structure, and copies it into the buffer
pointed to by the `value` field. If the variable is not set, the value
will be set to `NULL`, and the status code will be `ERR_ENV_UNSET`; otherwise
the status code will be `STATUS_OK`.
## `0x1B`: Set Environment Variable
Arguments:
- `C`: `0x1A`
- `X`: Bank of argument structure
- `Y`: Address of argument structure
Return Values:
- `C`: Status code
Argument Structure:
```
struct {
char *name; // The name of the variable to set
char *value; // Buffer for the new value of the variable
};
```
This call sets the value of an environment variable specified by the
`name` field of the argument structure by copying the string pointed
to by the `value` field. To unset a variable, pass `NULL` in the `value`
field. This call always returns `STATUS_OK`.