Raptor Project

It is possible to invent a single machine which can be used to compute any computable sequence. — Alan Turing, 1936

Welcome to the Raptor Project! Here is an all-in-one repository for exploring, developing, optimizing, and verifying a RISC-V core. Aiming at high quality, full Linux support, FPGA implementation, and ASIC readiness.

Core description: Super-scalar, out-of-order RISC-V core with register renaming, a 64-entry ROB, six execution paths fed by five scheduler classes over five unified writeback CDB ports, TAGE branch prediction, and a unified speculative/committed store queue. The scalar F/D unit has a dedicated FPQ and architectural 32 x 64-bit FPR bank, and shares CDB0 with the ALU-CSR pipe. The RTL is described by SystemVerilog with Chisel (Scala) used only for decoder generation. Features Sv32 (RV32) / Sv39 (RV64) virtual memory (MMU/TLB/PTW), 16-entry PMP (TOR/NA4/NAPOT), LR/SC + AMO atomics, compressed instructions (RVC), CLINT/PLIC interrupts, a RISC-V Debug Module / JTAG DTM bring-up path, and Linux v6.18.x flows via OpenSBI. Supports configurable RV32 and RV64 modes via compile-time switch.

Core name:  raptor-falcon (M/S/U + Sv32/Sv39 + PMP, Linux-capable)
ISA:        rv32/rv64 imafdc_zba_zbb_zbs_zfhmin_zicbom_zicbop_zicboz_zicntr_zicond_zicsr_zifencei_zihintntl_zihintpause_zihpm_zimop_zca_zcb_zcmop
Modes:      Machine, Supervisor, User
MMU:        riscv,sv32 (RV32) / riscv,sv39 (RV64) / riscv,none (Bare)
PMP:        16 entries, TOR / NA4 / NAPOT, L-bit lockable
Interrupts: CLINT (mtime, mtimecmp, msip) + PLIC (31 sources, M/S contexts)
Profiles:   RVI20U32; RVA22S64 supported (default config, RV64)

Bus Interface:  AXI4, XLEN-bit data/addr, 4-bit ID; burst-capable reads (up to 8 outstanding), one outstanding single-beat write with independent AW/W handshakes
Default uarch: dual issue / dual commit, ROB=64, ALQ=8 (2 issue ports), BRQ=4, MDQ=4, FPQ=4, IOQ=8, SQ=16, integer PRF=128, FPR=32 x 64-bit, L1I=4 KiB, L1D=2 KiB, 64 B cache lines, optional L2 passthrough/cache stage

Verifying:  RISCOF (riscv-arch-test), full-core F/D directed/differential tests, RVFI, SVA

The F/D/Zfhmin implementation covers scalar floating-point load/store, arithmetic, FMA, divide/square-root, conversion, comparison/classification, rounding modes, accrued exception flags, and binary16 load/store, transfer, and conversion. The compressed subset includes the C-extension floating-point memory forms required with F/D (C.FLW/C.FSW on RV32 and C.FLD/C.FSD plus their stack-pointer forms on RV32/RV64).

See documentation for more details.

Microarchitecture

flowchart TD
  subgraph BPU["BPU structure"]
    direction TD
    BTB["BTB (2-way SA, 128 entries)"]
    PHT["PHT (2-bit, 256 entries)"]
    RSB["RSB (4 entries)"]
    TAGE["TAGE (default DIRP)"]
  end
  subgraph FE["Frontend (default decode/rename widths: 2/2)"]
    BPU["BPU (TAGE/BTB/RSB)"]
    IFU["IFU (instruction prefix + held suffix)"]
    IDU["IDU (DecodeWidth slots)"]
    RNU["RNU (RenameWidth slots, integrated MAP/RAT/free bitmap + checkpoints)"]
  end
  subgraph BE["Backend (default dispatch/commit widths: 2/2)"]
    ROU["ROU (UOQ + ROB 64)"]
    DPU{{"DPU dispatch router"}}
    IEU["IEU: ALQ 8 + BRQ 4 + MDQ 4"]
    FEU["FEU: FPQ 4 + scalar F/D"]
    LSU["LSU: IOQ 8 + SQ 16"]
    CDB(("CDB ×5"))
    PRF["PRF (2 × RenameWidth reads, CompletionPorts writes; default 4R/5W)"]
    FPR["FPR (32 × 64-bit)"]
    CMU["CMU (commit)"]
    CSR
  end
  subgraph MEM["Memory Subsystem"]
    direction TD
    subgraph IMEM["I-side · IF0 (0-bubble seq fetch)"]
      L1I["L1I 4 KiB 2-way (banked SRAM)"]
      ITLB["ITLB (default 16 entries, FA)"]
      IPTW["IPTW (Sv32 2-lvl / Sv39 3-lvl)"]
    end
    subgraph DMEM["D-side · IS/EX-WB (2-cyc hit, 3-cyc load-use)"]
      L1D["L1D 2 KiB 2-way (banked SRAM, VIPT, write-through)"]
      DTLB["DTLB (default 16 entries, replicated load/store views)"]
      DPTW["DPTW (Sv32/Sv39, Svade)"]
    end
    PMPC["PMP ×16 (TOR/NA4/NAPOT): fetch + ld/st + PTW checks"]
    BUS["BUS (mem_link arbiter, request IDs, L1D > L1I)"]
    AXIM["AXI4 master (up to 8 reads, independent AW/W)"]
    L2["L2 (optional, 16 KiB DM / passthrough)"]
    RTR["cluster AXI router (1 master / 3 targets)"]
    CLINT["CLINT (mtime / mtimecmp / msip)"]
    PLIC["PLIC (31 sources, M/S contexts)"]
    EXT["off-chip AXI (memory / LiteX SoC)"]
  end
  BPU --- IFU
  IFU --> IDU --> RNU
  IDU -."Early Resteer".-> IFU
  RNU --> ROU --> DPU
  DPU --> IEU & FEU & LSU
  IEU & FEU & LSU --> CDB
  CDB -->|"writeback + wakeup"| ROU & PRF
  FEU --- FPR
  LSU --- FPR
  ROU --> CMU
  ROU -."store commit".-> LSU
  CMU -."flush / BPU train".-> FE
  CSR --- IEU
  IFU --- L1I
  L1I --- ITLB
  ITLB -."miss".-> IPTW
  LSU --> L1D
  L1D --- DTLB
  DTLB -."miss".-> DPTW
  PMPC -.-> L1I & L1D & IPTW & DPTW
  L1I & L1D & IPTW & DPTW --> BUS
  BUS -->|mem_link| AXIM --> L2 --> RTR
  RTR --> CLINT & PLIC & EXT

