QuantiumV SDK

Software development kit for quantiumv/core — a RISC-V SoC (RV64IMAC + Zicsr + M/S/U privilege, Sv39 virtual memory, PMP, CLINT+PLIC interrupts, a JTAG/DMI Debug Module) built collaboratively from scratch in SystemVerilog.

Join on Discord if you're interested in the project!

Status: Track A done, Track B (Linux) in progress

Track A — bare-metal firmware SDK: done and verified. toolchain.mk, startup/crt0.S + startup/trap.S, a real HAL (hal/uart.c, hal/clint.c, hal/trap_default.c), and two working examples (examples/hello, examples/trap_test) all build clean and have been run against the real core RTL via scripts/run-sim.sh — see ROADMAP.md for the per-phase detail and what its own verification pass found.

Track B — Linux enablement: real progress, not yet booting on core. Two concrete things landed on the core side recently: its real RAM grew from 32KB to 64MB (Linux-boot readiness was the explicit reason), and the target software stack itself — a real Linux kernel + OpenSBI + BusyBox, built via Buildroot — has been proven to boot to a genuine, verified interactive shell. That boot was on QEMU's own standard riscv64 virt machine, not on core — see Booting Linux (validated on QEMU) below for exactly what that does and doesn't prove, and What's still needed for a real core boot for the concrete remaining gap.

---

Booting Linux (validated on QEMU)

This reproduces the software-recipe validation: a real Linux kernel + OpenSBI + BusyBox rootfs, built via Buildroot's own stock qemu_riscv64_virt_defconfig (not linux/br2-external/configs/ quantiumv_defconfig below — that one's still an unvalidated skeleton, see its own header). This is deliberately decoupled from core's own hardware: it proves the OS/firmware recipe works at all, on real standard RISC-V peripherals, before spending time on the much slower and much harder RTL-simulation path.

git clone --depth 1 https://github.com/buildroot/buildroot.git
cd buildroot
make qemu_riscv64_virt_defconfig
make            # a real cross-build: host tools, a riscv64-glibc toolchain,
                 # the Linux kernel, OpenSBI, BusyBox -- expect 30-90+ minutes

Once it finishes, output/images/start-qemu.sh is Buildroot's own generated launcher. One real fix is needed before it boots: as generated, it passes a bare -drive file=rootfs.ext2,format=raw with no -device to actually attach it — on QEMU's RISC-V virt machine (unlike x86 PC machines), that drive is never presented to the guest at all, and the kernel hangs forever at Waiting for root device /dev/vda.... Fix by editing the generated start-qemu.sh (or invoking qemu directly) to use:

qemu-system-riscv64 -M virt -bios fw_jump.bin -kernel Image \
  -append "rootwait root=/dev/vda ro" \
  -drive file=rootfs.ext2,format=raw,if=none,id=hd0 \
  -device virtio-blk-device,drive=hd0 \
  -netdev user,id=net0 -device virtio-net-device,netdev=net0 \
  -nographic

Log in as root (empty password). You should land at a real BusyBox shell (Welcome to Buildroot / buildroot login:) and can confirm it's genuinely running with e.g. uname -a, cat /proc/cpuinfo, ip addr. Ctrl-A then X force-quits QEMU; poweroff from inside the guest is the clean way out.

Two environment notes if you're doing this on WSL (both hit and fixed during the original validation, may recur for you):

• WSL auto-appends the Windows PATH into the Linux one, and Windows path entries (Program Files-style) contain spaces, which breaks Buildroot's own dependency-check script. Export a clean PATH (no Windows entries) before running any Buildroot make command.
• If you don't have root/sudo and a host build tool (cpio/unzip/bc/ rsync were the ones this project hit) is missing: apt-get download <pkg> needs no root, then dpkg-deb -x <pkg>.deb <some-local-dir> and prepend that dir's bin/ to PATH — no sudo needed.

What's still needed for a real core boot

• An SBI platform targeting core. OpenSBI's platform/generic plus a correct device tree covers a board for free only if its CLINT/PLIC/UART are register-compatible with known hardware. Checked against core's real RTL: design/plic.sv is genuinely SiFive-PLIC-1.0.0-compatible (priority/pending/enable/threshold-claim offsets all match) — no bespoke PLIC driver needed. design/clint.sv and the UART are not — CLINT is a minimal 2-register design (mtime@0, mtimecmp@8), not the real SiFive/ACLINT layout (mtimecmp@0x4000/hart, mtime@0xBFF8) OpenSBI's generic timer driver expects; the UART isn't 16550-compatible either. Closing those two gaps (register-compat fixes in core, or a real platform/quantiumv/ OpenSBI port) is real, undecided work — see ROADMAP.md's own standards-compliance callout.
• A device tree describing core's own memory map (CPU ISA string, RAM, UART, CLINT, PLIC) — doesn't exist yet. include/quantiumv/memmap.h below is the nearest existing source of truth for the addresses it'd need.
• An actual attempt at booting through RTL simulation — genuinely untried. A real boot could take an enormous number of simulated cycles; nobody has measured this yet, so "will it even finish in reasonable wall-clock time" is itself an open question worth answering early.

---

Repo layout

sdk/
  README.md, ROADMAP.md          # read ROADMAP.md before starting new work
  setup.sh                        # Track A4: toolchain + OpenSBI + U-Boot + BusyBox bootstrap
  toolchain.mk                    # shared ASFLAGS/CFLAGS/LDFLAGS
  startup/crt0.S, trap.S          # Track A1/A2
  linker/quantiumv.ld              # Track A1
  include/quantiumv/               # memmap.h, csr.h, uart.h, clint.h -- mirrors core's own map
  hal/                             # uart.c, clint.c, trap_default.c
  examples/hello, examples/trap_test   # built and run against real core RTL
  scripts/run-sim.sh, generic_soc_tb.sv
  linux/br2-external/              # Track A4/B: Buildroot BR2_EXTERNAL tree
    configs/quantiumv_defconfig      # unvalidated skeleton, see its own header
    board/quantiumv/                 # empty -- device tree lands here, blocked on the SBI work above

See ROADMAP.md for the full Track A/B staging, the open team decisions (standards-compliant vs. custom CLINT/PLIC/UART, musl vs. glibc, hand-rolled SBI bridge vs. a real OpenSBI port), and per-phase notes on what each verification pass actually found.