Documentation of kernel API

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
 
@@ -256,3 +260,29 @@ will be exactly identical to the provided one, and either may be used at any tim
 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 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.