Skip to main content

Simple tools for working with the RISC-V instruction set

Project description


Simpleriscv is a minimal toolchain for assembling, disassembling, and simulating bare-metal RISC-V programs. It was created to lower the barrier to entry for individuals who are curious learning RISC-V and designing low-level systems. The process of building custom GCC toolchains may be necessary for more advanced RISC-V applications but, for beginners, this module provides a simple and quicker way to dive into projects and experimentation.

This package has no external dependencies which makes it cross-platform and easy to install. It does use David Beazley's PLY library for lexing and parsing assembly code but this is bundled in simpleriscv/ply.


Simpleriscv can be installed and upgraded via pip.

pip install simpleriscv


The following is a RISC-V program that loads two small integers and adds them together.

# add.asm

addi x1, zero, 2  # load 2 into register x1
addi x2, zero, 3  # load 3 into register x2
add x3, x1, x2    # add the values in x1 and x2 together and store into x3

Assembling the program will creating an output binary named with a .bin suffix in place of .asm.

simpleriscv asm add.asm

Now the simulator can be used to run the program.

simpleriscv sim add.bin

You might be thinking: where is the output?! By default, a RISC-V system is nothing more than a CPU and some memory. Interacting with outside world requires additional devices for input and output. Since our example program doesn't use any such device, it appears as though nothing happened.

However, changes did happen to the internal state of the CPU: 2 was loaded into register x1, 3 was loaded into register x2, and the sum of 2 + 3 was placed into register x3. How can we see those changes? By running the simulator with the optional flag --print-registers, we can see what the registers look like after our program has been ran.

simpleriscv sim add.bin --print-registers

Now we can see some changes! Notice the values printed for registers x1, x2, and x3.


Links to PDFs go here!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for simpleriscv, version 0.0.4
Filename, size File type Python version Upload date Hashes
Filename, size simpleriscv-0.0.4-py3-none-any.whl (49.2 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size simpleriscv-0.0.4.tar.gz (46.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page