takahirox/riscv-rust

RISC-V processor emulator written in Rust+WASM

riscv-rust

riscv-rust is a RISC-V processor and peripheral devices emulator project written in Rust and compiled to WebAssembly. You can import RISC-V emulator into your Rust or JavaScript project. Refer to the Slides for more detail.

Online Demo

You can run Linux or xv6 on the emulator in your browser. Online demo is here

Screenshots

Documents

• Document

Features

• Emulate RISC-V processor and peripheral devices
• Stable as Linux and xv6-riscv run on it
• Linux OpenSBI and legacy BBL boot support
• Runnable locally
• Also runnable in browser with WebAssembly
• Debugger
• You can import RISC-V emulator into your Rust or JavaScript project

Instructions/Features support status

• RV32/64I
• RV32/64M
• RV32/64F (almost)
• RV32/64D (almost)
• RV32/64Q
• RV32/64A (almost)
• RV64C/32C (almost)
• RV32/64Zifencei (almost)
• RV32/64Zicsr (almost)
• CSR (almost)
• SV32/39
• SV48
• Privileged instructions (almost)
• PMP

etc...

The emulator supports almost all instructions listed above but some instructions which are not used in Linux or xv6 are not implemented yet. Your contribution is very welcome.

How to import into your Rust project

The emulator module is released at crates.io. Add the following line into Cargo.toml of your Rust project.

[dependencies]
riscv_emu_rust = "0.2.0"

Refer to Document for the API.

How to build core library locally

$ git clone https://github.com/takahirox/riscv-rust.git
$ cd riscv-rust
$ cargo build --release

How to run Linux or xv6 as desktop application

$ cd riscv-rust/cli
# Run Linux
$ cargo run --release ../resources/linux/opensbi/fw_payload.elf -f ../resources/linux/rootfs.img
# Run xv6
$ cargo run --release ../resources/xv6/kernel -f ../resources/xv6/fs.img

How to run riscv-tests

Prerequirements

• Install riscv-gnu-toolchain
• Install riscv-tests

$ cd riscv-rust/cli
$ cargo run $path_to_riscv_tets/isa/rv32ui-p-add -n

How to import and use WebAssembly RISC-V emulator in a web browser

See wasm/web

How to install and use WebAssembly RISC-V emulator npm package

See wasm/npm

Links

Linux RISC-V port

Running 64- and 32-bit RISC-V Linux on QEMU

xv6-riscv

xv6-riscv is the RISC-V port of xv6 which is UNIX V6 rewritten by MIT for x86 in the current C language.

Specifications

• RISC-V ISA
• Virtio Device
• UART
• CLINT, PLIC (SiFive E31 Manual)
• SiFive Interrupt Cookbook

riscv-rust's Issues

Support SV48

Disk access ring buffer doesn't seem to be released correctly on Linux

Disk access ring buffer doesn't seem to be released correctly on Linux.

Currently setting virtio block device queue size big enough as workaround so far. We should figure out and resolve the root issue.

Write readme

Simpler decoding

We may simplify decoding with the sets of mask and data. For example decoding ADDI instruction can be written as

if (word & 0x0000707f) == 0x00000013 {
  return Instruction::ADDI;
}

then we may rewrite decode function with loop

// pseudo-code
for d in decoding_sets {
  if (word & d.mask) == d.data {
    return d.instruction;
  }
}

CLI Terminal should handle special characters input correctly

For example, cursor and delete keys.

Run peripheral devices in another thread

It'd be good to run peripheral devices in another thread for the performance. For example currently terminal emulator handling input (and output) runs in the same thread so that main thread needs to periodically check input event but it seems to have an impact to the performance. If it runs in another thread it can improve the performance.

This is also important for Web. For not only catching input but also rendering the output the main thread periodically needs to sleep with setTimeout(). It can have a big performance impact. Maybe we can load off riscv emulator to workers thread and share UART registers between main and worker threads.

Disk access fails if timer interrupt happens while booting up Linux

Disk access fails if timer interrupt happens while booting up Linux. Currently disable timer interrupt until likely Linux boots as workaround but we should figure out the root issue and fix.

Enable accessing memory wider than a byte at a time

Currently the emulator accesses memory one byte at a time. For examples it access memory four times to get 32-bit instruction.

It would be a good optimization to enable accessing memory wider than a byte at a time (in case where it is ensured that all the accessed bytes are in the same page and they all are not mapped to other devices).

Directly get tohost address for riscv-tests

by analyzing symbols because some tests uses non 0x80001000 for tohost.

Implement RV32C

Investigate the performance of Rust exception handling

I'm not really sure about if it is changed but it is used be said that try-catch is slow in most (or all) languages even if it goes on non-exception flow.

We need to investigate Rust exception handling performance using

fn foo() -> Result<u64, Error> {
    ...
}

match foo() {
    Ok(result) => result,
    Err(e) => return Err(e)
};

