Move documentation out of the program and into separate filesHEADmain

6 files changed, 436 insertions, 0 deletions

diff --git a/doc/_start_here.txt b/doc/_start_here.txt
new file mode 100644
index 0000000..18a05ac
--- /dev/null
+++ b/doc/_start_here.txt
@@ -0,0 +1,88 @@
+RVController
+============
+
+RVController is a program for use in Luacontrollers (from the mesecons mod) in Luanti.
+It emulates a single RISC-V hart and a configurable amount (64KiB default) of RAM.
+
+Features:
+* RV32IMACBZicfilp_Zicntr_Zicond_Zicsr_Zifencei_Zihintpause_Zilsd_Zimop_Zabha_Zacas_Zalasr_Zawrs_Zcb_Zclsd_Zcmop_Zcmp_Zcmt_Zbkb_Zbkx_Xh3bextm instruction set provides:
+ - 32-bit address space
+ - 32 32-bit registers (31 general-purpose + 1 zero register)
+ - Selectable endianness
+ - Multiply/divide instructions
+ - Bit manipulation including crossbar permutation and multiple-bit extraction
+ - Atomic memory operations via load-reserved/store-conditional, compare-and-swap, or math/bitwise operations directly on memory
+ - Byte/halfword/word atomic memory operation sizes
+ - Conditional zero instructions
+ - Freely mixable 16/32-bit instruction lengths
+ - Performance counters and timers
+ - Pause hint for power management
+ - Wait-for-reservation-set instructions to watch for memory changes
+ - Single-instruction function prologues/epilogues and jump tables
+ - Compatibility with future MOP-based extensions
+ - Forward-edge control-flow integrity via landing pads
+* Mutable ISA via writable bits in misa CSR
+* Mesecons and digilines I/O
+* Configurable RAM size and clock speed
+* Mesecons, digilines, and timer interrupts
+* Support for the privileged architecture (currently M-mode only), including:
+ - Configurable interrupt masking
+ - Built-in trap handler, or replace it with your own
+ - Optional vectored interrupt routing
+ - Double-trap detection
+* Built in machine-code monitor with help system and basic debugging support (including breakpoint)
+
+Specifications:
+RVController is intended to be compliant with the following specifications:
+* RV32I Base Integer Instruction Set, Version 2.1
+* "Zifencei" Extension for Instruction-Fetch Fence, Version 2.0
+	- Note: Implemented as a 'nop' instruction as memory is always consistent (see note on RVWMO below)
+* "Zicsr" Extension for Control and Status Register (CSR) Instructions, Version 2.0
+* "Zicond" Extension for Integer Conditional Operations, Version 1.0.0
+* "Zicntr" Extension for Counters, Version 2.0
+* "Zimop" Extension for May-Be-Operations, Version 1.0
+* "M" Extension for Integer Multiplication and Division, Version 2.0
+	- Note: This implies the following:
+	- * Zmmul Extension, Version 1.0
+* "A" Extension for Atomic Instructions, Version 2.1
+	- Note: This implies the following:
+	- * "Zalrsc" Extension for Load-Reserved/Store-Conditional Instructions
+	- * "Zaamo" Extension for Atomic Memory Operations
+* RVWMO Memory Consistency Model, Version 2.0
+	- Note: The actual implemented memory model is significantly more strict (memory is always consistent, there is no cache)
+* "Ztso" Extension for Total Store Ordering, Version 1.0
+* "C" Extension for Compressed Instructions, Version 2.0
+	- Note: This implies the following:
+	- * "Zca" Extension for Code Size Reduction, Version 1.0.0
+* Zcb: Extension for Code Size Reduction, Version 1.0.0
+* "Zcmop" Compressed May-Be-Operations Extension, Version 1.0
+* Zcmp: Extension for Code Size Reduction, Version 1.0.0
+* Zcmt: Extension for Code Size Reduction, Version 1.0.0
+* "B" Extension for Bit Manipulation, Version 1.0.0
+	- Note: This implies the following:
+	- * Zba: Extension for Address generation, Version 1.0.0
+	- * Zbb: Extension for Basic bit-manipulation, Version 1.0.0
+	- * Zbs: Extension for Single-bit instructions, Version 1.0.0
+* "Zihintpause" Extension for Pause Hint, Version 2.0
+* Zilsd, Zclsd: Extensions for Load/Store pair for RV32, Version 1.0
+* "Zabha" Extension for Byte and Halfword Atomic Memory Operations, Version 1.0
+* "Zacas" Extension for Atomic Compare-and-Swap (CAS) Instructions, Version 1.0.0
+* "Zalasr" Atomic Load-Acquire and Store-Release Instructions, Version 1.0
+* "Zawrs" Extension for Wait-on-Reservation-Set instructions, Version 1.01
+* Zbkb: Extension for Bit-manipulation for Cryptography, Version 1.0.0
+* Zbkx: Extension for Crossbar permutations, Version 1.0.0
+* Zicfilp: Control Flow Integrity - Landing Pad
+* Xh3bextm: Hazard3 bit extract multiple
+	- Note: Defined in the Hazard3 reference manual, available at https://github.com/Wren6991/Hazard3/releases/download/v1.1/hazard3.pdf
+* Machine-Level ISA, Version 1.13
+* "Smdbltrp" Double Trap Extension, Version 1.0
+
+For full specification text, visit https://docs.riscv.org/reference/home/index.html
+
+Documentation files:
+* _start_here.txt: This file
+* toolchain.txt: Cross-toolchain setup, needed if you want to build software and don't already have a riscv32(be)-none-elf toolchain
+* monitor.txt: Setup and operation of the built-in machine-code monitor
+* ecall.txt: Available M-mode ecall functions
+* csr.txt: Control and status registers
+* mmio.txt: Memory-mapped I/O
diff --git a/doc/csr.txt b/doc/csr.txt
new file mode 100644
index 0000000..be4a547
--- /dev/null
+++ b/doc/csr.txt
@@ -0,0 +1,78 @@
+RVController Control and Status Registers
+=========================================
+
+The following standard CSRs are available:
+* 0x017: jvt
+* 0x300: mstatus
+* 0x301: misa (0x40801107 = RV32IMACBX)
+* 0x304: mie
+* 0x305: mtvec
+* 0x310: mstatush
+* 0x340: mscratch
+* 0x341: mepc
+* 0x342: mcause
+* 0x343: mtval
+* 0x344: mip
+* 0x34b: mtval2
+* 0x747: mseccfg
+* 0xb00: mcycle
+* 0xb02: minstret
+* 0xb80: mcycleh
+* 0xb82: minstreth
+* 0xc00: cycle
+* 0xc01: time
+* 0xc02: instret
+* 0xc80: cycleh
+* 0xc81: timeh
+* 0xc82: instreth
+* 0xf11: mvendorid (0)
+* 0xf12: marchid (53)
+* 0xf13: mimpid ("RVCo")
+* 0xf14: mhartid (0)
+
+The following custom CSRs are also available:
+
+0x800 - Clock Configuration
+
+ 31                                 1   0
++-----------------------------------------+
+|            Reserved                 | LW|
++-----------------------------------------+
+
+The LW field controls the type of interrupts used.
+* LW=0: Standard interrupts are used. The clock behavior does not depend on player location, and when running, the clock runs at the configured frequency.
+* LW=1: Lightweight interrupts are used. The clock stops when no players are nearby and restarts when a player is nearby again. The clock speed is always 1Hz.
+Lightweight interrupts require mooncontroller. If RVController is running on a mesecons Luacontroller, LW will only control the clock speed.
+
+0x801 - MMIO Base Address
+
+ 31                                      0
++-----------------------------------------+
+|               Address                   |
++-----------------------------------------+
+
+When set to a value in the range 0x00000001 - 0xffffff00,
+the Address field selects the base address of the 256-byte MMIO region.
+When set to 0x00000000, MMIO is disabled.
+See mmio.txt for MMIO region contents.
+
+Additionally, the mip and mie CSRs have some interrupts that are not yet implemented,
+while some of the platform-use bits have been assigned to additional interrupts.
+
+0x304 - mie (Machine Interrupt-Enable)
+
+ 31                       18   17   16   15     8    7   6           0
++---------------------------------------------------------------------+
+|          Reserved          |MDIE|MMIE| Reserved |MTIE|   Reserved   |
++---------------------------------------------------------------------+
+
+0x344 - mie (Machine Interrupt-Pending)
+
+ 31                       18   17   16   15     8    7   6           0
++---------------------------------------------------------------------+
+|          Reserved          |MDIP|MMIP| Reserved |MTIP|   Reserved   |
++---------------------------------------------------------------------+
+
+* MTIE/MTIP: Machine Timer Interrupt (see RISC-V Machine-Level ISA documentation)
+* MMIE/MMIP: Machine Mesecons Interrupt - Becomes pending when a mesecons input changes state and remains pending until manually set to 0
+* MDIE/MDIP: Machine Digilines Interrupt - Becomes pending when a digilines message is received and remains pending until manually set to 0
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.
diff --git a/doc/mmio.txt b/doc/mmio.txt
new file mode 100644
index 0000000..b4c384b
--- /dev/null
+++ b/doc/mmio.txt
@@ -0,0 +1,41 @@
+RVController Memory-Mapped I/O
+==============================
+
+Base address is configurable, see csr.txt.
+
+Base + 0: Mesecons I/O Direction
+
+ 31                     4   3    2    1    0
++---------------------------------------------+
+|        Reserved         |MDRD|MDRC|MDRB|MDRA|
++---------------------------------------------+
+
+MDRA: Mesecons I/O Direction, pin A
+MDRB: Mesecons I/O Direction, pin B
+MDRC: Mesecons I/O Direction, pin C
+MDRD: Mesecons I/O Direction, pin D
+
+When a bit in this register is set to 0, the corresponding pin is an input.
+When set to 1, the corresponding pin is an output.
+Changing a pin from output to input while the output is active may cause unusual behavior due to Luacontroller limitations.
+
+Base + 1: Mesecons I/O Data
+
+ 31                     4   3    2    1    0
++---------------------------------------------+
+|        Reserved         |MDTD|MDTC|MDTB|MDTA|
++---------------------------------------------+
+
+MDTA: Mesecons I/O Data, pin A
+MDTB: Mesecons I/O Data, pin B
+MDTC: Mesecons I/O Data, pin C
+MDTD: Mesecons I/O Data, pin D
+For inputs: Each bit contains the state of the corresponding input. Writes are ignored.
+For outputs: Each bit contains the state of the corresponding output. Writing to these bits turns the output on/off.
+Fields are read-only for inputs and read/write for outputs.
+
+Base + 2: mtime (see RISC-V Machine Level ISA specification)
+
+Base + 10: mtimecmp (see RISC-V Machine Level ISA specification)
+
+Base + 18 - Base + 255: Reserved
diff --git a/doc/monitor.txt b/doc/monitor.txt
new file mode 100644
index 0000000..9496c9e
--- /dev/null
+++ b/doc/monitor.txt
@@ -0,0 +1,82 @@
+RVController Built-in Monitor
+=============================
+
+RVController contains a built-in machine-code monitor accessible by connecting a keyboard
+on channel "monitorkb" and a display on channel "monitordisp".
+
+For best results, use the keyboard and CRT ("cathodic") monitor from the digiterms mod:
+https://content.luanti.org/packages/mt-mods/digiterms/
+
+After connecting these devices and programming the Luacontroller, the following should be displayed:
+
++--------------------+
+|Reset: Cold         |
+|                    |
+|RVController Monitor|
+|                    |
+|Type 'help' for help|
+|Ready               |
++--------------------+
+
+Once you see this display, the monitor is ready to accept commands. The valid commands are:
+
+peek <address>
+Reads and displays the byte (8 bits) value from RAM at the specified address
+
+poke <address> <data>
+Writes the specified byte (8 bits) value to RAM at the specified address
+
+peekw <address>
+Reads and displays the word (32 bits) value from RAM starting at the specified address
+
+pokew <address> <data>
+Writes the specified word (32 bits) value to RAM starting at the specified address
+
+getreg <register number or name>
+Displays the current value of the specified register number (0-31)
+
+setreg <register number or name> <value>
+Sets the specified register (0-31) to the specified value
+
+getpc
+Displays the current value of the program counter
+
+setpc <value>
+Sets the program counter to the specified value
+
+reset
+Stops the CPU, resets all registers to zero, and clears all RAM
+
+step
+Allows the CPU to run for one instruction, then halts
+
+run
+Allows the CPU to run indefinitely
+
+stop
+Halts the CPU
+
+setbreak <address>
+Sets a breakpoint on the specified address.
+Note that the breakpoint triggers just *before* the instruction fetch,
+as in the instruction with the breakpoint on it will not have executed yet.
+There can only be one breakpoint at a time. If one is already set, the new one will replace it.
+
+clearbreak
+Clears any set breakpoint. Note that an ebreak instruction will still cause a break.
+
+help [command]
+Shows information on a monitor command, or a list of commands if none is specified.
+Use 'help 2' to see the second page
+
+rdcsr <CSR address or name>
+Displays the contents of the specified CSR
+
+wrcsr <CSR address or name> <data>
+Writes the specified data to the specified CSR, then reads back and displays the new value.
+Note that the new value may not match the written value if any read-only or WARL fields were written to.
+
+endian [big|little]
+With no arguments, displays the current endianness.
+With the argument "big" or "little", sets the current endianness to big-endian or little-endian respectively.
+This can also be viewed or changed using the MBE bit in the mstatush CSR.
diff --git a/doc/toolchain.txt b/doc/toolchain.txt
new file mode 100644
index 0000000..720d209
--- /dev/null
+++ b/doc/toolchain.txt
@@ -0,0 +1,72 @@
+How to set up the cross-compilation toolchain
+=============================================
+
+RVController can run in little-endian or big-endian mode.
+If you don't know what this means, you want little-endian.
+
+These instructions are for Linux. Doing any of this on other OSes is left as an exercise for the reader.
+
+Little-endian (recommended)
+---------------------------
+
+Target triplet is riscv32-none-elf. activate.sh will set this for you.
+See c/rrxing/Makefile for example commands to compile and link.
+
+Initial setup:
+cd cross-toolchain
+mkdir build target source
+nano activate.sh # Edit the paths to match your installation
+source activate.sh
+
+Binutils (required):
+cd source
+git clone git://sourceware.org/git/binutils-gdb.git
+cd ../build
+mkdir binutils
+cd binutils
+../../source/binutils-gdb/configure --target=$TARGET --prefix="$PREFIX" --with-sysroot --disable-nls --disable-werror
+make -j$(nproc)
+make install # Do not use sudo! root access is not needed.
+cd ../..
+
+GCC (optional, needed if you want to use C but not Clang):
+cd source
+git clone https://gcc.gnu.org/git/gcc.git
+cd ../build
+mkdir gcc
+cd gcc
+../../source/gcc/configure --target=$TARGET --prefix="$PREFIX" --disable-nls --enable-languages=c,c++ --without-headers --disable-hosted-libstdcxx --with-arch=rv32i
+make -j$(nproc) all-gcc all-target-libgcc all-target-libstdc++-v3
+make install-gcc install-target-libgcc install-target-libstdc++-v3 # Do not use sudo! root access is not needed.
+cd ../..
+
+Clang (recommended, needed if you want to use C but not GCC):
+You can just use a copy of clang built for some other arch with "-target riscv32-none-elf".
+If your distro ships a clang package, just install that.
+
+Big-endian
+----------
+
+Target triplet is riscv32be-none-elf. activate-be.sh will set this for you.
+See c/rrxing-be/Makefile for example commands to compile and link.
+
+Initial setup:
+cd cross-toolchain
+mkdir build target source
+nano activate-be.sh # Edit the paths to match your installation
+source activate-be.sh
+
+Binutils (required):
+cd source
+git clone git://sourceware.org/git/binutils-gdb.git
+cd ../build
+mkdir binutils-be
+cd binutils-be
+../../source/binutils-gdb/configure --target=$TARGET --prefix="$PREFIX" --with-sysroot --disable-nls --disable-werror
+make -j$(nproc)
+make install # Do not use sudo! root access is not needed.
+cd ../..
+
+Clang (recommended, required if you want to use C):
+You can just use a copy of clang built for some other arch with "-target riscv32be-none-elf".
+If your distro ships a clang package, just install that.