Crate riscy

Source
Expand description

riscy is a clean and clear implementation of the base 32-bit version of RISC-V instruction set architecture, also known as RV32I.

The oficial specification for RV32I.

riscy does not implement any instrucitons outside of the 42 instructions required by the spec. This makes it rich enough that you can run most simple programs compiled from C on it while keeping it small enough to be used as a tool to learn about RISC-V.

Notably absent from the base specification are:

  • multiplication and division
  • floating point numbers
  • atomic memory operations
  • support for compressed instructions
  • instructions for operating system support (beyond ecall and ebreak)
  • instructions for operating on control status registers (CSRs)

This crate is a library for building emulators containing a RV32I core. The basic building block for this is the RiscV struct, which roughly corresponds to a RISC-V hart (hardware thread).

This crate also comes with a binary (also called riscy) which serves as an example of how to use this library. It can run RISC-V ELF binaries, such as those cross-compiled from GCC or Clang. It can also be used to disassemble those binaries.

$ vim hello.c
$ gcc -march=rv32i -mabi=ilp32 hello.c -o hello
$ riscy hello
Hello, world!
$ riscy --dis hello | head
PC = 0x00010090
_start
0x00010090    97 51 00 00    auipc gp, 20480
0x00010094    93 81 01 db    addi gp, gp, -592
0x00010098    13 85 41 04    addi a0, gp, 68
0x0001009c    13 86 c1 09    addi a2, gp, 156
0x000100a0    33 06 a6 40    sub a2, a2, a0
0x000100a4    93 05 00 00    addi a1, zero, 0
0x000100a8    ef 00 c0 20    jal ra, 0x0000020c
0x000100ac    17 05 00 00    auipc a0, 0

Re-exports§

  • pub use crate::memory::Memory;

Modules§

Structs§

  • Addr
    A struct to representing an address value.
  • DecodeError
    A struct for signaling that there was an error during decoding.
  • Reg
    A struct for representing a general purpose register (eg, x0, x1, …, x32). This is used in the Instruction enum to distinguish the source and destination registers from other numeric data contained in an instruction.
  • RegVal
    A struct for representing a value that can be held inside of a general purpose register (eg, x0, x1, …, x32).
  • RiscV
    A struct to hold the state of a RiscV core.

Enums§

  • Instruction
    A struct for representing a fully decoded r32i instruction. Each variant matches an assembly instruction.
  • StepResult
    A struct to indicate the result of calling .step() or its variants.

Functions§

  • decode
    Decodes an rv32i instruction.