From 69cda888f57246002d8b2ae9d66762d9b5bc7500 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kyle=20J=C2=A0Cardoza?= Date: Mon, 8 Jul 2024 17:14:01 -0400 Subject: [PATCH] Documentation of kernel API --- doc/syscalls.md | 116 ++++++++++++++++++++++++------------------------ 1 file changed, 58 insertions(+), 58 deletions(-) diff --git a/doc/syscalls.md b/doc/syscalls.md index 3661b7a..17bc8fe 100644 --- a/doc/syscalls.md +++ b/doc/syscalls.md @@ -1,21 +1,21 @@ # 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 B 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. +The system API is based loosely on, but not compatible with, that of +CP/M-3 and MSX-DOS 2. -## 0x00: Terminate with Error Code +## 0x00: Terminate with Error Code Arguments: - C: 0x00 - X: Error code + C: 0x00 + X: Error code Return Values: This call does not return. @@ -24,13 +24,13 @@ 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 +## 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 @@ -41,11 +41,11 @@ 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 +## 0x02: Console Output Arguments: - C: 0x02 - X: Character to output + C: 0x02 + X: Character to output Return Values: None @@ -54,36 +54,36 @@ 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 +## 0x03: Direct Console Input Arguments: - C: 0x03 + C: 0x03 Return Values: - C: Character value + C: Character value 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 +## 0x04: Direct Console Output Arguments: - C: 0x04 - X: Character value + C: 0x04 + X: Character value Return Values: - C: Character value + C: Character value 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 +## 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 @@ -91,53 +91,53 @@ Return Values: This call uses the 0x02 call "Console Output" above to send a NULL-terminated string to stdout. -## 0x06: Buffered Line Input +## 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: Error code + C: Error 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 +## 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 A; if there is a character ready, it will return nonzero in A. -## 0x08: Return Version Number +## 0x08: Return Version Number Arguments: - C: 0x08 + C: 0x08 Return Values: C: Major version - X: Minor version - Y: Micro version + X: Minor version + Y: Micro version This call returns the version number of the kernel. -## 0x09: Get Date +## 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 @@ -152,12 +152,12 @@ in the following format: uint8_t weekday; // 0 = Sunday..6=Saturday } -## 0x0A: Set Date +## 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: None @@ -172,12 +172,12 @@ which must be in the following format: uint8_t weekday; // 0 = Sunday..6=Saturday }; -## 0x0B: Get Time +## 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: None @@ -191,12 +191,12 @@ in the following format: uint8_t second; // 0..59 }; -## 0x0C: Set Time +## 0x0C: Set Time Arguments: - C: 0x0C - X: Bank of buffer - Y: Address of buffer + C: 0x0C + X: Bank of buffer + Y: Address of buffer Return Values: None @@ -210,15 +210,15 @@ be in the following format: uint8_t second; // 0..59 }; -## 0x0D: Open File +## 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: File handle or error code + C: File handle or error code 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