riscv.zig

A fast-ish interpreted RISC-V emulator, in pure Zig.

About:

riscv.zig is a work in progress RISC-V emulator, soon-to-be available as both a library that can be implemented in other projects and as a standalone application. The goal is to be as flexible as reasonably possible, supporting most (if not all) major ISA extensions. It also aims to be performant, at least for an interpreted emulator. (I plan to implement JIT compilation using GNU Lightning, and maybe even KVM later on.)

Warning

riscv.zig is currently in heavy development, and is not in a usable state whatsoever. It probably can't even compile yet. As such, until I can get it into a usable state, all pushes and commits will be put into the main branch.

Installation:

The project tracks the latest stable releases of Zig, currently at 0.15.2. You will need the relevant version to use, and I strongly recommend you use anyzig to help with that. To clone and compile:

# You can also use ssh if you want:
git clone https://github.com/WGrav01/riscv.zig.git

cd riscv.zig

# To compile the library and app (the app is not implemented yet!):
zig build

# To run tests:
zig test

# To run the exe:
./zig-out/bin/riscv_zig

How to add the library to an existing project

1. Run zig fetch --save git+https://github.com/WGrav01/riscv.zig.git. You should then see the library in your build.zig.zon.
2. Add to your build.zig:

   const riscv = b.dependency("riscv_zig", .{
           .target = target,
           .optimize = optimize,
   });

   And, before installArtifact is called: (this assumes your main module is called exe)

   exe.root_module.addImport("riscv", riscv.module("riscv"));

3. Now, you can use the library in your project

   const riscv = @import("riscv");

4. Profit

Documentation

You can run the following to build the documentation to zig-out/docs/:

zig build docs

Additionally, you can append -Dno-emit-bin to prevent the Zig compiler from outputting a binary along with the docs. Then, in zig-out/docs/, run python -m http.server to host the documentation at 0.0.0.0:8080. The official documentation as well is available on Github Pages, and is generated every midnight. (at UTC time) I plan to implement snapshots for every tag as well.

Note

There is also a DeepWiki available, but keep in mind it is entirely AI generated. I have no control over the contents of the wiki. While it can be useful, ultimately the Github Pages site and this Readme is the authoritative documentation for this project.

Usage:

Coming soon, once I have an actual implementation of the library.

Roadmap:

Feature	Status
RV32 support	In progress
RV32i support	Planned
RV64 support	Planned
RV128 support	Planned
ISA extensions	Status table coming soon
JIT compilation	Planned
libvirt	Possibly? Stretch goal
GDB server	Likely, not sure yet
Assembler	Possibly? Stretch goal
Disassembler	Possibly? Stretch goal

Contributing:

PRs and help is welcome! Please open an issue however before any major contributions however, so that I can evaluate your proposed change and not waste your time. In addition, any PR that does not use Conventional Comments will be rejected.

Support:

I will be happy to help you. However, please do not open an issue unless you are confident that your problem is an enhancement, bug, or something to change. Use discussions instead.

Licensing:

This project is licensed under the MIT License. You can view it in this repository here.

Credits:

• Inspired heavily by mini-rv32ima.
• A lot of info used from fmash16's project.
• As well as from Writing a RISC-V Emulator in Rust.
• Huge thanks to Andrew Kelly for creating the Zig language.

And many thanks to the contributors!

WGrav

Contributor table made with jaywcjlove/contributors.