# RustSBI gives Rust kernels a RISC-V supervisor interface

> RustSBI is an implementation of the RISC-V Supervisor Binary Interface in Rust, structured so the specification layer, the runtime and the firmware are separate crates, with a Prototyper to build the actual images. It runs in M mode or HS mode, it is built on stable Rust for its libraries, and the firmware part uses a pinned nightly toolchain.

**rustsbi/rustsbi** — RISC-V Supervisor Binary Interface (RISC-V SBI) library in Rust; runs on M or HS mode; good support for embedded Rust ecosystem. For binary download see firmware folder.

- Repository: https://github.com/rustsbi/rustsbi
- Stars: 1,336 · Forks: 180
- Language: Rust
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/rustsbi-rustsbi

## The interface a supervisor exposes to a kernel

The RISC-V Supervisor Binary Interface is the contract between a RISC-V operating system or hypervisor and the firmware underneath it. When a kernel wants to set a timer, read a counter, or ask the platform to shut down, it does not touch a hardware register directly, it makes an SBI call, and the firmware below decides how to do it.

RustSBI is an implementation of that interface in Rust, and the readme states that it runs on M mode or HS mode. M mode is the machine mode, the most privileged state, which is where a supervisor sits when it is the only thing running, and HS mode is the hypervisor extended supervisor mode that the hypervisor extension adds. Running in both means the same code can serve as the firmware under a kernel and as the firmware under a hypervisor.

The feature list calls it a feature rich and extensible operating system runtime, and lists support for and development against the RISC-V SBI specification v2.0 as ratified, compatibility for machines, hypervisors and emulators, and libraries that support stable Rust. It also says it is capable to develop with other firmware ecosystem projects, and that it is adapted for operating system kernel models of your choice.

The audience is system software developers on RISC-V: people writing kernels, hypervisors, or the firmware that those kernels run on. And the readme says it explicitly, that RustSBI should be used as a library, and that under normal circumstances the platform can be implemented with the embedded Rust embedded-hal libraries.

## A library first, and the firmware built on top of it

There is a clear division in the project between the part you depend on and the part you might build.

The library side is what most people use. The documentation says RustSBI is usually used as a library or dependency, and that you may build the library itself with cargo build, and that building under a native platform will allow development of hypervisors and emulators. The library crates are the ones that inherit the minimum supported Rust version and that CI checks on the host and on real RISC-V targets.

The firmware side is the RustSBI Prototyper, and the readme points firmware users at its documentation. The Prototyper is what turns the library into an image that a board can boot, and the release list shows why it matters: there are tagged releases named after specific targets, a v0.0.0-alpha.1-milkv-duo which is described as the RustSBI Prototyper with U-Boot for the Milk-V Duo, and a v0.0.0-oscomp-2020 which is the Prototyper for OSCOMP.

And for most users the readme says the answer is the Prototyper, that most users would get the RustSBI binary download from the RustSBI Prototyper, with documents for building or downloading images for supported platforms. For boards, SoC vendors and research groups that ship their own package there is the awesome-rustsbi list, described as a curated list of awesome things related to RustSBI including implementation projects maintained by individuals or the community, and for commercial boards the readme points at implementation specific distribution links or at the vendor.

So there are three consumption routes, and the project is explicit about which is which: the Prototyper for the common case, a board or vendor package for a specific platform, and the library itself if you are writing the platform layer.

## Eleven library crates and four firmware crates in one workspace

The Cargo manifest at the root is where the architecture becomes visible, because the workspace members are the design.

The library members are library/macros, library/sbi-rt, library/sbi-spec, library/sbi-testing, library/rustsbi, library/riscv-aia, library/riscv-cove, library/riscv-cove-rt, library/rpmi, library/penglai, library/pmpm and library/smm. The firmware members are firmware/runtime, firmware/runtime/macros, firmware/runtime/lib/csr, firmware/prototyper, firmware/bench-kernel and firmware/test-kernel, plus the xtask crate that drives the build.

