Quick Start

Build and simulate Raptor in a few commands. Run everything from the project root — source env.sh is not required, the Makefile exports all variables.

Prerequisites

Linux (Ubuntu 22.04+) or macOS. On macOS some targets require a Linux container (e.g. colima).
git, make, a C/C++ toolchain, Python 3, a RISC-V GCC toolchain.
Optional but recommended:
- verilator — RTL simulator (installed by make setup).
- surfer — waveform viewer.
- tmux — nicer terminal multiplexing.

1. Install Dependencies

git clone https://github.com/Kingfish404/raptor-chip
cd raptor-chip

# One-line setup (installs all dependencies)
make setup

# Show all available targets
make help

2. Run NEMU (Software ISS)

make run-nemu32                 # configure + build + run, RV32

Or step by step:

make build-nemu32               # configure and build
make run-nemu32
make menuconfig-nemu32          # interactive Kconfig

3. Run NPC (Verilator Simulation)

# Full pipeline: Chisel -> SystemVerilog -> configure -> build -> run
make run-rv32

# Or step by step
make verilog                    # Chisel -> SystemVerilog
make configure-rv32            # configure only (difftest enabled by default)
make build-rv32
make run-rv32

# Common runtime flags
make run-rv32 ARGS="-b -n"     # -b batch mode (default) · -n no wave trace
make run-rv32 IMG=path/to.bin  # load a custom image
make menuconfig-rv32           # interactive Kconfig

RV64 Mode

The core supports RV64 via the compile-time switch -DRAPT_RV64. Switching between RV32 and RV64 automatically invalidates the build cache — no manual make clean needed.

make build-rv64
make run-rv64   ARGS="-b -n"
make lint-rv64
# or pass VFLAGS explicitly
make run-rv32 VFLAGS="-DRAPT_RV64" ARGS="-b -n"

4. Benchmarks

# NPC standalone
make coremark-rv32        ARGS="-b -n"
make microbench-rv32      ARGS="-b -n"

# NPC with difftest (vs NEMU reference model)
make coremark-rv32 DIFFTEST=1     ARGS="-b -n"
make microbench-rv32 DIFFTEST=1   ARGS="-b -n"

# Reproducible random memory-delay simulation (also supports -rv64)
make coremark-rv32 SIM_RANDOM_DELAY=31 SIM_RANDOM_SEED=1
make microbench-rv32 SIM_RANDOM_DELAY=31 SIM_RANDOM_SEED=42
make cpu-tests-rv64 SIM_RANDOM_DELAY=31 SIM_RANDOM_SEED=1

# ysyxSoC (RV32)
make coremark-ysyxsoc      ARGS="-b -n"
make microbench-ysyxsoc    ARGS="-b -n"

# NEMU
make coremark-nemu32       ARGS="-b -n"
make microbench-nemu32     ARGS="-b -n"

Recorded IPC history: Performance Iterations. Early PPA tables: PROFILE (legacy archive).

5. Apps on riscv-pk

make app-hello-rv32                        # hello world
make app-coremark-rv32    ARGS="-b -n"     # CoreMark on pk
make app-embench-rv32     ARGS="-b -n"     # Embench-IoT
make app-pk-build                           # build OpenSBI + pk
make app-clean

6. Linux Kernel

make linux-boot-nemu32              # NEMU
make linux-boot-rv32               # NPC + difftest vs NEMU (default)

Details: Linux Kernel Boot.

7. FPGA

LiteX is the supported board flow (KU15P, AXAU15, VCU118, Tang Mega 138K Pro):

make -C fpga/litex help
make -C fpga/litex fpga-detect          # detect attached Xilinx parts

The Gowin Tang Nano 20K path remains as a small open-toolchain target:

make fpga-syn                       # synth
make fpga-pnr                       # place & route

See fpga/litex/README.md and fpga/gowin-tang-nano-20k/README.md.

8. Utilities

make pack     # pack all SV into one file
make lint     # Verilator lint (RV32)
make sta      # static timing analysis (yosys-opensta)
make clean    # clean all build artifacts

Command Reference

Task	Command
Show all targets	`make help`
Setup environment	`make setup`
Generate RTL	`make verilog`
Build & run NEMU	`make run-nemu32`
Full NPC simulation	`make run-rv32`
NPC simulation (batch, no wave)	`make run-rv32 ARGS="-b -n"`
NPC RV64 mode	`make run-rv64 ARGS="-b -n"`
CPU tests on NPC	`make cpu-tests-rv32 ARGS="-b -n"`
Run CoreMark on NPC	`make coremark-rv32 ARGS="-b -n"`
Run MicroBench on NPC	`make microbench-rv32 ARGS="-b -n"`
Run nanos-lite on NEMU	`make nanos-nemu32`
Boot Linux on NEMU	`make linux-boot-nemu32`
Boot Linux on NPC w/ difftest	`make linux-boot-rv32`
FPGA (LiteX)	`make -C fpga/litex help`
FPGA (Tang Nano 20K)	`make fpga-syn` / `make fpga-pnr`
Pack SV / Lint / STA	`make pack` / `make lint` / `make sta`
Clean all	`make clean`

Key overridable variables: ARGS (runtime), VFLAGS (RTL defines), IMG (custom binary), MAINARGS (benchmark mode).

Manual Workflow

The same actions using the environment directly:

source ./env.sh

# 1. NEMU
cd $NEMU_HOME && make riscv32_defconfig && make && make run

# 2. NPC
cd $RAPTOR_HOME/hdl/chisel && make verilog
cd $NSIM_HOME && make o2_difftest_defconfig && make && make run

# 3. nanos-lite on NEMU (with VME)
cd $RAPTOR_HOME/abstract-machine/app/nanos-lite \
  && make ARCH=$ISA-nemu update run ARGS="-b" VME=1