Setup & Quick Start

Suggest install tmux for better terminal management. surfer for wave viewer. colima for Linux container.

# One-line setup (installs all dependencies)
make setup
# or if just want to setup RTL workspace
make setup-rtl

# Show all available targets
make help
# or pack all SV files into one
make verilog pack

# Setup for IDE/LSP support
make ide-setup

1. NEMU (Software Emulator)

# Configure, build and run NEMU (riscv32)
make run-nemu32

# Or step by step
make config-nemu32          # configure (riscv32_defconfig)
make build-nemu32           # build
make run-nemu32             # run

# Interactive menuconfig
make menuconfig-nemu32

2. Simulation (Verilator)

# Full pipeline: generate RTL -> configure -> build -> run
make sim-rv32

# Or step by step
make verilog              # Chisel -> SystemVerilog
make config-rv32         # configure (o2_defconfig)
make build-rv32          # build Verilator simulator
make run-rv32            # run simulation

# Run with args
make run-rv32 ARGS="-b -n"    # -b: batch mode [default], -n: no wave trace
make run-rv32 IMG=path/to.bin  # load custom image
# Add reproducible 0..8-cycle delays to each AXI memory beat/response
make run-rv32 ARGS="-b -n --mem-random-delay=8 --mem-random-seed=1"
# Interactive menuconfig
make menuconfig-rv32

RV64 Mode

The processor supports RV64 via a compile-time switch (-DRAPT_RV64). Switching between RV32 and RV64 automatically invalidates the build cache, no manual make clean needed.

# Build and run in RV64 mode (convenience targets)
make build-rv64
make run-rv64 ARGS="-b -n"
# Or explicitly pass VFLAGS
make run-rv32 VFLAGS="-DRAPT_RV64" ARGS="-b -n"

3. Benchmarks

# Run riscv32
make coremark-rv32 ARGS="-b -n"
make microbench-rv32 ARGS="-b -n"
# Run with difftest (vs NEMU reference)
make coremark-rv32-difftest ARGS="-b -n"
make microbench-rv32-difftest ARGS="-b -n"
# Run sim with reproducible random AXI memory delays (also supports -rv64)
make coremark-random-rv32 SIM_RANDOM_DELAY=31 SIM_RANDOM_SEED=1
make microbench-random-rv32 SIM_RANDOM_DELAY=31 SIM_RANDOM_SEED=42
make cpu-tests-random-rv64 SIM_RANDOM_DELAY=31 SIM_RANDOM_SEED=1
# Run on ysyxSoC
make coremark-ysyxsoc ARGS="-b -n"
make microbench-ysyxsoc ARGS="-b -n"
# Run on NEMU (riscv32-nemu)
make coremark-nemu32 ARGS="-b -n"
make microbench-nemu32 ARGS="-b -n"

4. Applications running on riscv-pk

# Build and run hello world on NPC
make app-hello-rv32
# Build and run CoreMark on NPC
make app-coremark-rv32 ARGS="-b -n"
# Build and run Embench-IoT on NPC
make app-embench-rv32 ARGS="-b -n"
# Build riscv-pk (opensbi + pk)
make app-pk-build
# Clean app build artifacts
make app-clean

