bfe-core1106-sdk/README.md

bfe-core1106-sdk

A modern, open development environment for the Luckfox Pico 86 Panel (Rockchip RV1106): a current Linux kernel as a reviewable patch series, a hermetic build, a QEMU device simulator, register-level hardware models, and MC/DC-hardened drivers (Modified Condition/Decision Coverage — the avionics-grade test bar). It replaces the vendor stack — a ~2 GB, twice-forked SDK pinned to Linux 5.10 — and is honest about what runs on real silicon versus what is simulated. Born as the SDK for WardenOS (BlueFlare Energy's wall-panel firmware); nothing here requires it.

Why

The vendor SDK:

• bakes in absolute paths and silently drops Kconfig options;
• offers no way to test hardware-dependent code off the device — every change means flashing a panel;
• let a memory-map mistake brick a bench unit (a coprocessor load address in unreserved kernel RAM) that a static check would have caught — tools/config-lint is now that check.

This SDK makes the board buildable, testable, and hardenable without a panel in the loop, on a maintained kernel.

What Works

A self-built Linux 6.18.46, forward-ported from vendor 5.10.160 as a subsystem-split patch series (patches/) and hardware-verified on a bench panel: clk, pinctrl, eMMC, GMAC, TRNG, OTP, SARADC/TSADC, RTC, USB host, PWM/backlight, VOP display, GT911 touch, AIC8800 wifi, RGA, I2S audio, the HPMCU (RISC-V watchdog coprocessor) mailbox, the open NPU driver, and PVTM. Mainline alone was not viable for RV1106 (ADR-0001).

Quick Start

Requirements: gcc-arm-linux-gnueabihf, qemu-system-arm, curl, cpio, mkfs.ext4, a bare python on PATH (Debian/Ubuntu: python-is-python3), gcc >= 14 (for the MC/DC gate), and Rust (for the simulators' tests).

# 1. Build the kernel: fetch pinned pristine 6.18.46, apply patches/, emit
#    zImage + rv1106-warden.dtb. WORK must sit outside any git checkout.
WORK=$HOME/kbuild-out CROSS_COMPILE=arm-linux-gnueabihf- bash build/build-kernel.sh

# 2. Boot it in the QEMU device simulator (no hardware needed):
bash qemu/mkinitramfs.sh
bash qemu/mkimage.sh
bash qemu/run.sh --kernel $HOME/kbuild-out/linux-6.18.46/arch/arm/boot/zImage --shell

# 3. Run the test suites:
for d in sim tools/config-lint qemu/rs485-bridge; do
  (cd "$d" && cargo test)
done
for d in drivers/*/test; do make -C "$d" check; done  # 100% MC/DC gate (gcc >= 14)

Add WARDEN_KCONFIG_FRAGMENT=qemu/configs/virt.fragment to step 1 for the kernel variant with the simulator's extra devices; qemu/README.md has the scenario tests (portal, OTA apply, display + touch, watchdog).

Layout

Directory	Contents
patches/	the RV1106 forward-port onto pristine linux-6.18.46, subsystem-split
build/	hermetic kernel build: pinned fetch → apply patches → zImage + dtb
qemu/	device simulator: QEMU -M virt boots the real kernel and real userspace
sim/	register-level hardware models (Rust): membus, HPMCU, CRU, Modbus, RGA, NPU
drivers/	hardened hardware-facing drivers: HAL seams, 100% MC/DC harnesses
kernel/	forward-port provenance and bring-up records (patches/ is canonical)
tools/	config-lint (static memory-map gates) and dev tooling
docs/	architecture, ADRs (decisions/), CI/CD

Architecture

One thin hardware abstraction seam per block (a trait in Rust, a function table in C): firmware logic talks to the seam; the seam binds a real backend on the device or a simulated backend on the host. MC/DC is measured against the same seam the simulator implements, so the two reinforce each other. Full detail: docs/architecture.md.

Simulator	Runs	Proves
sim/	register-level Rust models	driver and supervisor logic, with fault injection
qemu/	the real kernel + userspace on -M virt	boot, init, daemons, networking, OTA, watchdog, display + touch
lvglsim (downstream)	the LVGL UI on SDL	rendering and UI flows

With the production UI binary in qemu/payload/, run.sh --display on opens the panel's 720x720 screen in a window, mouse clicks landing as touch — device and UI in one VM. Emulation results are never on-silicon evidence; the simulators narrow which claims need a panel.

Principles

• Open — open tools over closed ones; GPL-2.0-only.
• Hard — every seam has a fault-injection path; recovery code is tested against failure, not just success.
• Modern — the newest kernel the hardware can run, current toolchains, Rust for new host-testable code, reproducible builds.

Downstream

WardenOS (the 86 Panel firmware this SDK was born for) consumes this repo from its private repo, flare-edge; issue references and checkout paths pointing there are context, not reachable links. The QEMU simulator runs its production binaries unmodified — real over-the-air updates included.

License

GPL-2.0-only, repo-wide (LICENSE; a per-file SPDX identifier governs where present). patches/ and kernel/ are derivative of the Linux kernel and GPL-2.0 vendor code; per-driver origin is tracked in kernel/rv1106-enablement/PROVENANCE.md. Contributions are accepted under the same license (inbound = outbound).