Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/thoughtpolice/rv32-sail

32-bit RISC-V Emulator
https://github.com/thoughtpolice/rv32-sail

embedded haskell nix risc-v

Last synced: 2 months ago
JSON representation

32-bit RISC-V Emulator

Awesome Lists containing this project

README 

        
* rv32-sail - high-level emulator for RV32IM 🔥



[[https://img.shields.io/badge/version-1.0pre-orange.svg]] [[https://img.shields.io/badge/license-MIT-blue.svg]]



Run it *[[https://riscv.ls0f.pw][in your browser]]*, right now!



-----



~rv32-sail~ is a software emulator for a small computer that uses the [[https://risc-v.org][RISC-V]]

instruction set. While other system emulators (such as [[https://www.qemu.org][QEMU]], or [[https://github.com/rems-project/sail-riscv][sail-riscv]]) are

designed to boot systems like Linux or [[https://sel4.systems][seL4]], ~rv32-sail~ is more modest: it

currently is designed to emulate something closer to an advanced

microcontroller. (Think of it as an emulator for a system like the [[https://www.sifive.com/boards/hifive1][HiFive1]] --

not the [[https://www.sifive.com/boards/hifive-unleashed][HiFive Unleashed]].)



~rv32-sail~ does not just come with the emulator: it's more like a full Software

Development Kit, similar to some embedded microcontroller boards. It also comes

with a handy environment containing a C cross compiler, the emulator, as well as

a robust build system and test suite, and demonstrations. If you want to try

RISC-V assembly programming, write your own simple "bare metal" programs, or

extend the RISC-V instruction set, this might be for you!



#+BEGIN_QUOTE

*NOTE*: rv32-sail ships a RISC-V *software emulator*, which is an approximate

representation of the CPU as a sequential software program. It is not

"cycle-accurate" and can not model clocks, digital logic, power or area

consumption of a physical RISC-V CPU in any way! If you want to the Verilog

equivalent of ~rv32-sail~, try [[https://github.com/cliffordwolf/picorv32][picorv32]]!

#+END_QUOTE



* Features



- High-level RISC-V ISA emulator, written in [[https://www.cl.cam.ac.uk/~pes20/sail/][Sail]]

  - Clean code is paramount with lots of comments.

  - High-level, type-safe, functional-imperative description of RISC-V.

  - Part hand-written (execution engine), part generated (decoder) at

    compile time.

  - Implements all of the base RV32IM instruction set as well as a select

    amount of CSRs. Machine (M) mode only, no User (U) mode support (yet).

- Robust build system, toolchain, programming environment.

  - Global dependencies (GCC, Haskell, Sail) are provided with *[[https://nixos.org/nix][Nix]]*,

    so every dependency is taken care of for you, *on almost any Linux

    distribution*. Embedded programming toolchain nightmares are over,

    and you never fiddle with prerequisites -- and you can delete

    everything in an instant when you're done.

  - The build system is written using [[https://shakebuild.com][Shake]] -- it's fast

    and highly accurate, meaning you will (hopefully) never get out of

    date builds, broken builds, or build failures due to invalid

    dependency tracking.

  - Designed to be used incrementally and easy for contributors. Most of

    the Nix complexity is completely hidden, and the build system is

    easy as pie to use -- like a normal shell script.

  - Uses GitHub actions for continuous deployment of binary artifacts and

    examples (Docker, WebAssembly). This makes it easy for users to play.

  - When developing, you can download all the programming tools without

    compiling anything at all, thanks to [[https://cachix.org/][Cachix]]!

- Included programming tools

  - GCC 8.x with the RISC-V backend is the primary C toolchain.

  - A firmware shim library called ~libfirm~ provides the basics needed

    for setting up the environment -- initial stack allocation and calling

    your ~main~ function, etc.

  - Includes a very minimal ~libc~ that provides some of the core fundamentals

    for C programming, including basic standard headers, library functions etc.

  - Loads raw ELF binaries that can be booted and executed directly.

- Included demo code

  - Full test firmware based on [[https://github.com/cliffordwolf/picorv32][picorv32]] firmware, and upstream RISC-V assembly

    tests, for basic verification.

  - Benchmarks: both [[https://en.wikipedia.org/wiki/Dhrystone][Dhrystone]] and [[https://www.eembc.org/coremark/][CoreMark]] are built by default.

  - Fun: a full prototype FORTH implementation, based on JonesForth



Note that ~rv32-sail~ is *not* designed to be packaged for Linux distributions,

or used like -- or as an alternative to -- a real emulator such as QEMU. It is

quite slow, and it is designed for correctness and as the basis for software

stack development, with design flexibility in the simulator.



The end goal of this project is to implement a full, robust emulator for an

embedded RISC-V CPU with [[https://www.cl.cam.ac.uk/research/security/ctsrd/cheri/][CHERI extensions]], based on the paper /[[_][CheriRTOS: A

Capability Model for Embedded Devices]]/, as well as an accompanying

capability-first RTOS. (If we want to stir up our wild imaginations, such a

device could be a pure open hardware/FOSS replacement for devices like the

ESP32.)



* Table of Contents :TOC_4_gh:

- [[#rv32-sail---high-level-emulator-for-rv32im-][rv32-sail - high-level emulator for RV32IM 🔥]]

- [[#features][Features]]

- [[#quickstart][Quickstart]]

  - [[#quickstart-in-your-browser][Quickstart: In your browser]]

  - [[#quickstart-docker][QuickStart: Docker]]

  - [[#quickstart-nix-with-cachix][QuickStart: Nix with Cachix]]

- [[#building][Building]]

- [[#usage][Usage]]

  - [[#running-demos-and-tests][Running demos and tests]]

    - [[#smoke-test-firmware][Smoke-Test firmware]]

    - [[#dhrystone-and-coremark-benchmarks][Dhrystone and CoreMark benchmarks]]

    - [[#forth][FORTH]]

  - [[#basic-emulator-options][Basic emulator options]]

  - [[#emulator-configuration-options][Emulator configuration options]]

  - [[#cleaning-up][Cleaning up]]

- [[#source-code-layout][Source code layout]]

- [[#softwarefirmware-development][Software/Firmware Development]]

  - [[#programming-toolchain-support][Programming toolchain support]]

    - [[#cc][C/C++]]

    - [[#rust][Rust]]

  - [[#libfirm-starter-guide][Libfirm starter guide]]

  - [[#adding-your-own-programs][Adding your own programs]]

- [[#authors][Authors]]

- [[#license][License]]



* Quickstart



If you just want to try out the emulator and the demos at no cost, there are

three easy ways to do it: your Browser, Docker, and a [[https://nixos.org][Nix]] Cache.



** Quickstart: In your browser



As mentioned above, you can run the emulator *[[https://riscv.ls0f.pw][in your browser]]*, right now. This

requires a modern system with support for [[https://webassembly.org][WebAssembly]]. It has a neat retro UX,

using the JavaScript [[https://hterm.org][hterm]] library. It offloads all of the compiled code into a

[[https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers][Web Worker]] so the main UI thread isn't blocked, even when running "compute

intense" demos like CoreMark.



This page is automatically updated on every commit to the ~master~ branch. It

has been tested on recent Chrome (Desktop), and Safari (iOS), though mobile

input is quite glitchy right now. Firefox seems to have a WebAssembly loading

glitch that requires cache purges, and hterm integration problems; I am not sure

what extent this is inherent or just my code.



Note: The WebAssembly build is *very unstable*, moreso than the ordinary

emulator -- so don't be surprised if very basic functionality doesn't work.

Patches to help Sail WebAssembly support, hterm integration, and emscripten

updates are very welcome.



** QuickStart: Docker



There's a *Docker Container* that's automatically compiled and built (using

[[https://github.com/features/actions][GitHub Actions]]) on every commit to the ~master~ branch. You can try the emulator

immediately by running one of the included demos:



#+BEGIN_SRC language

docker run --rm thoughtpolice/rv32-sail:master -e smoke.elf

docker run --rm thoughtpolice/rv32-sail:master -e dhrystone.elf

#+END_SRC



All of the demos in the package (Dhrystone, CoreMark, etc), as well as the smoke

test firmware (~smoke.elf~) are included in the Docker container.



#+BEGIN_QUOTE



Note: The ~:master~ tag for the Docker repository is always updated when the

~master~ branch is, etc etc. There is also a tag corresponding to every git

commit, and the Nix package version (e.g. ~1.0~ or ~1.0pre_...~)



The ~:latest~ tag is reserved for stable releases -- there are no stable

releases as of now.

#+END_QUOTE



** QuickStart: Nix with Cachix



There's a *[[https://cachix.org][Cachix]] Cache* containing all the build tools as well as pre-built

copies of the emulator, updated on every commit to the ~master~ branch. Read the

"Building" section below to get started.



* Building



#+BEGIN_QUOTE

*NOTE*: You *must** have [[https://nixos.org/nix][the Nix Package Manager]] installed in order to build the

emulator! While you can install Sail and the dependencies yourself, this is the

only supported development method, and the only environment that tests, builds

etc are run with, in the main repository. Should you ignore this, I cannot help

you with any issues, and you should not be surprised if things don't work!



If you are running an x86_64 Linux distribution, using ~systemd~, and capable of

executing ~sudo~ on your machine, then you can do a quick installation easily

from your shell:



#+BEGIN_SRC bash

$ sh <(curl https://nixos.org/nix/install) --daemon

#+END_SRC



(Please read the shell script. All it does is download a tarball and execute an

actual installation script inside, and you can find [[https://github.com/NixOS/nix/tree/master/scripts][the source code for those

scripts]] as well.)



*You must pass the --daemon flag to the installer!* (If you don't, you will not

have sandboxing support enabled in Nix, which could lead to non-reproducible

builds, and other strange build failures.)



This should work on any modern Linux distribution with namespace support and

systemd as the init system. Then you can log back into your user account --

~nix~, ~nix-shell~ and other tools will now be available.



In the future, I hope to also provide static binary distributions containing

the emulator and test firmware, too.

#+END_QUOTE



Currently, the primary way to compile the emulator and firmware is to use the

build system is by simply invoking it directly using the ~bake.hs~ script. This

is designed to be as easy as possible. If you have a recent version of Nix

installed, this will essentially "just work" -- though the first invocation will

take some time (see below).



There is a binary cache available thanks to [[https://cachix.org][Cachix]] which contains copies of all

the build tools and builds from the ~master~ branch. First, as ~root~ or someone

who can ~sudo~, add yourself to ~trusted-users~, and restart the ~nix-daemon~

service:



#+BEGIN_SRC bash

grep -q "trusted-users.*$USER" /etc/nix/nix.conf ; \

    [ ! $? -eq 0 ] && echo "trusted-users = root $USER" | sudo tee -a /etc/nix/nix.conf

sudo systemctl restart nix-daemon.service

#+END_SRC



Then you can configure binary caches with a local file in

~$HOME/.config/nix/nix.conf~:



#+BEGIN_SRC bash

mkdir -p "$HOME/.config/nix"

cat > "$HOME/.config/nix/nix.conf" <