lib-rv32

Overview

lib-rv32 is a collection of Rust libraries for emulating, learning, and assembling 32-bit RISC-V integer ISAs.

lib-rv32-isa: library for ISA simulation
lib-rv32-mcu: reference implemenation of an MCU used in conjunction with lib_rv32_isa
lib-rv32-asm: library for assembling RISC-V programs
lib-rv32-cli: CLI tool exposing the libraries
lib-rv32-wasm: An webapp using the library's WASM bindings.

Libraries

ISA simulator

This library can execute instructions against any memory and register file that implements the required primitives in the traits lib_rv32_common::traits::{Memory, RegisterFile}. This is to encourage usage with whatever frontend you desire.

However, reference implementations are provided in lib_rv32_mcu::*. The library provides functions to read from the memory, registers, and step a single instruction. Since, the user decides when to call these functions, these will probably fit most use-cases.

MCU

The MCU crate provides an implemenation of Memory and RegisterFile for use with the ISA simulator. With this, one can fully emulate an embedded RISC-V core.

Assembler

This crate can be used to assemble simple RISC-V assembly programs. The main functions offered by this library are:

assemble_ir: assemble an instruction &str to a u32
assemble_program: assemble a program &str to a Vec<u32>
assemble_program_buf: assemble a BufRead to a Vec<u32>

CLI

Emulator

The primary use of the emulator is tracing execution of RISC-V programs and making assertions about their behavior. It currently only supports simple binary memory images (not ELF binaries).

Enter assertions into a JSON file (note: all numbers are strings to allow for hex or decimal radices).

assert.json:

Then run:

This will execute prog.bin, stop at the PC value 0x24, and then make the assertions from assert.json.

The program will trace the execution instruction-by-instruction:

When complete, it will summarize results:

Assembler

The CLI also exposes the assembler via the command line. You can assemble the file program.s to program.bin using

lrv-cli -cv program.s -o program.bin

Testing

This project has a very flexible testing system.

Unit-tests are provided wherever appropriate.

Additionally, to test the whole system, test programs can be added to mcu/tests/programs. A test is simply a directory containing .c and .s source files and a test_case.json consisting of assertions about the state of the MCU after the program is complete.

During testing, Cargo will for each test: