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,
+Argument Structure:
-which must be in the following format:
 
     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,
+Argument Structure:
-in the following format:
 
     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
+Argument Structure:
-be in the following format:
 
     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,
+If the file is successfully opened, the C accumulator will contain STATUS_OK, and
-a positive integer value. On error, the C accumulator will contain a negative value,
+the X register will contain the file handle. On error, the C accumulator will contain 
-indicating an error has occured. 
+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.
+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.