550 lines
14 KiB
Markdown
Executable File
550 lines
14 KiB
Markdown
Executable File
# 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`,
|
||
(equal to `0x0000`) which applies to all sxuch 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`: Bank of string
|
||
- `Y`: Address of string
|
||
|
||
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`: Bank of buffer
|
||
- `Y`: Address of buffer
|
||
|
||
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 argument structure
|
||
|
||
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, `C` will contain `STATUS_OK`, and
|
||
the `X` register will contain the file handle. On error, `C` 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, `C` will contain a status code of `STATUS_OK`. On error,
|
||
`C` 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, `C` will contain a status code of `STATUS_OK`, and the `X`
|
||
register will contain the duplicate file handle. On error, `C` 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, `C` 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, `C` 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 (Low word)
|
||
- `Y`: New file position (High word)
|
||
|
||
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.
|
||
|
||
## `0x16`: Set File Attributes
|
||
|
||
Arguments:
|
||
- `C`: `0x16`
|
||
- `X`: File handle
|
||
- `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`
|
||
|
||
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
|
||
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
|
||
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
|
||
};
|
||
```
|
||
|
||
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.
|
||
|
||
Each device driver in 65X-DOS registers one or more major/minor
|
||
number pairs to one or more "default" names. These aliases are
|
||
what appear in a fully qualified pathname for a file before the
|
||
`:` 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.
|
||
|
||
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
|
||
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`. |