The names describe the layering. sbi-spec is the specification layer, the types and the constants that describe the SBI calls. sbi-rt is the runtime support, macros is the macro layer, and sbi-testing is the harness. Then the extension crates, riscv-aia for the advanced interrupt architecture, riscv-cove and riscv-cove-rt for the counter vector extension, rpmi for the platform management interface, penglai, pmpm for the platform memory management, and smm for the secure machine manager. The main rustsbi crate ties them together, and the last two, bench-kernel and test-kernel, exist so the firmware has something to run against.

The manifest also encodes the working policy. The default members are the host-testable libraries, and a comment says that sbi-testing is checked on RISC-V targets in CI while the firmware is built through xtask, so a plain cargo build in the root does not try to compile bare metal firmware. The release profile sets debug = true for the whole workspace, and codegen-units = 1 for the prototyper and the firmware runtime, which is the usual way to get reproducible optimisation for the code that ends up in a boot image. The only two workspace dependencies are fdt, the flattened device tree parser, and the riscv crate at 0.16.1.

The edition is 2024 and the minimum supported Rust version is 1.88.

## Building it natively, cross compiling, or in a container

Three build paths, and the readme gives the commands for each.

Building the library on the host is the simple one, and the readme says the build should finish without any errors:

```bash
cargo build
```

To check the libraries on RISC-V with stable Rust, you add the target and cross build, and the note in the readme explains why this matters: the target platform of RISC-V platform firmware is usually a bare metal target, and under normal circumstances those targets start with riscv and end with none-elf.

```bash
rustup target add --toolchain stable riscv64imac-unknown-none-elf
cargo +stable build --locked --target riscv64imac-unknown-none-elf
```

And the container route, for hosts that do not match the CI environment. The image includes the pinned nightly toolchain, the RISC-V targets, QEMU, the U-Boot tools and cargo-binutils.

```bash
docker build -t rustsbi-dev .
docker run --rm -v "$PWD:/workspace" -w /workspace rustsbi-dev cargo check
```

For an interactive shell the same mount is used with a shell instead of the check command. The readme notes that the source tree is mounted at /workspace and that changes and build artifacts stay on the host, which is the behaviour you want from a development container.

The toolchain policy explains the split between the two Rust versions. All crates under library/ support Rust 1.88 or later on their supported targets, each crate inheriting the minimum supported Rust version from the root Cargo.toml, and CI tests the host-compatible libraries, checks every library on RV64IMAC with all features, and checks the RV32IMAC-compatible libraries on RV32IMAC. Repository-wide development, including the Prototyper, uses the date-pinned nightly toolchain in rust-toolchain.toml, and rustup selects it automatically for commands run in the repository.

## The Prototyper, the agent module, and the spec version

Two features stand out for anyone evaluating the project, and one of them is unusual enough to name carefully.

The first is the Prototyper, which is where the firmware side of the project meets real hardware. The readme frames the distribution problem honestly: most users get the binary from the Prototyper, boards and vendors may ship a dedicated package for their platform, and users on commercial boards can visit implementation specific distribution links or consult the vendor. The two named target releases, one for the Milk-V Duo with U-Boot and one for OSCOMP, show the pattern of a platform release built from the same codebase with a different bring-up.

The second is the RustSBI Agent, described in the feature list as an LLM based Agent module called RustSBI Agent, hosted in a separate repository under rustsbi, and designed to assist system software developers in their development process. That is a documentation and tooling aid rather than part of the SBI interface, and it is the one item in the feature list that is about the developer rather than the runtime.

The rest of the feature list is about reach. Support to and develop with RISC-V SBI specification v2.0 ratified is the headline, and the FAQ reinforces the portability claim from a different angle: yes, you can use RustSBI on C based kernels, because RustSBI strictly follows the RISC-V SBI standard, and all features are prepared for all programming languages as long as they support the RISC-V SBI defined calling convention. If your kernel supports another SBI implementation, it will usually support RustSBI in the same way.

And the origin story is worth knowing. The project was originally part of the rCore Summer of Code 2020 activities, inspired by MeowSBI and similar projects, and it is now capable of running rCore-Tutorial and other OS kernels on a wide range of supported RISC-V devices.

## Dual licensing, an MSRV, and where RustSBI is the wrong tool

