65X-DOS/doc/syscalls.md

258 lines
6.1 KiB
Markdown
Raw Normal View History

2024-07-08 06:42:08 +02:00
# System Calls
2024-07-08 23:14:01 +02:00
The system API is exposed to user code using the COP interrupt.
The B 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-08 23:14:01 +02:00
## 0x00: Terminate with Error Code
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x00
X: Error code
2024-07-08 23:09:29 +02:00
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.
2024-07-08 23:14:01 +02:00
## 0x01: Console Input
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x01
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-08 23:14:01 +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-08 23:14:01 +02:00
## 0x02: Console Output
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x02
X: Character to output
2024-07-08 23:09:29 +02:00
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.
2024-07-08 23:14:01 +02:00
## 0x03: Direct Console Input
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x03
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 04:06:32 +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
will be read, and if not, NULL will be returned.
2024-07-08 23:14:01 +02:00
## 0x04: Direct Console Output
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x04
X: Character value
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-09 04:06:32 +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-08 23:14:01 +02:00
## 0x05: String Output
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x05
X: Address of string (15:0)
Y: Address of string (23:16)
2024-07-08 23:09:29 +02:00
Return Values:
None
This call uses the 0x02 call "Console Output" above to send a NULL-terminated
string to stdout.
2024-07-08 23:14:01 +02:00
## 0x06: Buffered Line Input
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x06
X: Address of buffer (15:0)
Y: Address of buffer (23:16)
2024-07-08 23:09:29 +02:00
Return values:
2024-07-09 04:06:32 +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-08 23:14:01 +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-08 23:14:01 +02:00
## 0x07: Console Status
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x07
2024-07-08 23:09:29 +02:00
Return Values:
2024-07-08 23:14:01 +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-08 23:14:01 +02:00
## 0x08: Return Version Number
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x08
2024-07-08 23:09:29 +02:00
Return Values:
C: Major version
2024-07-08 23:14:01 +02:00
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-08 23:14:01 +02:00
## 0x09: Get Date
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x09
X: Bank of buffer
Y: Address of buffer
2024-07-08 23:09:29 +02:00
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
}
2024-07-08 23:14:01 +02:00
## 0x0A: Set Date
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x0A
X: Bank of buffer
Y: Address of buffer
2024-07-08 23:09:29 +02:00
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
};
2024-07-08 23:14:01 +02:00
## 0x0B: Get Time
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x0B
X: Bank of buffer
Y: Address of buffer
2024-07-08 23:09:29 +02:00
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
};
2024-07-08 23:14:01 +02:00
## 0x0C: Set Time
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +02:00
C: 0x0C
X: Bank of buffer
Y: Address of buffer
2024-07-08 23:09:29 +02:00
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
};
2024-07-08 23:14:01 +02:00
## 0x0D: Open File
2024-07-08 23:09:29 +02:00
Arguments:
2024-07-08 23:14:01 +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-08 23:14:01 +02:00
C: File handle or error code
2024-07-08 23:09:29 +02:00
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`.
2024-07-09 04:06:32 +02:00
If the file is successfully opened, the C accumulator will contain the file handle,
a positive integer value. On error, the C accumulator will contain a negative value,
indicating an error has occured.
2024-07-08 23:24:17 +02:00
## 0x0E: Close File
Arguments:
C: 0x0E
X: File handle
Return Values:
2024-07-09 04:06:32 +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 04:06:32 +02:00
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.
2024-07-08 23:24:17 +02:00
## 0x0F: Duplicate File Handle
Arguments:
C: 0x0F
X: File handle
Return Values:
2024-07-09 04:06:32 +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 04:06:32 +02:00
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.