From 2492810f6cd0770aa7845558e18b14b646c53013 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kyle=20J=C2=A0Cardoza?= Date: Mon, 8 Jul 2024 23:43:57 -0400 Subject: [PATCH] Documentation of kernel API --- doc/syscalls.md | 178 ++++++++++++++++++++++++------------------------ 1 file changed, 89 insertions(+), 89 deletions(-) diff --git a/doc/syscalls.md b/doc/syscalls.md index ced7944..ca0b6e3 100644 --- a/doc/syscalls.md +++ b/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.