because it's used a lot in the emulator. For example it is used to notify and catch page fault.

If it's slow we may need to think of other options.

Run modern Operating System

I'd like to try to run more modern Operating System on the emulator, for example Linux, OpenBSD, or FreeBSD.

Handle csr *ip properly

Currently the emulator takes an interrupt by seeing the device interrupt signal. But the interrupt signal should rise csr *ip register bit and the emulator should take an interrupt if csr *ip register bit is risen.

And csr *ip register can be writable. If it's writable software should be able to cause an interrupt by writing.

Release online demo with WASM compile

Support physical memory protection

Implement RV64I

stressfs of xv6 doesn't end

stressfs of xv6 doesn't end. I guess that's because virtio block disk emulation is something wrong.

$ usertests
stressfs starting
write 0
write 1
write 2
write 3
write 4

Implement RV32/64F

rv64ui-p-auipc fails

Write note about how to build Linux for riscv-rust

RISC-V's vector V extension? :)

It might be great to implement it so further applications may rely on this feature for further development :)

Implement RV32/64M

Implement privileged instructions

Emulate peripheral devices more properly

The currently peripheral device emulation is a bit too specific to xv6-riscv device drivers, for example ignoring some peripheral device accesses which may not have an effect to xv6-riscv.

We should emulate more properly because it can be broken if they update xv6-riscv device drivers, or other programs may fail.

Support 64-bit mode

Take CPU performance profile to figure out the hotspot

As you know, the emulator is not fast enough yet. For example it takes time to boot xv6. Taking CPU performance profile would be a good start to figure out the hotspot.

Multi hardware threads support

Maybe time sharing approach is a good start?

// pseudo code
for i 0..n {
  self.threads[i].tick();
}

Peripheral devices should be configurable by device tree file

Peripheral devices should be configurable by device tree file but currently the configurations (Memory map, IRQ number, and so on) are hardcoded in the emulator.

Another option is we hardcode the device tree in the emulator.

Binary translation

Support virtio multi queue requests

Network support on Linux

Some tests in xv6 usertests fail

Consider to rename repository

I realized the name riscv-rust is already used as a project name by official risc-v. So my repository name riscv-rust may be confusing and it would be better to rename.

Refactoring and clean up

Implement MMU

Add debugging feature to cli

disassemble, break point, step execution, etc

Implement LR/SC instructions properly

Enable to run test again without second argument

Currently cli application takes two arguments kernel image file and filesystem image file. But the second argument filesystem image file is xv6 specific and shouldn't be necessary for running tests. We should enable run (test) without second argument.

Skip redundant address tranlation

The emulator accesses memory one byte at a time. For example it accesses memory four times to get a 32-bit instruction.

It can have a big performance impact especially if virtual-physical memory address translation is on because the translation can be one of the slowest operation in the emulator.

So it would be a good optimization to skip redundant address translation. For example we can have translation table cache.

Rewrite to modern, standard, optimized Rust coding style

I guess there may be a big room for rewriting the code to more modern, standard, and optimized Rust coding style.

I'm very happy if you give feedback and help me because I'm still new to Rust.

Write note about how to build xv6-riscv for riscv-rust

I should write a note about the files in xv6 directory.

• xv6-riscv kernel file in xv6 directory (xv6/kernel) is built without C extension because the emulator doesn't support C extension yet. I added -march=rv64imafd compile/assemble option in Makefile of xv6-riscv. And also I edited initcode in kernel/proc.c to convert to non-C extension instructions. Plus, I added -O3 compile option to get better performance.
• xv6-riscv filesystem image file (xv6/fs.img) is made by make qemu of xv6-riscv

Load/Store rv32ui-v-* tests fail

Send feedback to riscv-tests

While working on Linux support I found some bugs in the CPU instruction implementations although I already passed riscv-tests. I think better to send feedback to riscv-tests for better coverage.

Linux freezes if running vi

Cache decode

Caching decode result would be a good optimization. Especially it would work well in loop.

// pseudo code
let instruction = match decode_cache.has(word) {
  true => {
    decode_cache.get(word)
  },
  false => {
    let instruction = self.decode_internal(word);
    decode_cache.set(word, instruction);
    decode_cache.remove_lru();
    instruction
  }
};

Enable running riscv-tests in online demo

One challenging is how to display logs on the terminal. Via UART?

pipe fails in xv6

How to reproduce in xv6.

$ cat README | wc

Error message.

Unknown Instruction type.
Pc:00000000000004f0, Opcode:0000000, Word:0000000000000000
thread 'main' panicked at 'explicit panic', src\cpu.rs:1022:17
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
error: process didn't exit successfully: `target\release\standalone.exe xv6/kernel -f xv6/fs.img` (exit code: 101)

Pass all riscv-tests/rv32ui-p-*

Currently passed 15/39

Implement RV32/64A

Rename project name

I may want to rename the project name from rust-riscv to riscv-rust at some point. (I don't remember why I named rust-riscv...)