trmckay/lib-rv32

Rust library for emulating 32-bit RISC-V

This library can execute instructions against any memory and register file that implements

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:

  1. Compile it for RISC-V
  2. Spin up a new MCU
  3. Program it with the generated binary
  4. Run the test program for some number of cycles
  5. Make assertions
  6. Report succes or failure

If a test fails, it will describe the error that caused the crash or the assertion that failed and print an object dump of the compiled test binary:

Tests are run in CI, but can be run locally provided your system has riscv(32|64)-unknown-elf-gcc.

Versions

Find the latest versions by id

Information - Updated Mar 26, 2022

Stars: 12
Forks: 1
Issues: 1

Repositories & Extras

Rust RPC client for Bitcoin Core JSON-RPC

This is a Rust RPC client library for calling the Bitcoin Core JSON-RPC API

Rust RPC client for Bitcoin Core JSON-RPC

jsonpointer_flatten

Rust library to flatten a JSON object using JSON Pointer field addressing as defined in

jsonpointer_flatten

JSON-RPC library designed for async/await in Rust

Designed to be the successor to tracking issue for next stable release (0

JSON-RPC library designed for async/await in Rust

tinyjson is a library to parse/generate JSON format document

Rust stable toolchain (no dependency)

tinyjson is a library to parse/generate JSON format document

Introduction to JsonPath

The library provides the basic functionality to find the set of the data according to the filtering query

Introduction to JsonPath

A simple JSON library

This is a simple JSON library I wrote for one of the

A simple JSON library

A library for writing colored JSON output to a termcolor terminal

A library for writing colored termcolor terminal

A library for writing colored JSON output to a termcolor terminal

Rust's standard library offers

display_json is a crate that allows you to easily integrate

Rust's standard library offers

A Rust library for safely extracting JSON fields while also checking data bounds

Obtain an SQL schema from the Database being used (it should contain the table creation SQL)

A Rust library for safely extracting JSON fields while also checking data bounds

jsonm implementation port for Rust

Original library written in JS is here:

jsonm implementation port for Rust

Lexical JSON number types

This is a simple library for parsing and storing JSON numbers according

Lexical JSON number types
Facebook Instagram Twitter GitHub Dribbble
Privacy