1 files changed, 75 insertions, 0 deletions
diff --git a/doc/ecall.txt b/doc/ecall.txt
new file mode 100644
index 0000000..02cdcab
--- /dev/null
+++ b/doc/ecall.txt
@@ -0,0 +1,75 @@
+RVController M-mode ecall functions
+===================================
+
+Executing an ecall instruction in M-mode (currently the only mode) functions as an emulator call.
+The operation to be performed is selected by:
+* When in RV32E mode (misa[4] = 1, misa[8] = 0): register a5
+* When in RV32I mode (misa[4] = 0, misa[8] = 1) AND register a7 is 0: register a5
+* Otherwise: register a7
+
+The available operations are:
+
+a7(/a5) = 0
+No operation
+
+a7(/a5) = 1
+Prints the integer value from register a0
+
+a7(/a5) = 4
+Prints the null-terminated string from the address specified by register a0
+
+a7(/a5) = 5
+Reads an integer from the console and stores it into register a0
+This will block until the user enters a valid number
+
+a7(/a5) = 8
+Reads a string from the console and stores it (with a null terminator) into the address pointed to by register a0
+Will not read more than the length specified in register a1, anything more is discarded
+This will block until the user types something
+
+a7(/a5) = 10
+Exits the program (halts the CPU)
+
+a7(/a5) = 11
+Prints the character stored in the register a0
+
+a7(/a5) = 12
+Reads one character from the console (any more characters on the line are discarded) and stores it into register a0
+
+a7(/a5) = 128
+Gets a random integer (between the values in registers a0 and a1) and stores it into register a0
+
+a7(/a5) = 129
+Sends a digilines string message:
+* channel is specified by the null-terminated string at the address specified by register a0
+* message is specified by the null-terminated string at the address specified by register a1
+
+a7(/a5) = 130
+Gets the number of characters available to read from the console input buffer
+Result is stored in register a0
+
+a7(/a5) = 131
+Clears the console input buffer
+
+a7(/a5) = 132
+Reads one character from the console input buffer and stores it into register a0
+This will not block - if no data is available to read, a NUL character (0) is returned
+The input buffer can store up to 256 characters - if full, incoming characters are dropped
+
+a7(/a5) = 133
+Gets the number of messages in the digilines receive buffer
+Result is stored in register a0
+
+a7(/a5) = 134
+Clears the digilines receive buffer
+
+a7(/a5) = 135
+Reads one message from the digilines receive buffer, returns channel and message as null-terminated strings
+This will not block - if no data is available to read, zero-length strings will be returned
+Arguments:
+a0 - Address that the channel string will be written to
+a1 - Size of the buffer that the channel string will be written into
+a2 - Address that the message will be written to
+a3 - Size of the buffer that the message will be written into
+
+All values not listed are reserved.