rustsbi

RustSBI

RISC-V Supervisor Binary Interface (SBI) library in Rust; runs on M-mode or HS mode.

Binary downloads

Most users would get RustSBI binary download from the RustSBI Prototyper. Check out the documents here to build or download images for supported platforms.

Boards, SoC vendors and research groups may sometimes provide dedicated RustSBI package for supported platforms. There are packages exists on awesome-rustsbi: it is a curated list of awesome things related to RustSBI, which includes some implementation projects maintained by individuals or the community.

Users on commercial boards may visit implementation specific distribution links depending on the platforms they need, or consult vendors if they provide discrete RustSBI package support.

Rust toolchain policy

All crates under library/ support Rust 1.88 or later on their supported targets. Each crate inherits this minimum supported Rust version (MSRV) from the root Cargo.toml. With both the MSRV and current stable Rust, 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 RustSBI Prototyper, uses the date-pinned nightly toolchain in rust-toolchain.toml. rustup selects it automatically for commands run in this repository.

Build this project

Native development

For firmware user

If you need to build RustSBI firmware for M-mode, please refer to the RustSBI Prototyper documentation.

For library user

RustSBI is usually used as a library or dependency. If you wish to, you may build RustSBI library itself using the following command:

cargo build

The build should finish without any errors.

Building under native platform will allow development of hypervisors and emulators. To check the libraries on RISC-V with stable Rust, install the target for that toolchain and cross-build:

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

The target platform of RISC-V platform firmware is usually a bare metal target. Under normal circumstances these targets in Rust would start with riscv??- and end with -none-elf.

Or use the Docker development environment

The repository provides a Docker image for development on hosts that do not match the CI environment. It includes the pinned nightly toolchain, RISC-V targets, QEMU, U-Boot tools and cargo-binutils.

For a one-off check, run:

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

For an interactive shell, run:

docker run --rm -it -v "$PWD:/workspace" -w /workspace rustsbi-dev bash

The source tree is mounted at /workspace; changes and build artifacts stay on the host.

Features

• Feature rich and extensible operating system runtime
• Empower support, compatibility for machines, hypervisors and emulators
• Support to and develop with RISC-V SBI specification v2.0 ratified
• Libraries support stable Rust
• Capable to develop with other firmware ecosystem projects
• Adapted for operating system kernel models on your choice
• Included a LLM based Agent module called RustSBI Agent (https://github.com/rustsbi/Agent), which is designed to assist system software developers in their development process

Frequently asked questions

1. How would I build a RustSBI implementation?

RustSBI have extensive documents on such purposes! No matter what you are building with it, you will find some documents about RustSBI on bare-metal environments, hypervisors and emulators.

Check it out at RustSBI document main page.

1. Can I use RustSBI on C based kernels?

Yes, you can! RustSBI strictly follows RISC-V SBI standard. All features are prepares for all programming languages, as long as they support RISC-V SBI defined calling convention.

If your kernel language supports other SBI implementations, usually it will support RustSBI in the same way.

Talks and documents

This project is originally a part of rCore Summer of Code 2020 activities, inspired by MeowSBI and other similar projects. Now it is capable of running rCore-Tutorial and other OS kernels on wide supported RISC-V devices.

There are multiple talks related to RustSBI dated back to Aug 2020. These talks discuss from design and abstraction of RustSBI modules, to actual production and research usage scenario related to RustSBI and RISC-V bootloaders. Public slides and blog articles of these talks are available at RustSBI/slides page.

Notes on platform implementation

1. RustSBI should be used as a library. Under normal circumstances, RustSBI platform can be implemented with embedded Rust's embedded-hal libraries.
2. Contributions are welcomed! We welcome to implement and test RustSBI for both FPGA cores and real cores. Implementations for emulators are also welcomed. If you are ready, start your own binary project and use RustSBI in it!
3. If there is a bug in RustSBI project itself, fire an issue or pull request to let us know!

Security

Please see our Security Policy for information on how to report security vulnerabilities.

Sponsors

The RustSBI project is sponsored by multiple institutions, companies, and individuals.

Individual sponsors (by order of donation):

Chao Liu
(@zevorn)	Zhenchen Wang
(@Plucky923)	Zongyao Chen
(@chenzongyao200127)

License & Copyright

This project is licensed under either of

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Mulan PSL v2 (LICENSE-MULAN or https://opensource.org/licenses/MulanPSL-2.0)

Documents from RISC-V SBI Specification are used in this project. These documents are (C) RISC-V Foundation under Creative Commons Attribution 4.0 International License (CC-BY 4.0). The full license text is available at https://creativecommons.org/licenses/by/4.0/.