OPNsense on RISC-V — Orange Pi RV2 (SpacemiT K1 / Ky X1)

Status: experimental hardware bring-up — NOT for production. This is an active, work-in-progress port. Kernels are iterated rapidly, some drivers are build-only, and the SD/board can behave unpredictably. Do not put this in front of a network you care about.

A from-scratch effort to bring FreeBSD/riscv64 + OPNsense up on the Orange Pi RV2 — the SpacemiT K1 ("Ky X1") SoC: 8-core RISC-V, dual onboard Gigabit Ethernet, 8 GB LPDDR4X. The goal is to finish the FreeBSD hardware enablement for this SoC (clocks/reset, PMIC, storage, NICs, Wi-Fi, …) and then package OPNsense on top of it using OPNsense's own arm-precedented cross-build tooling. Most of the SoC driver work here is original FreeBSD driver development; the hardware knowledge also feeds the sibling OpenWrt-RISC port of the same board.

Target hardware

Board	Orange Pi RV2
SoC	SpacemiT K1 (a.k.a. Ky "X1"), 8× RISC-V rv64gc, 1.6 GHz
RAM	8 GB LPDDR4X
Ethernet	2× GbE — SpacemiT EMAC IP (Synopsys DesignWare GMAC family)
Wi-Fi	AP6256 / BCM43456 SDIO (brcmfmac)
Storage	microSD (root); eMMC pads; SPI-NOR holds OpenSBI + vendor U-Boot
PCIe	2× PCIe 2.0 M.2 M-Key (NVMe) — driver builds; board-validation later
Console	Serial UART0 @ 115200 8N1
Boot	Vendor U-Boot 2022.10ky + OpenSBI in SPI-NOR; FreeBSD loader.efi chainloads

Current status (summary — see STATUS.md for the full worklog)

This is mid-bring-up; the living, newest-at-top worklog in STATUS.md is authoritative. Highlights as of this writing:

