From 82ae21f95c1ad1d672386c03289189a3a8a696a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kyle=20J=C2=A0Cardoza?= <Kyle.Cardoza@icloud.com>
Date: Mon, 8 Jul 2024 22:15:36 -0400
Subject: [PATCH] Documentation of kernel API

---
 doc/syscalls.md | 60 ++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 45 insertions(+), 15 deletions(-)

diff --git a/doc/syscalls.md b/doc/syscalls.md
index f063734..7658459 100644
--- a/doc/syscalls.md
+++ b/doc/syscalls.md
@@ -160,10 +160,9 @@ Arguments:
     Y: Address of buffer
 
 Return Values:  
-    None
+    C: Status code
 
-This call sets the system date from the data in the specified buffer,
-which must be in the following format:
+Argument Structure:
 
     struct {
         uint16_t year // Current year
@@ -172,6 +171,8 @@ which must be in the following format:
         uint8_t weekday; // 0 = Sunday..6=Saturday
     };
 
+This call sets the system date from the data in the argument structure.
+
 ## 0x0B: Get Time
 
 Arguments:
@@ -180,10 +181,9 @@ Arguments:
     Y: Address of buffer
 
 Return Values: 
-    None
+    C: Status code
 
-This call fills in the specified buffer with the current time,
-in the following format:
+Argument Structure:
 
     struct {
         uint8_t hour; // 0..23
@@ -191,18 +191,19 @@ in the following format:
         uint8_t second; // 0..59
     };
 
+This call fills in the specified argument structure with the current time.
+
 ## 0x0C: Set Time
 
 Arguments:
     C: 0x0C
-    X: Bank of buffer
+    X: Bank of argument structure
     Y: Address of buffer
 
 Return Values: 
-    None
+    C: Status code
 
-This call sets the current time from the provided buffer, which must
-be in the following format:
+Argument Structure:
 
     struct {
         uint8_t hour; // 0..23
@@ -210,6 +211,8 @@ be in the following format:
         uint8_t second; // 0..59
     };
 
+This call sets the current time from the provided argument structure.
+
 ## 0x0D: Open File
 
 Arguments:
@@ -218,15 +221,16 @@ Arguments:
     Y: Address of pathname string
 
 Return Values: 
-    C: File handle or error code
+    C: Status code
+    X: File handle
 
 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 the file handle,
-a positive integer value. On error, the C accumulator will contain a negative value,
-indicating an error has occured. 
+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
 
@@ -255,4 +259,30 @@ 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
 register will contain the duplicate file handle. On error, the C accumulator will 
-contain a negative value, indicating an error has occured.
\ No newline at end of file
+contain a negative value, indicating an error has occured.
+
+## 0x10: Read from File Handle
+
+Arguments:
+    C: 0x10
+    X: Bank of argument block
+    Y: Address of argument block
+
+Return Values:
+    C: Status code
+    X: Number of bytes actually read
+
+Argument block structure:
+
+    struct {
+        void *dest; // Pointer to the buffer to use.
+        uint16_t file; // File handle.
+        size_t length; // Maximum number of bytes to read.
+    };
+
+
+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,
+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.
\ No newline at end of file