Developer Docs

Build Prerequisites

RAPcores targets the FOSS synthesis, place and route, and bitstream tools. Namely yosys and nextpnr. We are open to support other flows and open source tool chain. However do note that RAPcores does use some SystemVerilog features supported by Yosys.

We recommend using a relatively recent build of these tools. The ones included in LTS Linux distros may be out of date.

Overview of Make targets






remove build artifacts



build and program BOARD



run formal verification



get yosys synthesis statistics


parse the src directory with iverilog


parse the src directory with yosys


parse the src directory and run CDC checks with verilator


parse the src directory with yosys, iverilog, and verilator


run the testbench recipe in testbench/yosys/{test}


run the testbench recipe in testbench/cxxrtl/{test}


build docs in the specified format (e.g. docs-html)

Board targets

The following targets require a BOARD to be specified.

make BOARD=<board>

Generate bit stream.

make clean BOARD=<board>

Clean build artifacts.

make prog BOARD=<board>

Generate bitstream and upload.

make stat BOARD=<board>

Get logic synthesis statistics for the given configuration.

Formal Verification

SymbiYosys is used for formal verification of the code base. It can be run with:

make formal BOARD=<board>

This command will create a symbiyosys_<board> directory in the symbiyosys directory contains all the logs and data from the verification. If an assert or cover fails, a .vcd file will be generated that will display the states of registers and wires that induced the failure. GTKWave is a useful program for viewing the .vcd files.

The base config for Symbiyosys is symbiyosys.sby in the symbiyosys directory. Board specific defines are overlaid on top to ensure that each board configuration can be validated.

Test Benches

The main RAPcores source is tested for compatibility against Yosys, IVerilog, and Verilator. In-tree testbenches use the Yosys suite with either the default ‘sim’ or ‘cxxrtl’ backends.

Yosys Sim Bench

The yosys test benches can be executed with:

make yosys-<sim name>

For example:

make yosys-spi will run the spi.ys simulation located in testbench/yosys/<sim name>.

Yosys CXXRTL Bench (experimental)

CXXRTL text benches are Verilog to C++ transpiled testbenches. To run these a compiler and C++ driver program is required. The yosys CXXRTL test benches can be executed with:

make cxxrtl-<sim name>

For example:

make cxxrtl-rapcore will run the rapcore.ys simulation located in testbench/cxxrtl/<sim name>.


All files should have none as the default nettype:

`default_nettype none


For parser compatibility and linting one can use:

make triple-check

which will parse the source using Yosys, IVerilog, and Verilator.

Developing with Nix

RAPcores includes a shell.nix for use with the Nix Package manager. This makes it easy to get a development environment with all build requirements installed for you.

To start you will need to install Nix using the instructions here. They are reproduced here with some recommendations:

sudo install -d -m755 -o $(id -u) -g $(id -g) /nix
curl -L | sh
source $HOME/.nix-profile/etc/profile.d/ >> ~/.bashrc

Then restart the terminal. Next, cd to the RAPcores directory. Run nix-shell, and some packages will be installed. Once complete you should be able to run any of the make commands below. This environment includes all the tools to synthesis, place, route, program, and formally verify the RAPcores project.

Packages included in Nix environment

Verilog frontends:

  • yosys

  • verilog

  • verilator

Place and route/databases:

  • nextpnr

  • icestorm

  • trellis

Formal verification:

  • symbiyosys

  • yices


  • tinyprog

  • fujprog

  • openocd

Helpful Articles



Useful Tools

Google’s Verilog formatter and linter: -