Documentation of kernel API
This commit is contained in:
Kyle J Cardoza
parent
838a66e5e9
commit
2492810f6c
178
doc/syscalls.md
178
doc/syscalls.md
|
|
@ -1,7 +1,7 @@
|
|||
# System Calls
|
||||
|
||||
The system API is exposed to user code using the COP interrupt.
|
||||
The B accumulator is loaded with a function number;
|
||||
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.
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ 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,
|
||||
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.
|
||||
|
||||
|
|
@ -19,8 +19,8 @@ successful. Any other value will indicate some specific error.
|
|||
|
||||
Arguments:
|
||||
|
||||
- C: 0x00
|
||||
- X: Error code
|
||||
- `C`: `0x00`
|
||||
- `X`: Error code
|
||||
|
||||
Return Values:
|
||||
- This call does not return.
|
||||
|
|
@ -32,10 +32,10 @@ the command shell.
|
|||
## 0x01: Console Input
|
||||
|
||||
Arguments:
|
||||
- C: 0x01
|
||||
- `C`: `0x01`
|
||||
|
||||
Return Values:
|
||||
- C: Character read from stdin
|
||||
- `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
|
||||
|
|
@ -49,8 +49,8 @@ continues waiting for another character to be ready.
|
|||
## 0x02: Console Output
|
||||
|
||||
Arguments:
|
||||
- C: 0x02
|
||||
- X: Character to output
|
||||
- `C`: `0x02`
|
||||
- `X`: Character to output
|
||||
|
||||
Return Values:
|
||||
- None
|
||||
|
|
@ -62,19 +62,19 @@ to handle control characters and escape sequences.
|
|||
## 0x03: Direct Console Input
|
||||
|
||||
Arguments:
|
||||
- C: 0x03
|
||||
- `C`: `0x03`
|
||||
|
||||
Return Values:
|
||||
- C: Character value or NULL
|
||||
- `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.
|
||||
will be read, and if not, `NULL` will be returned.
|
||||
|
||||
## 0x04: Direct Console Output
|
||||
|
||||
Arguments:
|
||||
- C: 0x04
|
||||
- X: Character value
|
||||
- `C`: `0x04`
|
||||
- `X`: Character value
|
||||
|
||||
Return Values:
|
||||
- None
|
||||
|
|
@ -86,41 +86,41 @@ control.
|
|||
## 0x05: String Output
|
||||
|
||||
Arguments:
|
||||
- C: 0x05
|
||||
- X: Address of string (15:0)
|
||||
- Y: Address of string (23:16)
|
||||
- `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
|
||||
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)
|
||||
- `C`: `0x06`
|
||||
- `X`: Address of buffer (15:0)
|
||||
- `Y`: Address of buffer (23:16)
|
||||
|
||||
Return values:
|
||||
- C: Status code
|
||||
- `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
|
||||
The newline in the resulting buffer will be replaced with a `NULL` to terminate the
|
||||
string.
|
||||
|
||||
## 0x07: Console Status
|
||||
|
||||
Arguments:
|
||||
- C: 0x07
|
||||
- `C`: `0x07`
|
||||
|
||||
Return Values:
|
||||
- C: Status Code
|
||||
- `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.
|
||||
|
|
@ -128,21 +128,21 @@ zero in C; if there is a character ready, it will return nonzero in C.
|
|||
## 0x08: Return Version Number
|
||||
|
||||
Arguments:
|
||||
- C: 0x08
|
||||
- `C`: `0x08`
|
||||
|
||||
Return Values:
|
||||
- C: Major version
|
||||
- X: Minor version
|
||||
- Y: Micro version
|
||||
- `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
|
||||
- `C`: `0x09`
|
||||
- `X`: Bank of buffer
|
||||
- `Y`: Address of buffer
|
||||
|
||||
Return Values:
|
||||
- None
|
||||
|
|
@ -162,12 +162,12 @@ in the following format:
|
|||
## 0x0A: Set Date
|
||||
|
||||
Arguments:
|
||||
- C: 0x0A
|
||||
- X: Bank of buffer
|
||||
- Y: Address of buffer
|
||||
- `C`: `0x0A`
|
||||
- `X`: Bank of buffer
|
||||
- `Y`: Address of buffer
|
||||
|
||||
Return Values:
|
||||
- C: Status code
|
||||
- `C`: Status code
|
||||
|
||||
Argument Structure:
|
||||
|
||||
|
|
@ -185,12 +185,12 @@ 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
|
||||
- `C`: `0x0B`
|
||||
- `X`: Bank of buffer
|
||||
- `Y`: Address of buffer
|
||||
|
||||
Return Values:
|
||||
- C: Status code
|
||||
- `C`: Status code
|
||||
|
||||
Argument Structure:
|
||||
|
||||
|
|
@ -207,12 +207,12 @@ 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
|
||||
- `C`: `0x0C`
|
||||
- `X`: Bank of argument structure
|
||||
- `Y`: Address of buffer
|
||||
|
||||
Return Values:
|
||||
- C: Status code
|
||||
- `C`: Status code
|
||||
|
||||
Argument Structure:
|
||||
|
||||
|
|
@ -229,61 +229,61 @@ 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
|
||||
- `C`: `0x0D`
|
||||
- `X`: Bank of pathname string
|
||||
- `Y`: Address of pathname string
|
||||
|
||||
Return Values:
|
||||
- C: Status code
|
||||
- X: File handle
|
||||
- `C`: Status code
|
||||
- `X`: File handle
|
||||
|
||||
This call attempts to open the file referred to by the provided NULL-terminated
|
||||
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
|
||||
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
|
||||
- `C`: `0x0E`
|
||||
- `X`: File handle
|
||||
|
||||
Return Values:
|
||||
- C: Status code
|
||||
- `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,
|
||||
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
|
||||
- `C`: `0x0F`
|
||||
- `X`: File handle
|
||||
|
||||
Return Values:
|
||||
- C: Status code
|
||||
- X: Duplicate of file handle
|
||||
- `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
|
||||
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
|
||||
- `C`: `0x10`
|
||||
- `X`: Bank of argument block
|
||||
- `Y`: Address of argument block
|
||||
|
||||
Return Values:
|
||||
- C: Status code
|
||||
- X: Number of bytes actually read
|
||||
- `C`: Status code
|
||||
- `X`: Number of bytes actually read
|
||||
|
||||
Argument Structure:
|
||||
|
||||
|
|
@ -296,7 +296,7 @@ Argument Structure:
|
|||
```
|
||||
|
||||
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,
|
||||
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.
|
||||
|
|
@ -304,13 +304,13 @@ 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
|
||||
- `C`: `0x11`
|
||||
- `X`: Bank of argument block
|
||||
- `Y`: Address of argument block
|
||||
|
||||
Return Values:
|
||||
- C: Status code
|
||||
- X: Number of bytes actually written
|
||||
- `C`: Status code
|
||||
- `X`: Number of bytes actually written
|
||||
|
||||
Argument Structure:
|
||||
|
||||
|
|
@ -323,7 +323,7 @@ Argument Structure:
|
|||
```
|
||||
|
||||
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,
|
||||
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.
|
||||
|
|
@ -331,21 +331,21 @@ 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
|
||||
- `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)
|
||||
- `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
|
||||
`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
|
||||
|
|
@ -355,16 +355,16 @@ This call performs driver-specific functions.
|
|||
## 0x14: Delete File
|
||||
|
||||
Arguments:
|
||||
- C: 0x14
|
||||
- X: Bank of pathname
|
||||
- Y: Address of pathname
|
||||
- `C`: `0x14`
|
||||
- `X`: Bank of pathname
|
||||
- `Y`: Address of pathname
|
||||
|
||||
Return Values:
|
||||
- C: Status code
|
||||
- `C`: Status code
|
||||
|
||||
This call attempts to delete the file indicated by the given NULL-terminated string,
|
||||
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
|
||||
`STATUS_OK`. On failure, C will contain a negative number indicating the specific
|
||||
error.
|
||||
|
||||
## 0x15: Move File
|
||||
|
|
@ -387,5 +387,5 @@ Argument Structure:
|
|||
```
|
||||
|
||||
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
|
||||
C will contain `STATUS_OK`. On error, C will contain a negative value indicating the
|
||||
specific error.
|
||||
|
|
|
|||
Loading…
Reference in New Issue