An experimental five-stage RV64 processor written in Anvil. Anvil generates SystemVerilog, which runs under Verilator or feeds the Genesys 2 FPGA flows in this repository.
Under Verilator the core runs the RISC-V ISA tests, freestanding C++ programs, and xv6-riscv to a shell prompt.
- The Anvil compiler, as
anvilinPATHor viaANVIL_BIN. Upstreammasterat commit8432f2bor later; earlier revisions mis-evaluate sized literals and the core will not execute correctly. - Verilator 4.2 or newer
- GNU Make,
git,curl - Vivado with Kintex-7 support, for FPGA synthesis only
The RISC-V cross-toolchain is not required up front: the scripts install a
prebuilt one into .toolchain/ without root.
Clone with submodules, then boot xv6:
git clone --recurse-submodules <repo-url>
cd RISCy-Experiment
scripts/run_xv6.shrun_xv6.sh performs every step needed and skips those already done: check
out the xv6 submodule, install the RISC-V toolchain, build xv6 for this core's
ISA, build the simulator, and boot. It prints a progress bar while booting and
stops once the shell prompt appears.
Expected output:
xv6 kernel is booting
init: starting sh
$
Pass -i to stay attached to the shell instead of stopping at the prompt.
Expect roughly 7 minutes to reach the shell prompt. Measured at 396 s on a desktop x86-64 machine; the simulator runs at about 200 000 cycles per second and the boot needs on the order of 10^8 cycles, so the figure scales with single-core performance. The first run takes longer still, because it also downloads the toolchain (about 520 MB) and builds xv6 and the simulator.
XV6_CYCLE_LIMIT (default 2 000 000 000) bounds the run in simulated cycles.
XV6_HOST_TIMEOUT (default 0, meaning no limit) bounds it in wall clock.
# Build the Verilator simulator.
scripts/build_program_sim.sh
# Run the ISA and C++ program regressions, lints and FPGA export checks.
scripts/verify_all.sh
# Run one ISA test.
build/pipeline_core_program/obj_dir/Vpipeline_core tests/isa/csr.elf 100000To include the xv6 boot in the full run:
RUN_XV6=1 \
XV6_KERNEL="$PWD/.toolchain/xv6-build/kernel/kernel" \
XV6_FS_IMG="$PWD/.toolchain/xv6-build/fs.img" \
XV6_CYCLE_LIMIT=2000000000 \
XV6_HOST_TIMEOUT=0 \
VERIFY_XV6_TIMEOUT=0 \
scripts/verify_all.shAnvil compilation is bounded by a 12 GiB virtual-memory limit and a 20-minute timeout, both configurable:
ANVIL_BIN=/path/to/anvil ANVIL_VMEM_MB=16384 ANVIL_TIMEOUT=30m \
scripts/build_program_sim.shANVIL_VMEM_MB=0 disables the memory limit.
The simulator prints the guest console on stdout and a few startup lines on
stderr. Pass --verbose for the full per-cycle trace (page-table walks, UART
and PLIC activity, traps, privilege changes), or --trace for pipeline
tracing.
xv6-riscv is vendored as a submodule at third_party/xv6-riscv. Stock xv6
targets rv64gc with the lp64d ABI, which this core does not implement, so
scripts/toolchain/build_xv6.sh rebuilds it for rv64ima_zicsr_zifencei with
-mabi=lp64, NCPU=1 and PHYSTOP=0x80800000. It builds out of tree into
.toolchain/xv6-build, leaving the submodule's working tree untouched.
Five-stage in-order pipeline:
| Stage | Responsibility |
|---|---|
| IF | Instruction fetch and PC selection |
| ID | Decode, register reads, forwarding, hazard detection |
| EX | Integer, branch, CSR and capability operations |
| MEM | Loads, stores, atomics, alignment, memory exceptions |
| WB | Register writeback, retirement, traps, redirects |
See Status for what is implemented and how far each target runs.
The project is under active development. Simulation is the mature target; FPGA bring-up is in progress.
The simulation target is complete and is what the regressions exercise.
| Item | State |
|---|---|
| RV64I, RV64M, RV64A | implemented; covered by the ISA tests |
| M/S/U privilege, traps, interrupts | implemented; covered by the ISA tests |
| Sv39 paging | implemented; the page-table walk and TLB run in the C++ harness |
| Capability extension | experimental; 10 of the 21 ISA tests cover it, with cap_result currently driven by the harness |
| ISA tests | 21/21 pass |
| C++ program tests | 8/8 pass |
| xv6-riscv | boots to a shell prompt |
The harness supplies RAM, the Sv39 walker and TLB, the MMIO devices (UART, PLIC, timer), virtio block storage, and part of the capability state as C++ models. The regressions therefore exercise the core against that contract; the services themselves are being moved into RTL as FPGA bring-up progresses. docs/WORK_LOG.md records the current boundary.
Bring-up on the Digilent Genesys 2 (XC7K325T-2FFG900C) is in progress. The
build and lint flows are in place and the BRAM target produces a bitstream;
running xv6 on the board is the goal being worked towards.
| Area | State |
|---|---|
| Generated-core synthesis | RTL exports and passes Verilator lint |
| BRAM bring-up | Builds a bitstream. The payload writes BOOT\r\nB\r\nL=5A\r\n over UART and 0x5a to the GPIO window — a board bring-up program rather than xv6 |
| DDR/MIG integration | Target and calibration target in place; validating the memory path is the next step |
| Sv39 in RTL | The core exposes the signals; a synthesizable TLB and page-table walker are still to come |
| xv6 storage | An FPGA storage or host-bridge path is still to be chosen |
| Capability datapath | Harness-backed for now; RTL integration pending |
| Timing closure | To be established once the memory path lands |
The core has not yet been run on hardware. make -C fpga check and the lint
scripts run without Vivado; building a bitstream or programming a board needs
Vivado with Kintex-7 support.
scripts/lint_fpga_rtl.sh
scripts/lint_fpga_bram_rtl.sh
make -C fpga check
make -C fpga bram
make -C fpga bitstream-bramSee fpga/README.md for board setup and programming, and the open work list in docs/WORK_LOG.md.
| Path | Contents |
|---|---|
src/ |
Anvil types, pipeline stages, CSR logic, execution units |
sim/ |
Verilator harness, linker script, startup code |
tests/ |
ISA assembly tests and freestanding C++ programs |
scripts/ |
Build, test, export and lint entry points |
fpga/ |
Genesys 2 wrappers, constraints, Vivado scripts, Makefile |
third_party/xv6-riscv |
xv6-riscv submodule |
docs/WORK_LOG.md |
Implementation boundary and open engineering work |
See also scripts/README.md, sim/README.md and tests/README.md.