• Boots on real hardware: FreeBSD 16.0-CURRENT/riscv64, all 8 cores + 8 GB RAM.
• Core SoC drivers written & many hardware-validated: clock/reset controller (spacemit_ccu), pinctrl/GPIO, I²C (TWSI), P1 PMIC + regulators + RTC, hardware CRNG, thermal sensor, real UART clock, SDHCI (microSD), USB2 EHCI, USB3 (5 Gbps), PWM, SPI/QSPI, PCIe host + PHY.
• Dual Gigabit Ethernet driver (if_smte, ported from OpenBSD's smte(4)).
• WLAN working: AP6256 SDIO Wi-Fi (native brcmfmac over MMCCAM) scans and associates as a station, and runs as a WPA2 access point (the Wi-Fi firmware acts as the WPA2 4-way authenticator). The R51 kernel fixes a hostap vap-teardown bug that used to spin the kernel forever on every WebUI "Apply". See the WLAN entries in STATUS.md.
• Production kernel RV2PROD: the validated bring-up kernel with the runtime debug instrumentation (WITNESS/INVARIANTS) stripped, but the serial debugger (KDB/DDB) kept for recovery.
• OPNsense userspace: WebUI up on riscv64; Unbound resolver fixed and made boot-reliable; a self-hosted riscv64 package/firmware update mirror plus a poudriere cross-build pipeline are baked into the image build; a flashable SD image ships a matched kernel+modules set.
• Ran inline as a real home firewall during testing — WAN DHCP, automatic outbound NAT, DNS, the DHCP server, and WAN port-forwards all validated end-to-end on hardware.
• Known rough edges: remote reboot relies on a watchdog path (OpenSBI SRST is a no-op on this board), SD reliability depends on card quality, and several drivers (NVMe/PCIe, some peripherals) are build-only pending on-hardware validation.

Because this is a hardware port, "builds clean" and "validated on the board" are tracked separately throughout STATUS.md — trust the on-hardware notes.

Milestones

A rough arc of the major milestones so far (STATUS.md has the blow-by-blow):

• ✅ FreeBSD/riscv64 boots to multiuser on the RV2 — console → storage → SMP → login:
• ✅ SpacemiT K1 SoC enablement — clock/reset, pinctrl, I²C, P1 PMIC + regulators + RTC, CRNG, thermal, UART clock, SDHCI, USB2/USB3, PWM, SPI/QSPI, PCIe (much of it hardware-validated; the rest builds clean pending board time)
• ✅ Both onboard Gigabit NICs working (if_smte, ported from OpenBSD)
• ✅ Remote reboot solved via the K1 watchdog, working around the no-op OpenSBI SRST
• ✅ OPNsense cross-built for riscv64 (emulated + native poudriere) with a self-hosted package/firmware update mirror
• ✅ WebUI up; Unbound resolver fixed and made boot-reliable on this RTC-less board
• ✅ AP6256 Wi-Fi — station scan/associate and WPA2 access-point mode
• ✅ R51 — the hostap vap-teardown kernel hang fixed and folded into the RV2PROD production kernel + a flashable SD image with matched kernel+modules
• ✅ Deployed inline as a working home firewall and validated end-to-end
• 🔜 Cut a released SD image, activate the CI runner, and finish on-hardware validation of the remaining drivers (NVMe/PCIe, peripherals)

Repository layout

├── SPEC.md            # project brief + ground rules (read section 2 first)
├── STATUS.md          # living worklog, newest entries at top (start here)
├── src/
│   ├── freebsd/       # SpacemiT K1 FreeBSD kernel drivers (CCU, PMIC, EMAC,
│   │                  #   SDHCI, PCIe, USB, I2C, pinctrl, brcmfmac Wi-Fi, DTS…)
│   ├── firmware/      # AP6256 redistributable Broadcom Wi-Fi firmware
│   └── tools/         # on-board helpers (e.g. wdtreset watchdog reboot)
├── scripts/           # image build, CI pipeline, poudriere, deploy, UART tools
│   └── ci/            # build-and-publish + builder-pipeline
├── tools/fw_env/      # read/write the U-Boot env in SPI-NOR from FreeBSD
├── config/            # loader.conf and build config
└── docs/              # hardware audit, build guides, CI, mirror hosting, patches
    └── hardware/      # the authoritative K1 SoC hardware audit + register maps

Building

Start with BUILD.md — the consolidated, contributor-friendly "how do I build (or run) this?" guide. It walks the whole flow (host prerequisites → kernel → packages → image → flash) and links out to the detailed docs below.

Image and kernel builds are driven by the scripts under scripts/ and documented under docs/:

• OPNsense image build: docs/opnsense-image-build.md, driver script scripts/build-opnsense-image.sh (and scripts/boottest-opnsense-image.sh to boot-test in an emulator).
• CI / cross-build pipeline: docs/ci-riscv64-rust-pipeline.md, docs/ci-selfhosted-runner-setup.md, and scripts/ci/.
• Poudriere package builds: scripts/poudriere-setup.sh.
• riscv64 update/firmware mirror: docs/opnsense-riscv-update-channel.md.
• Kernel deploy & serial recovery: scripts/deploy-kernel.sh, docs/loader-autoboot-serial-recovery.md.

The .ps1 scripts under scripts/ are Windows-host helpers (Hyper-V VM provisioning, SD flashing, UART console/logging). See STATUS.md and SPEC.md for how the pieces fit together before building.

Contributing

Contributions are welcome — this is exactly the kind of project that benefits from more people with the board on their desk. Please read CONTRIBUTING.md first; it covers the build flow, the branch/PR conventions, and (importantly) how to report what you tested on real hardware vs. build-only.

License

Original contributions are BSD-2-Clause (© 2026 Daniel Shue) — see LICENSE. This repo also carries upstream-derived FreeBSD/OpenBSD/Linux code and Broadcom firmware that remain under their own licenses; the top-level license does not relicense them. See NOTICE and the per-file SPDX headers for the details.

This is a personal fork/port for research and hobbyist use. Upstreaming to FreeBSD or OPNsense proper is out of scope for this repository (see CONTRIBUTING.md).