From 7eb76db305bb4eafc57a31693fd6fe571b4707d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kyle=20J=C2=A0Cardoza?= Date: Mon, 8 Jul 2024 17:09:29 -0400 Subject: [PATCH] Documentation of kernel API --- doc/syscalls.md | 220 +++++++++++++++++++++++++++++++++++++++++++++- src/kernel/main.c | 3 - 2 files changed, 219 insertions(+), 4 deletions(-) diff --git a/doc/syscalls.md b/doc/syscalls.md index e414c3e..3661b7a 100644 --- a/doc/syscalls.md +++ b/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 \ No newline at end of file diff --git a/src/kernel/main.c b/src/kernel/main.c index d8cb109..0213029 100644 --- a/src/kernel/main.c +++ b/src/kernel/main.c @@ -5,10 +5,7 @@ // // Copyright © 2024 Kyle J Cardoza -#include "kernel/device.h" - void main(void) { - device_init_all(); for (;;) {} }