Documentation of kernel API

doc/syscalls.md

@@ -1,10 +1,228 @@
 # System Calls
 
 The system API is exposed to user code using the COP interrupt.
-The high byte of the C accumulator is loaded with a function number;
+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.
+
+## 0x00: Terminate with Error Code
+
+Arguments:
+    C: 0x00
+    X: Error code
+
+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.
+
+## 0x01: Console Input
+
+Arguments:
+    C: 0x01
+
+Return Values:
+    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
+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.
+
+## 0x02: Console Output
+
+Arguments:
+    C: 0x02
+    X: Character to output
+
+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.
+
+## 0x03: Direct Console Input
+
+Arguments:
+    C: 0x03
+
+Return Values:
+    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
+
+Arguments:
+    C: 0x04
+    X: Character value
+
+Return Values:
+    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
+
+Arguments:
+    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
+string to stdout.
+
+## 0x06: Buffered Line Input
+
+Arguments:
+    C: 0x06
+    X: Address of buffer (15:0)
+    Y: Address of buffer (23:16)
+
+Return values:
+    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
+string.
+
+## 0x07: Console Status
+
+Arguments:
+    C: 0x07
+
+Return Values:
+    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
+
+Arguments:
+    C: 0x08
+
+Return Values:
+    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
+
+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
+    }
+
+## 0x0A: Set Date
+
+Arguments:
+    C: 0x0A
+    X: Bank of buffer
+    Y: Address of buffer
+
+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
+    };
+
+## 0x0B: Get Time
+
+Arguments:
+    C: 0x0B
+    X: Bank of buffer
+    Y: Address of buffer
+
+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
+    };
+
+## 0x0C: Set Time
+
+Arguments:
+    C: 0x0C
+    X: Bank of buffer
+    Y: Address of buffer
+
+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
+    };
+
+## 0x0D: Open File
+
+Arguments:
+    C: 0x0D
+    X: Bank of pathname string
+    Y: Address of pathname string
+
+Return Values: 
+    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
+`[drive]:/[dir]/[dir2]/filename.ext`, such as `sd0:/games/kaboom/readme.ansi`.
+
+If the file is successfully opened, the carry flag will be cleared and the C
+accumulator will contain the file handle. On error, the carry flag will be 

src/kernel/main.c

@@ -5,10 +5,7 @@
 //
 // Copyright © 2024 Kyle J Cardoza <Kyle.Cardoza@icloud.com>
 
-#include "kernel/device.h"
-
 void main(void) {
-	device_init_all();
 
     for (;;) {}
 }