# rvemu
[![Build Status](https://travis-ci.com/d0iasm/rvemu.svg?branch=master)](https://travis-ci.com/d0iasm/rvemu)  
RISC-V online emulator with WebAssembly generated by Rust. The instruction sets in this emulator complies "The RISC-V Instruction Set ManualVolume I: Unprivileged ISADocument Version 20191213".

__NOTE: This project is currently under intensely development. The source code might be changed dramatically.__

https://riscvemu.web.app/

Supports the following RISC-V ISA features (RV64G):
- RV32I (v2.1): supports 40/40 instructions (FENCE, ECALL, and EBREAK don't do anything for now)
- RV64I (v2.1): supports 12/12 instructions (SLLI, SRLI, and SRAI are included in RV32I)
- RV32M/RV64M (v2.0): supports 13/13 instructions
- RV32A/RV64A (v2.0): supports 22/22 instructions (no unittests and no atomicity)
- RV32F/RV64F (v2.2): supports 30/30 instructions
- RV32D/RV64D (v2.2): supports 32/32 instructions
- Zifencei (v2.0): supports 1/1 instructions (FENCE.i doesn't do anything for now)
- Zicsr (v2.0): supports 6/6 instructions (no unittests and no atomicity)

# Usage
The emulator supports the following commands:
- __upload__: Upload a local RISC-V binary/local RISC-V binaries for an execution on the emulator.
- __ls__: List the files you uploaded.
- __run [file]__: Execute a file.
- __help__: Print all commands you can use.

![Demo](https://raw.githubusercontent.com/d0iasm/rvemu/master/demo.gif)

## Build and Run
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.
```
$ wasm-pack build --out-dir 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
```

## Test
You need to install a Firefox browser, a Chrome browser, or a Safari browser to test the project. A browser can be specified by a `--firefox` or a `--chrome` flag.
```
$ wasm-pack test --headless --firefox
```

## Debug
It's a tricky way to debug this project. These is no binary to execute in a console because wasm-bindgen usually needs a browser, so use a unit test instead to print messages to a console.
```
$ wasm-pack test --firefox --headless -- --test debug
```

## Publish
[The site](https://riscvemu.web.app/) is hosted by a firebase for now. It might move in the future.
```
$ firebase deploy
```

# Roadmap
### Supports "The RISC-V Instruction Set ManualVolume I: Unprivileged ISADocument Version 20191213"
- [x] RV64G ISA
- [ ] RV64C ISA

### Supports "The RISC-V Instruction Set ManualVolume II: Privileged ArchitectureDocument Version 20190608-Priv-MSU-Ratified"
- [ ] Privileged ISA (URET, SRET, MRET, WFI, SFENCE.VMA, HFENCE.BVMA, and HFENCE.GVMA)
- [ ] Machine-level CSRs
- [ ] Machine-Mode privileged instructions
- [ ] Supervisor-level CSRs
- [ ] Supervisor instructions
- [ ] Page-Based Virtual-Memory System
- [ ] User-level CSRs

## Dependencies
- rust toolchain
  - rustup
  - rustc
  - cargo
    - cargo-generate
- wasm-pack
- npm
  - xterm: https://xtermjs.org/
  - xterm-addon-fit
- firebase CLI

## Resources
- [Rust and WebAssembly](https://rustwasm.github.io/docs/book/introduction.html)
- [wat2wasm demo](https://webassembly.github.io/wabt/demo/wat2wasm/)
- [RISC-V Software Ecosystem Overview](https://riscv.org/software-status/)
- [RISC-V Online Simulator](https://www.kvakil.me/venus/)
- [Running 64- and 32-bit RISC-V Linux on QEMU](https://risc-v-getting-started-guide.readthedocs.io/en/latest/linux-qemu.html)

## 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](https://riscv.org/2020/01/emulate-32-bit-and-64-bit-risc-v-in-your-browser-with-asamis-open-source-rvemu-gareth-halfacree-hackster-io/)
- [Emulate 32-Bit and 64-Bit RISC-V in Your Browser with Asami's Open Source rvemu](https://www.hackster.io/news/emulate-32-bit-and-64-bit-risc-v-in-your-browser-with-asami-s-open-source-rvemu-b783f672e463)