Sentinel65X
/
65X-DOS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation of kernel API

This commit is contained in:
Kyle J Cardoza 2024-07-08 23:43:57 -04:00
parent 838a66e5e9
commit 2492810f6c
1 changed files with 89 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
doc/syscalls.md
View File

@ -1,7 +1,7 @@
# System Calls # System Calls
The system API is exposed to user code using the COP interrupt. The system API is exposed to user code using the `COP` interrupt.
The B accumulator is loaded with a function number; The `C` accumulator is loaded with a function number;
the other registers are loaded with call-specific data (or nothing), the other registers are loaded with call-specific data (or nothing),
and any return values are placed in the same registers. 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 The system API is based loosely on, but not compatible with, that of
CP/M-3 and MSX-DOS 2. 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 which applies to all such calls; this value indicates that the call was
successful. Any other value will indicate some specific error. successful. Any other value will indicate some specific error.
@ -19,8 +19,8 @@ successful. Any other value will indicate some specific error.
Arguments: Arguments:
- C: 0x00 - `C`: `0x00`
- X: Error code - `X`: Error code
Return Values: Return Values:
- This call does not return. - This call does not return.
@ -32,10 +32,10 @@ the command shell.
## 0x01: Console Input ## 0x01: Console Input
Arguments: Arguments:
- C: 0x01 - `C`: `0x01`
Return Values: 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 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 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 ## 0x02: Console Output
Arguments: Arguments:
- C: 0x02 - `C`: `0x02`
- X: Character to output - `X`: Character to output
Return Values: Return Values:
- None - None
@ -62,19 +62,19 @@ to handle control characters and escape sequences.
## 0x03: Direct Console Input ## 0x03: Direct Console Input
Arguments: Arguments:
- C: 0x03 - `C`: `0x03`
Return Values: 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 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 ## 0x04: Direct Console Output
Arguments: Arguments:
- C: 0x04 - `C`: `0x04`
- X: Character value - `X`: Character value
Return Values: Return Values:
- None - None
@ -86,41 +86,41 @@ control.
## 0x05: String Output ## 0x05: String Output
Arguments: Arguments:
- C: 0x05 - `C`: `0x05`
- X: Address of string (15:0) - `X`: Address of string (15:0)
- Y: Address of string (23:16) - `Y`: Address of string (23:16)
Return Values: Return Values:
- None - 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. string to stdout.
## 0x06: Buffered Line Input ## 0x06: Buffered Line Input
Arguments: Arguments:
- C: 0x06 - `C`: `0x06`
- X: Address of buffer (15:0) - `X`: Address of buffer (15:0)
- Y: Address of buffer (23:16) - `Y`: Address of buffer (23:16)
Return values: Return values:
- C: Status code - `C`: Status code
This call will read up to 255 characters from stdin, or up to the first newline, 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 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 the user. When the 255th character has been entered into the buffer, any further
input will be ignored until a newline is entered. 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. string.
## 0x07: Console Status ## 0x07: Console Status
Arguments: Arguments:
- C: 0x07 - `C`: `0x07`
Return Values: 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 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. 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 ## 0x08: Return Version Number
Arguments: Arguments:
- C: 0x08 - `C`: `0x08`
Return Values: Return Values:
- C: Major version - `C`: Major version
- X: Minor version - `X`: Minor version
- Y: Micro version - `Y`: Micro version
This call returns the version number of the kernel. This call returns the version number of the kernel.
## 0x09: Get Date ## 0x09: Get Date
Arguments: Arguments:
- C: 0x09 - `C`: `0x09`
- X: Bank of buffer - `X`: Bank of buffer
- Y: Address of buffer - `Y`: Address of buffer
Return Values: Return Values:
- None - None
@ -162,12 +162,12 @@ in the following format:
## 0x0A: Set Date ## 0x0A: Set Date
Arguments: Arguments:
- C: 0x0A - `C`: `0x0A`
- X: Bank of buffer - `X`: Bank of buffer
- Y: Address of buffer - `Y`: Address of buffer
Return Values: Return Values:
- C: Status code - `C`: Status code
Argument Structure: Argument Structure:
@ -185,12 +185,12 @@ This call sets the system date from the data in the argument structure.
## 0x0B: Get Time ## 0x0B: Get Time
Arguments: Arguments:
- C: 0x0B - `C`: `0x0B`
- X: Bank of buffer - `X`: Bank of buffer
- Y: Address of buffer - `Y`: Address of buffer
Return Values: Return Values:
- C: Status code - `C`: Status code
Argument Structure: Argument Structure:
@ -207,12 +207,12 @@ This call fills in the specified argument structure with the current time.
## 0x0C: Set Time ## 0x0C: Set Time
Arguments: Arguments:
- C: 0x0C - `C`: `0x0C`
- X: Bank of argument structure - `X`: Bank of argument structure
- Y: Address of buffer - `Y`: Address of buffer
Return Values: Return Values:
- C: Status code - `C`: Status code
Argument Structure: Argument Structure:
@ -229,61 +229,61 @@ This call sets the current time from the provided argument structure.
## 0x0D: Open File ## 0x0D: Open File
Arguments: Arguments:
- C: 0x0D - `C`: `0x0D`
- X: Bank of pathname string - `X`: Bank of pathname string
- Y: Address of pathname string - `Y`: Address of pathname string
Return Values: Return Values:
- C: Status code - `C`: Status code
- X: File handle - `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 string, which must contain a fully-qualified pathname -- something of the form
`[drive]:/[dir]/[dir2]/filename.ext`, such as `sd0:/games/kaboom/readme.ansi`. `[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 the X register will contain the file handle. On error, the C accumulator will contain
a negative value indicating which error has occured. a negative value indicating which error has occured.
## 0x0E: Close File Handle ## 0x0E: Close File Handle
Arguments: Arguments:
- C: 0x0E - `C`: `0x0E`
- X: File handle - `X`: File handle
Return Values: Return Values:
- C: Status code - `C`: Status code
This call attempts to close the file referred to by the provided file handle. 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. the C accumulator will contain a negative value, indicating an error has occured.
## 0x0F: Duplicate File Handle ## 0x0F: Duplicate File Handle
Arguments: Arguments:
- C: 0x0F - `C`: `0x0F`
- X: File handle - `X`: File handle
Return Values: Return Values:
- C: Status code - `C`: Status code
- X: Duplicate of file handle - `X`: Duplicate of file handle
This call attempts to duplicate the provided file handle. The new 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. 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 register will contain the duplicate file handle. On error, the C accumulator will
contain a negative value, indicating an error has occured. contain a negative value, indicating an error has occured.
## 0x10: Read from File ## 0x10: Read from File
Arguments: Arguments:
- C: 0x10 - `C`: `0x10`
- X: Bank of argument block - `X`: Bank of argument block
- Y: Address of argument block - `Y`: Address of argument block
Return Values: Return Values:
- C: Status code - `C`: Status code
- X: Number of bytes actually read - `X`: Number of bytes actually read
Argument Structure: Argument Structure:
@ -296,7 +296,7 @@ Argument Structure:
``` ```
This call attempts to read up to `length` bytes from the file handle `file`, into 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 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 accumulator will contain a negative value indicating the specific error, and the X
register will contain the number of bytes actually read. 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 ## 0x11: Write to File
Arguments: Arguments:
- C: 0x11 - `C`: `0x11`
- X: Bank of argument block - `X`: Bank of argument block
- Y: Address of argument block - `Y`: Address of argument block
Return Values: Return Values:
- C: Status code - `C`: Status code
- X: Number of bytes actually written - `X`: Number of bytes actually written
Argument Structure: Argument Structure:
@ -323,7 +323,7 @@ Argument Structure:
``` ```
This call attempts to write up to `length` bytes to the file handle `file`, from 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 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 accumulator will contain a negative value indicating the specific error, and the X
register will contain the number of bytes actually written. 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 ## 0x12: Seek in File
Arguments: Arguments:
- C: 0x12 - `C`: `0x12`
- X: Seek value - `X`: Seek value
- Y: Seek origin - `Y`: Seek origin
- 0x00: Seek relative to the beginning of the file - `0x00`: Seek relative to the beginning of the file
- 0x01: Seek relative to the current position in the file - `0x01`: Seek relative to the current position in the file
- 0x02: Seek relative to the end of the file - `0x02`: Seek relative to the end of the file
Return value: Return value:
- C: Status code - `C`: Status code
- X: New file position (31:16) - `X`: New file position (`31:16`)
- Y: New file position (15:0) - `Y`: New file position (`15:0`)
This call moves the internal file pointer, the position in the specified file from 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 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. value indicating the specific error, and the new file position in X and Y.
## 0x13: Device I/O Control ## 0x13: Device I/O Control
@ -355,16 +355,16 @@ This call performs driver-specific functions.
## 0x14: Delete File ## 0x14: Delete File
Arguments: Arguments:
- C: 0x14 - `C`: `0x14`
- X: Bank of pathname - `X`: Bank of pathname
- Y: Address of pathname - `Y`: Address of pathname
Return Values: 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 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. error.
## 0x15: Move File ## 0x15: Move File
@ -387,5 +387,5 @@ Argument Structure:
``` ```
This call attempts to move or rename the specified `source` file to `dest`. On success, 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. specific error.