d0iasm/rvemu - RISC-V online emulator with WebAssembly generated by Rust

rvemu: RISC-V Online Emulataor

RISC-V online emulator with WebAssembly generated by Rust. The emulator implements the standard extensions RV64G (RV64IMAFD, Zicsr, Zifencei) and complies with the RISC-V specifications .

The online emulator is available here:

• rvemu.app : Run a RISC-V binary you uploaded.
• rvemu.app/xv6 : Run xv6 .

The emulator supports the following features:

• RV64G ISAs
  • RV64I (v2.1): supports 52/52 instructions (FENCE, ECALL and EBREAK do nothing for now)
  • RV64M (v2.0): supports 13/13 instructions
  • RV64A (v2.1): supports 22/22 instructions (No atomicity for now)
  • RV64F (v2.2): supports 30/30 instructions
  • RV64D (v2.2): supports 32/32 instructions
  • Zifencei (v2.0): supports 1/1 instructions (FENCE.i does nothing for now)
  • Zicsr (v2.0): supports 6/6 instructions (No atomicity for now)
• RV64C ISAs
• Privileged ISAs: supports 7/7 instructions (WFI, SFENCE.VMA, HFENCE.BVMA and HFENCE.GVMA do nothing for now)
• Control and status registers (CSRs)
  • Machine-level CSRs
  • Supervisor-level CSRs
  • User-level CSRs
• Virtual memory system (Sv39)
• Devices
  • UART: universal asynchronous receiver-transmitter
  • CLINT: core local interruptor
  • PLIC: platform level interrupt controller
  • Virtio: virtual I/O

These features are compliant with "The RISC-V Instruction Set ManualVolume I: Unprivileged ISADocument Version 20191213" and "The RISC-V Instruction Set ManualVolume II: Privileged ArchitectureDocument Version 20190608-Priv-MSU-Ratified".

Usage

You can run xv6 , a simple Unix-like operating system, in rvemu.app/xv6 .

You also be able to run an arbitrary RISC-V binary in rvemu.app . The online emulator supports the following commands:

• upload : Upload local RISC-V binaries for the execution on the emulator.
• ls : List the files you uploaded.
• run [file] : Execute a file which you uploaded or some files are already embedded.
• help : Print all commands you can use.

See the "Build RISC-V binary" section for more information.

Build and run on the local browser

The wasm-pack build command generates a pkg directory and makes Rust source code into .wasm binary. It also generates the JavaScript API for using our Rust-generated WebAssembly. The toolchain's supported target is wasm32-unknown-unknown . You need to execute this command whenever you change your Rust code.

$ make rvemu-wasm
// This is the alias of `wasm-pack build lib/rvemu-wasm --out-dir <path-to-rvemu>/public/pkg --target web`.

This command installs dependencies in the node_modules directory. Need npm install --save in the public directory at the first time and whenever you change dependencies in package.json.

$ npm install --save // at the public directory

You can see the website via http://localhost:8000 . npm start is the alias of python3 -m http.server so you need Python3 in your environment.

$ npm start // at the public directory

Build and run as a CLI tool

The emulator can be executed as a CLI tool too. You can build it by make rvemu-cli command which is the alias of cargo build --release --manifest-path lib/rvemu-cli/Cargo.toml .

To execute the RISC-V ELF binary, xv6 in the folloing example, you can use --kernel or -k options to specify the kernel image. Note that xv6-kernel.text is an ELF file without headers by the command riscv64-unknown-elf-objcopy -O binary kernel xv6-kernel.text

$ ./target/release/rvemu-cli -k examples/xv6-kernel.text -f examples/xv6-fs.img

You can see the details of how to use by the help option.

$ ./target/release/rvemu-cli --help
rvemu: RISC-V emulator 0.0.1
Asami Doi <@d0iasm>

USAGE:
    rvemu-cli [FLAGS] [OPTIONS] --kernel <kernel>

FLAGS:
    -d, --debug      Enables to output debug messages
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -f, --file <file>        A raw disk image
    -k, --kernel <kernel>    A kernel ELF image without headers

Build RISC-V binary

The emulator starts to execute at the address 0x8000_0000, the start address of DRAM, so you need to extract .text section and place it to the address.

// Make an assembly file from a C file.
$ riscv64-unknown-elf-gcc -S -nostdlib hoge.c
// Make a binary file from an assembly file with start position 0.
$l riscv64-unknown-elf-gcc -Wl,-Ttext=0x80000000 -nostdlib -o hoge hoge.s
// Extract a text section from a binary file.
$ riscv64-unknown-elf-objcopy -O binary hoge hoge.text

Testing

You can see the binaries for unit testings in riscv/riscv-tests . The following command executes all rv64ua/d/f/i/m-p-* binaries. TODO: not all tests are passed for now.

$ make test

Analyzing with perf

$ perf record -F99 --call-graph dwarf ./target/release/rvemu-cli -k examples/xv6-kernel.text -f examples/xv6-fs.img
$ perf report

Publish

The site is hosted by a firebase.

$ firebase deploy

Dependencies

• wasm-pack
• npm
  • xterm
  • xterm-addon-fit

Resources

Documents

• RISC-V Specifications
• Rust and WebAssembly
• riscv/riscv-sbi-doc
• riscv/riscv-elf-psabi-doc
• riscv/riscv-asm-manual

Implementation of other emulators

• qemu/qemu
• riscv/riscv-isa-sim
• riscv/riscv-angel
• riscv/riscv-ovpsim
• rv8-io/rv8
• TinyEmu
• stephank/rvsim

Helpful tools

• riscv/riscv-tests
• wat2wasm demo
• RISC-V Online Simulator

Articles about this project

• Emulate 32-Bit And 64-Bit RISC-V In Your Browser With Asami’s Open Source rvemu | Gareth Halfacree, Hackster.io
• Emulate 32-Bit and 64-Bit RISC-V in Your Browser with Asami's Open Source rvemu