5. Linux Kernel Boot

# Boot Linux on NEMU (requires OpenSBI payload built first)
make linux-boot-nemu32
# Boot RV32GC Buildroot Linux on NEMU (downloads/re-wraps the image as needed)
make linux-boot-nemu32gc
# RV64GC equivalent
make linux-boot-nemu64gc
# Boot Linux on NPC (NEMU difftest is enabled by default)
make linux-boot-rv32
# See detailed instructions
# docs/linux_kernel.md, linux/README.md

The two GC NEMU targets enable a virtio-mmio NIC by default. It uses libslirp for unprivileged outbound NAT (guest DHCP 10.0.2.15, gateway 10.0.2.2, DNS 10.0.2.3); install the libslirp development package if it is not already available (libslirp-dev on Debian/Ubuntu).

6. Verification

# Random instruction fuzzing with difftest (NPC vs NEMU)
make verify-fuzz
make verify-fuzz-inf      # continuous until Ctrl-C / failure
# Signature-based ISA corner-case tests
make verify-sigtest
# RISCOF classic compliance tests (legacy, no difftest)
make verify-riscof-classic
make verify-riscof-classic-nemu
# Official RISCOF compliance (riscv-arch-test, sail reference)
make verify-riscof
# Verilator line/toggle coverage
make verify-coverage
# Run everything
make verify-all
# See verify/README.md for SVA, formal (RVFI), and ACT4 details

7. FPGA

# --- LiteX SoC ---
cd fpga/litex
make setup                          # one-time: install LiteX + register Raptor CPU
make pack                           # pack RTL into single .sv
make sim                            # Verilator sim with LiteX BIOS
make coremark                       # build + run CoreMark in sim
make embench                        # build + run all Embench-IoT benches
make linux                          # build + run Linux payload in sim

# Tang Mega 138K Pro hardware flow
make fpga-build                     # synth + P&R bitstream
make fpga-load                      # load to SRAM (volatile)
make fpga-flash                     # write to external SPI flash
make fpga-console                   # open UART console

# MLK-CU07-KU15P OpenSBI/Linux over MIG DDR and BIOS serialboot
make opensbi-fpga-e2e UART_PORT=/dev/ttyUSB0  # build/load, then standalone OpenSBI
make linux-fpga-e2e UART_PORT=/dev/ttyUSB0    # build/load, then OpenSBI + Linux
make linux-fpga-run UART_PORT=/dev/ttyUSB0    # reuse an existing bitstream
# See fpga/litex/README.md for full target/variant matrix

Build and Run (Manual)

The following commands are equivalent to the make targets above, useful if you need finer-grained control.

# 0. environment variables for direct subdirectory workflows
source ./env.sh

# 1. build and run NEMU
cd $NEMU_HOME && make riscv32_defconfig && make && make run
cd $NEMU_HOME && make riscv32_linux_defconfig && make && make run

# 2. build and run NPC
cd $RAPTOR_HOME/hdl/chisel && make verilog
cd $NSIM_HOME && make o2_defconfig && make && make run
cd $NSIM_HOME && make o2linux_defconfig && make && make run
cd $NSIM_HOME && make menuconfig && make ARCH=riscv32-npc run

# 3. build and run the program you want

## n. running nanos-lite on nemu
cd $NAVY_HOME && make ISA=$ISA fsimg
cd $NAVY_HOME/apps/menu && make ISA=$ISA install
cd $RAPTOR_HOME/abstract-machine/app/nanos-lite && make ARCH=$ISA-nemu update run
cd $RAPTOR_HOME/abstract-machine/app/nanos-lite && make ARCH=$ISA-nemu run
## n.vme running nanos-lite on nemu with VME
cd $RAPTOR_HOME/abstract-machine/app/nanos-lite && make ARCH=$ISA-nemu update run ARGS="-b" VME=1

## n+1. running busybox on nemu (Linux required)
cd $NAVY_HOME/apps/busybox && colima ssh # login to Linux container
make ARCH=riscv32-nemu install

## 2n. running microbench/coremark on npc
cd $RAPTOR_HOME/abstract-machine/app/am-kernels/benchmarks/coremark_eembc && \
    make ARCH=riscv32-npc run ARGS="-b -n"
cd $RAPTOR_HOME/abstract-machine/app/am-kernels/benchmarks/microbench && \
    make ARCH=riscv32-npc run ARGS="-b -n"
# ARGS="-b -n" is optional, -b is for batch mode [default], -n is for no wave trace

## package all sv files into one
cd sim && make pack

Run OpenSBI & Linux Kernel

See Linux Kernel

Reference

• Specifications – RISC-V International
• riscv/riscv-isa-manual: RISC-V Instruction Set Manual
• riscv-software-src/riscv-unified-db: Machine-readable database of the RISC-V specification, and tools to generate various views
• “一生一芯”