{"id":13599879,"url":"https://github.com/d0iasm/rvemu","last_synced_at":"2025-04-10T17:32:59.221Z","repository":{"id":39374024,"uuid":"216803731","full_name":"d0iasm/rvemu","owner":"d0iasm","description":"RISC-V emulator for CLI and Web written in Rust with WebAssembly. It supports xv6 and Linux (ongoing).","archived":false,"fork":false,"pushed_at":"2024-02-22T01:41:58.000Z","size":55992,"stargazers_count":698,"open_issues_count":13,"forks_count":52,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-04-24T23:01:42.700Z","etag":null,"topics":["emulator","riscv","riscv-emulator","riscv-simulator","rust"],"latest_commit_sha":null,"homepage":"https://rvemu.app/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d0iasm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-22T12:03:46.000Z","updated_at":"2024-06-09T18:11:12.601Z","dependencies_parsed_at":"2024-06-09T18:21:16.147Z","dependency_job_id":null,"html_url":"https://github.com/d0iasm/rvemu","commit_stats":{"total_commits":548,"total_committers":7,"mean_commits":78.28571428571429,"dds":0.02372262773722633,"last_synced_commit":"07994c5261f69a130b6abcea70ba1ed0e2c9bbaf"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d0iasm%2Frvemu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d0iasm%2Frvemu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d0iasm%2Frvemu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d0iasm%2Frvemu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d0iasm","download_url":"https://codeload.github.com/d0iasm/rvemu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223442733,"owners_count":17145825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emulator","riscv","riscv-emulator","riscv-simulator","rust"],"created_at":"2024-08-01T17:01:15.405Z","updated_at":"2025-04-10T17:32:59.210Z","avatar_url":"https://github.com/d0iasm.png","language":"Rust","funding_links":[],"categories":["Rust","CPU RISC-V"],"sub_categories":["网络服务_其他"],"readme":"# rvemu: RISC-V Emulataor\n\n[![Build Status](https://travis-ci.com/d0iasm/rvemu.svg?branch=master)](https://travis-ci.com/d0iasm/rvemu)\n[![Actions Status](https://github.com/d0iasm/rvemu/workflows/CI/badge.svg)](https://github.com/d0iasm/rvemu/actions)\n[![docs.rs](https://docs.rs/rvemu/badge.svg)](https://docs.rs/rvemu)\n[![crate.io](https://img.shields.io/crates/v/rvemu.svg)](https://crates.io/crates/rvemu)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/d0iasm/rvemu/master/LICENSE)\n\nRISC-V online/CLI emulator in Rust.\n\nThe online emulator is available here:\n- [**rvemu.app**](https://rvemu.app/): Run an arbitrary RISC-V binary you\n  uploaded.\n- [**rvemu.app/xv6**](https://rvemu.app/xv6.html): Run\n  [`xv6`](https://github.com/mit-pdos/xv6-riscv) automatically once you visit\n  the page.\n\nThe emulator supports RV64GC ISA (RV64IMAFD, Zicsr, Zifencei, RV64C),\nprivileged ISA, CSRs, virtual memory system (Sv39), peripheral devices (UART,\nCLINT, PLIC, Virtio), and device tree. See [the \"Features List\"\nsection](https://github.com/d0iasm/rvemu#features-list) for the details of\nfeatures.\n\nThese features are compliant with \"The RISC-V Instruction Set Manual Volume I:\nUnprivileged ISA Document Version 20191214-draft\" and \"The RISC-V Instruction Set\nManual Volume II: Privileged Architecture Document Version 1.12-draft\" in [the RISC-V\nspecifications](https://riscv.org/technical/specifications/).\n\n## Usage\n\nThe emulator can run both in your browser and in your terminal. Also, the\nemulator can be embedded in your project by [the crate\nregistry](https://crates.io/crates/rvemu).\n\n### On Browser\n\nYou can run [`xv6`](https://github.com/mit-pdos/xv6-riscv), a simple Unix-like\noperating system, in [**rvemu.app/xv6**](https://rvemu.app/xv6.html).\n\n![Demo](https://raw.githubusercontent.com/d0iasm/rvemu/master/demo.gif)\n\nYou also be able to run an arbitrary RISC-V binary in\n[**rvemu.app**](https://rvemu.app/). The online emulator supports the following\ncommands:\n- __upload__: Upload local RISC-V binaries for the execution on the emulator.\n- __ls__: List the files you uploaded.\n- __run [file]__: Execute a file which you uploaded or some files are already\n  embedded.\n- __help__: Print all commands you can use.\n\nSee [the \"Build RISC-V binary\"\nsection](https://github.com/d0iasm/rvemu#build-risc-v-binary) for more\ninformation to build RISC-V binary.\n\n### On Terminal\n\nThe option `--kernel` or `-k` specifies a kernel image, and `--file` or `-f`\nspecifies a root filesystem image.\n\n**Linux**\n\n```\n$ ./target/release/rvemu-cli -k bin/linux/bbl.bin -f bin/linux/busybear.bin\n```\n\n**xv6**\n\n```\n$ ./target/release/rvemu-cli -k bin/xv6/kernel.bin -f bin/xv6/fs.img\n```\n\n**Bare-metal binary**\n\nYou can use an arbitrary RISC-V binary and you can skip the `-f` option. An ELF\nbinary should have no headers.\n```\n$ ./target/release/rvemu-cli -k \u003cyour-binary\u003e\n```\n\n## Build\n\n### For Web Application\n\nThe `wasm-pack build` command generates a `pkg` directory and makes Rust\nsource code into `.wasm` binary. It also generates the JavaScript API for\nusing our Rust-generated WebAssembly. The toolchain's supported target is\n`wasm32-unknown-unknown`. You need to execute this command whenever you change\nyour Rust code.\n\n```\n// This is the alias of\n// `wasm-pack build lib/rvemu-wasm --out-dir \u003cpath-to-rvemu\u003e/public/pkg --target web --no-typescript`.\n$ make rvemu-wasm\n```\n\nThis command installs dependencies in the `node_modules` directory. Need `npm\ninstall --save` in the `public` directory at the first time and whenever you\nchange dependencies in package.json.\n\n```\n$ npm install --save // at the public directory\n```\n\nYou can see the website via http://localhost:8000. `npm start` is the alias of\n`python3 -m http.server` so you need Python3 in your environment.\n\n```\n$ npm start // at the public directory\n```\n\n### For CLI Tool\n\nBuild the emulator as a CLI tool.\n\n```\n$ make rvemu-cli\n```\n\n## Build RISC-V Binary\n\nYou might need to build [RISC-V toolchain](https://github.com/riscv/riscv-gnu-toolchain).\n\n```\n$ git clone --recursive git@github.com:riscv/riscv-gnu-toolchain.git\n$ cd riscv-gnu-toolchain\n$ ./configure --prefix=/opt/riscv --with-arch=rv64gc\n$ make\n$ make linux\n```\n\n### Bare-metal C Program\n\nYou need to make an ELF file without headers, which starts at the address `0x8000_0000` by the following instructions:\n\n```\n// Make an assembly file from a C file.\n$ riscv64-unknown-elf-gcc -S -nostdlib foo.c\n\n// Make a binary file from an assembly file with start position 0x8000_0000.\n$ riscv64-unknown-elf-gcc -Wl,-Ttext=0x80000000 -nostdlib -o foo foo.s\n\n// Remove headers from a binary file.\n$ riscv64-unknown-elf-objcopy -O binary foo foo.text\n```\n\n### Linux\n\n- [Linux v4.19-rc3](https://github.com/torvalds/linux/tree/v4.19-rc3)\n- [riscv-pk](https://github.com/riscv/riscv-pk)\n- [busybear-linux](https://github.com/michaeljclark/busybear-linux)\n\nFor build:\n\n```\n// Linux\n$ git clone https://github.com/torvalds/linux/\n$ git checkout tags/v4.19-rc3 -b v4.19-rc3\n$ make ARCH=riscv CROSS_COMPILE=riscv64-unknown-linux-gnu- defconfig\n$ make ARCH=riscv CROSS_COMPILE=riscv64-unknown-linux-gnu- -j $(nproc)\n\n// riscv-pk\n$ git clone https://github.com/riscv/riscv-pk\n$ cd riscv-pk\n$ mkdir build\n$ cd build\n$ ../configure --prefix=$RISCV --host=riscv64-unknown-elf \\\n  --with-payload=../../linux/vmlinux --enable-logo\n$ make\n$ make install\n\n// busybear-linux\n$ git clone https://github.com/michaeljclark/busybear-linux\n$ cd busybear-linux\n$ ./scripts/build.sh\n```\n\nIf a compile error happens, you may need to:\n\n- update `CC := gcc` to `CC := riscv64-unknown-elf-gcc` in\n  `riscv-pk/build/Makefile`\n- comment out the \"build bbl\" part in `busybear-linux/scripts/build.sh`\n\nbecause the build script for cross compiling in `riscv-pk` is broken.  See\nhttps://github.com/riscv/riscv-pk/blob/master/configure#L1146-L1148\n\n## Testing\n\nYou can see the binaries for unit testings in\n[riscv/riscv-tests](https://github.com/riscv/riscv-tests).\n\n```\n$ make test\n```\n\n## Analyzing with Perf\n\n```\n$ perf record -F99 --call-graph dwarf ./target/release/rvemu-cli -k bin/xv6/kernel.bin -f bin/xv6/fs.img\n$ perf report\n```\n\n## Publish\n\n[The site](https://rvemu.app/) is hosted by a firebase.\n\n```\n$ firebase deploy\n```\n\n## Features List\n\nThe emulator supports the following features:\n- [x] RV64G ISA\n  - [x] RV64I (v2.1): supports 52/52 instructions (`fence` does nothing for\n    now)\n  - [x] RV64M (v2.0): supports 13/13 instructions\n  - [x] RV64A (v2.1): supports 22/22 instructions (No atomicity for now)\n  - [x] RV64F (v2.2): supports 30/30 instructions\n  - [x] RV64D (v2.2): supports 32/32 instructions\n  - [x] Zifencei (v2.0): supports 1/1 instructions (`fence.i` does nothing for\n    now)\n  - [x] Zicsr (v2.0): supports 6/6 instructions (No atomicity for now)\n- [x] RV64C ISA (v2.0): support 36/36 instructions\n- [x] Privileged ISA: supports 7/7 instructions (`sfence.vma`, `hfence.bvma`,\n  and `hfence.gvma` do nothing for now)\n- [x] Control and status registers (CSRs)\n  - [x] Machine-level CSRs\n  - [x] Supervisor-level CSRs\n  - [ ] User-level CSRs\n- [x] Virtual memory system (Sv39)\n- [x] Devices\n  - [x] UART: universal asynchronous receiver-transmitter\n  - [x] CLINT: core local interruptor\n  - [x] PLIC: platform level interrupt controller\n  - [x] Virtio: virtual I/O\n- [x] Device tree\n\n## Dependencies\n\n- [Nightly Rust](https://doc.rust-lang.org/1.2.0/book/nightly-rust.html)\n- [Python3](https://www.python.org/downloads/)\n- [wasm-pack](https://github.com/rustwasm/wasm-pack)\n- npm\n  - [xterm](https://xtermjs.org/)\n  - xterm-addon-fit\n- dtc: device tree compiler\n\n`dtc` can be installed by `apt install device-tree-compiler` on Ubuntu.\n\n## Resources\n\n- [RISC-V Specifications](https://riscv.org/technical/specifications/)\n- [Rust and\n  WebAssembly](https://rustwasm.github.io/docs/book/introduction.html)\n- [riscv/riscv-sbi-doc](https://github.com/riscv/riscv-sbi-doc/blob/master/riscv-sbi.adoc)\n- [riscv/riscv-elf-psabi-doc](https://github.com/riscv/riscv-elf-psabi-doc/blob/master/riscv-elf.md)\n- [riscv/riscv-asm-manual](https://github.com/riscv/riscv-asm-manual/blob/master/riscv-asm.md)\n- [qemu/qemu](https://github.com/qemu/qemu)\n- [riscv/riscv-isa-sim](https://github.com/riscv/riscv-isa-sim)\n\n### Helpful Tools\n\n- [riscv/riscv-tests](https://github.com/riscv/riscv-tests)\n- [RISC-V Online Simulator](https://www.kvakil.me/venus/)\n\n## Articles about This Project\n\n- [Emulate 32-Bit And 64-Bit RISC-V In Your Browser With Asami’s Open Source\n  rvemu | Gareth Halfacree,\n  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/)\n- [Emulate 32-Bit and 64-Bit RISC-V in Your Browser with Asami's Open Source\n  rvemu](https://www.hackster.io/news/emulate-32-bit-and-64-bit-risc-v-in-your-browser-with-asami-s-open-source-rvemu-b783f672e463)\n- [Made a RISC-V Emulator Running Xv6 | d0iasm.io](https://d0iasm.github.io/blog/risc-v/2020/04/03/xv6-on-my-riscv-emulator.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd0iasm%2Frvemu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd0iasm%2Frvemu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd0iasm%2Frvemu/lists"}