RvRun - A RISC-V emulator

RvRun is an emulator for the Linux RISC-V 64bit userspace, it is an educational project that attempts to emulate as many instructions and system calls as possible.

Installation

Pre-compiled binary

You can download the pre-compiled binary together with the example programs on the github releases page. Download the code and unzip it, you'll see the binary rvrun on your current directory, as well as an examples directory with pre-compiled RISC-V binaries that you can use to test rvrun. the makefile used for compilation will still be there, if you'd like to install it to your $PATH directory, you can use the install and uninstall targets described below on the compiling section

Compiling

Ensure you have git and make installed, if anything fails, try gmake. First, clone the repository, cd into it, and checkout into the version you want to use (e.g. with git checkout v1.1). The Makefile provides 4 targets:

• rvrun: Compiles all of the code into a single binary called rvrun that is on the current directory
• clean: Deletes all of the object and dependency files generated by compilation
• install: Moves the binary to your /usr/local/bin directory
• uninstall: Deletes the binary from your /usr/local/bin directory

The rvrun target is the default one, that is, you only need to run make to compile the program. Both the install and uninstall targets can be altered by passing a PREFIX=<path> argument to make, this will make so that the binaries are installed in <path>/bin, instead of /usr/local/bin.

The Makefile defaults to using cc as the compiler, but both gcc and clang are suported. If you'd like to choose one, you can also add CC=<compiler> to your make command. using gcc is recommended, and cc will most likely be a symbolic link to it.

A normal installation might go like:

$ git clone https://github.com/foo8664/RvRun.git
Cloning into 'RvRun'...
remote: Enumerating objects: 381, done.
remote: Counting objects: 100% (381/381), done.
remote: Compressing objects: 100% (220/220), done.
remote: Total 381 (delta 230), reused 302 (delta 154), pack-reused 0 (from 0)
Receiving objects: 100% (381/381), 106.43 KiB | 2.88 MiB/s, done.
Resolving deltas: 100% (230/230), done.
$ cd RvRun
$ git checkout v1.1
$ make --quiet
$ sudo make install
install -m755 rvrun /usr/local/bin/rvrun
$ # RvRun can now be used via the "rvrun" command

The examples/ directory has a separate Makefile for the programs in it, and it's usage is described in examples/README.md

Usage

RvRun requires a file to execute, it should be an ELF file for a little endian, executable, RISC-V program, it is the first positional argument, and everything passed after it will be considered an argument for that program, not for RvRun. RvRun supports multiple flags, these are:

• --help: Show a message similar to this, explaining how to use RvRun
• --version: Show a version and exit
• --stdin=FILE: redirect emulated process's stdin from FILE, without affecting RvRun
• --stdout=FILE: redirect emulated process's stdout to FILE, without affecting RvRun
• --stderr=FILE: redirect emulated process's stderr to FILE, without affecting RvRun
• --log-level=LEVEL: Determine which logs will be outputed and which won't, defaults to 3 (Error)
• --log-file=FILE: Redirect RvRun's logs to FILE

For a full description on how to use RvRun, you can run it with the --help flag

Currently supports:

Extensions

• I (Base ISA, 64bits)
• M (Integer Multiplication and Division)
• F (Single-Precision Floating-Point)
• Zicsr (Control and Status Registers)

System calls

• openat (syscall num: 56)
• close (syscall num: 57)
• read (syscall num: 63)
• write (syscall num: 64)
• exit (syscall num: 93)
• exit_group (syscall num: 94)

Dynamic Libraries are not supported!

Asciinema recordings

Example uses of RvRun have been recorded with asciinema, and are available under the asciinema/ directory. If you do not want to install asciinema to play these recordings, you can also see them at:

• echo: https://asciinema.org/a/900181
• cat: https://asciinema.org/a/900183
• xdd: https://asciinema.org/a/900185
• fib: https://asciinema.org/a/sIxNuRmRAi5E3eVN
• gcd: https://asciinema.org/a/o8HgbgymWB3ikf1v
• sin: https://asciinema.org/a/dLGEu0nAImabzgsI

License

RvRun is licensed under the GPL version 2, available at https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html, there is a local copy in the LICENSE file. Some files in the source code are from other projects, and are required to build RvRun (e.g. include/sysnums.h, from the linux kernel source code), these files may or may not be under different licenses. If in doubt, check the start of the file, there should be a comment displaying copyrighting and licensing information.