diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/_start_here.txt | 88 | ||||
| -rw-r--r-- | doc/csr.txt | 78 | ||||
| -rw-r--r-- | doc/ecall.txt | 75 | ||||
| -rw-r--r-- | doc/mmio.txt | 41 | ||||
| -rw-r--r-- | doc/monitor.txt | 82 | ||||
| -rw-r--r-- | doc/toolchain.txt | 72 |
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. |