diff options
| -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 (renamed from cross-toolchain/SETUP.txt) | 0 | ||||
| -rw-r--r-- | rvcontroller.lua | 216 |
7 files changed, 367 insertions, 213 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/cross-toolchain/SETUP.txt b/doc/toolchain.txt index 720d209..720d209 100644 --- a/cross-toolchain/SETUP.txt +++ b/doc/toolchain.txt diff --git a/rvcontroller.lua b/rvcontroller.lua index f3a85d2..ba03ea4 100644 --- a/rvcontroller.lua +++ b/rvcontroller.lua @@ -3,219 +3,9 @@ --This is free and unencumbered software released into the public domain. --See http://unlicense.org/ for more information ---[[ - -Emulated system specifications: - -Single RISC-V core, RV32IMACBZicfilp_Zicntr_Zicond_Zicsr_Zifencei_Zihintpause_Zilsd_Zimop_Zabha_Zacas_Zalasr_Zawrs_Zcb_Zclsd_Zcmop_Zcmp_Zcmt_Zbkb_Zbkx_Xh3bextm instruction set, switchable endianness (little-endian default) -65536 bytes of RAM (configurable in settings below) starting at base address 0 - -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 - -See https://docs.riscv.org/reference/isa/unpriv/unpriv-index.html for full specifications. - -Monitor commands: - -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> -Displays the current value of the specified register number (0-31) - -setreg <register number> <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 - - -ecall operations: - -NOTE: When in RV32E mode, replace a7 with a5. a5 can also be used in place of a7 in I mode if a7 is 0. - -a7 = 0 -Run the operation from the a5 register instead, unless a5 is also 0 in which case no operation occurs - -a7 = 1 -Prints the integer value from register a0 - -a7 = 4 -Prints the null-terminated string from the address specified by register a0 - -a7 = 5 -Reads an integer from the console and stores it into register a0 -This will block until the user enters a valid number - -a7 = 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 = 10 -Exits the program (halts the CPU) - -a7 = 11 -Prints the character stored in the register a0 - -a7 = 12 -Reads one character from the console (any more characters on the line are discarded) and stores it into register a0 - -a7 = 128 -Gets a random integer (between the values in registers a0 and a1) and stores it into register a0 - -a7 = 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 = 130 -Gets the number of characters available to read from the console input buffer -Result is stored in register a0 - -a7 = 131 -Clears the console input buffer - -a7 = 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 = 133 -Gets the number of messages in the digilines receive buffer -Result is stored in register a0 - -a7 = 134 -Clears the digilines receive buffer - -a7 = 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 - -Custom CSRs: - -0x800[0]: Lightweight mode, controls processor clock speed and behavior when mapblock is unloaded: -0: 10 Hz (adjustable in settings below), processor does not stop when mapblock is unloaded -1: 1 Hz, processor stops when mapblock is unloaded -Note that when set to 0, a digilines message being received will cause the processor to run for one cycle. -This is intended to be used to check if the digilines message needs action to be taken in response, -and the program can then turn lightweight mode off if so. - -0x801: MMIO Base Address (see MMIO section below) -May be set to any address with no alignment restrictions. -0 to disable, all other values enable. - -MMIO: - -Base address is selected by CSR 0x801 above. - -Base + 0: Mesecons I/O Direction -Format: [0000dcba] (WARL) -0 in the bit corresponding to an I/O pin selects input, 1 selects 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 -Format: [0000dcba] (Input bits are RO, output bits are RW) -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. - -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 - -Interrupts: - -Bits 7/16/17 of mie/mip are currently implemented. - -Bit 7: MTIP (machine timer interrupt), standard -Bit 16: MCIP (mesecons input interrupt), custom for RVController -Bit 17: DGIP (digilines receive interrupt), custom for RVController - -]] +--Documentation has moved to the "doc" directory in the repository. +--If you don't have a copy of this, you can find it here: +--https://cheapiesystems.com/git/rvcontroller/tree/doc --Settings local RAM_SIZE = 0x10000 --RAM size in bytes, must be a multiple of 256 |