The licensing is unusually accommodating for a firmware project. The project is licensed under either of the MIT license, with LICENSE-MIT at the root, or the Mulan PSL v2, with LICENSE-MULAN, and the Cargo manifest expresses the same as MulanPSL-2.0 OR MIT. The Mulan PSL is the permissive licence used in the Chinese open source ecosystem, and offering both is a practical way to be usable in more supply chains.

The readme also records that documents from the RISC-V SBI Specification are used in the project, and that those documents are copyright the RISC-V Foundation under the Creative Commons Attribution 4.0 International Licence. That is the right way to handle it, and it is the kind of attribution a company doing a licence scan will want to find rather than discover.

The limitation is architectural rather than a bug. RustSBI is a Rust implementation, so if your kernel is written in another language, you are adding a Rust component to the boot path, and although the calling convention is language neutral, the build and update story is not. The readme is clear that RustSBI should be used as a library, that the platform is normally implemented with embedded-hal, and that contributors are welcome to implement and test RustSBI for FPGA cores and real cores, and for emulators, and that if you want your own binary project you should start it and use RustSBI in it.

In other words, the project is a set of building blocks for people who are writing Rust or who are comfortable adding Rust to a firmware build. It is not a drop-in blob for a board that already has a working bootloader, and for a commercial board the readme's own advice is to consult the vendor. There is a security policy in SECURITY.md for reporting vulnerabilities, and the project is sponsored by multiple institutions, companies and individuals, with individual sponsors listed by name.

## Conclusion

RustSBI is worth adopting if you are writing a RISC-V operating system or hypervisor in Rust and you want the supervisor interface handled by an existing implementation rather than by you, because the workspace separates the specification layer, the runtime and the per platform crates, and the library side builds on stable Rust. It is the wrong choice if your kernel is not written in Rust and you do not want a Rust component in the boot path, and it is the wrong choice if you need a single vendor supplied binary for every platform, since the readme says most users get their binary from the Prototyper or from a board vendor. Before you start, read the RustSBI document main page on docs.rs, confirm the platform you need is in the supported list, and note that the current release is v0.4.1 from 2026-05-13 with the repository pushed to on 2026-10-14.

## FAQ

### What is RustSBI and which RISC-V modes does it support?

It is a RISC-V Supervisor Binary Interface library written in Rust, and the readme states that it runs on M mode or HS mode. It supports and is developed against the RISC-V SBI specification v2.0 as ratified, and it is compatible with machines, hypervisors and emulators.

### How do I build the RustSBI library?

With cargo build on the host, which the readme says should finish without errors, or by cross building for RISC-V with rustup target add --toolchain stable riscv64imac-unknown-none-elf followed by cargo +stable build --locked --target riscv64imac-unknown-none-elf. There is also a Docker development image for hosts that do not match CI.

### Where do most users get a RustSBI binary?

From the RustSBI Prototyper, according to the readme, which builds or downloads images for supported platforms. Boards, SoC vendors and research groups may ship their own dedicated package, and there is an awesome-rustsbi list of implementation projects maintained by individuals or the community.

### Can RustSBI be used from a C based kernel?

Yes. The readme says RustSBI strictly follows the RISC-V SBI standard, that all features are prepared for all programming languages as long as they support the RISC-V SBI defined calling convention, and that a kernel supporting another SBI implementation will usually support RustSBI the same way.

### What licence is RustSBI under?

Either of the MIT license or the Mulan PSL v2, with both files in the repository and the Cargo manifest declaring MulanPSL-2.0 OR MIT. The readme also records that documents from the RISC-V SBI Specification are used in the project under the Creative Commons Attribution 4.0 International Licence from the RISC-V Foundation.

## Sources

- [Issues](https://github.com/rustsbi/rustsbi/issues)
- [License: MIT](https://github.com/rustsbi/rustsbi/blob/main/LICENSE)
- [README](https://github.com/rustsbi/rustsbi/blob/main/README.md)
- [Releases](https://github.com/rustsbi/rustsbi/releases)
- [rustsbi/rustsbi on GitHub](https://github.com/rustsbi/rustsbi)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rustsbi-rustsbi