docs: tighten README and core docs
Second conciseness pass per review feedback: bullets and tables over prose (vendor-SDK failings, repo layout, sim models, kernel-port rationale, QEMU scenarios), duplicated content cut (provenance pointer, scenario prose the qemu README already carries). Also fixes two stale claims in architecture.md: the flared seam unification and real-image boot both landed (flare-edge #110, PR #8) but were still marked pending.
This commit is contained in:
BFE Engineering
@@ -10,36 +10,32 @@ A modern, open development environment for the **Luckfox Pico 86 Panel**
|
||||
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 — with tooling that is tested, benchmarked,
|
||||
reproducible, and honest about what runs on real silicon versus what is
|
||||
simulated.
|
||||
|
||||
Originally built as the SDK for WardenOS (BlueFlare Energy's wall-panel
|
||||
firmware), but nothing here requires it: if you have an 86 Panel, this repo
|
||||
gives you a modern kernel and a way to develop for the board without flashing
|
||||
it on every change.
|
||||
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, silently drops Kconfig options, and
|
||||
offers **no way to test hardware-dependent
|
||||
code off the device** — every change means flashing a panel. That is slow and
|
||||
occasionally destructive: a coprocessor load address that collided with
|
||||
unreserved kernel RAM bricked a bench unit, a mistake a static memory-map
|
||||
check would have caught before any flash (`tools/config-lint` now is that
|
||||
check). This SDK exists so the board is buildable, testable, and hardenable
|
||||
**without a panel in the loop**, on a maintained kernel.
|
||||
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 the vendor 5.10.160 tree
|
||||
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 (no RV1106 device tree, clock, display, RGA, NPU, or flash-boot support
|
||||
upstream); see `docs/decisions/0001-kernel-base.md`.
|
||||
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
|
||||
|
||||
@@ -64,71 +60,61 @@ done
|
||||
for d in drivers/*/test; do make -C "$d" check; done # 100% MC/DC gate (gcc >= 14)
|
||||
```
|
||||
|
||||
The kernel variant with the simulator's extra devices (PCI serial, watchdog,
|
||||
WireGuard, display) adds one env var to step 1:
|
||||
`WARDEN_KCONFIG_FRAGMENT=qemu/configs/virt.fragment`. See `qemu/README.md`
|
||||
for the scenario tests (portal, OTA apply, display + touch, watchdog).
|
||||
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
|
||||
|
||||
```
|
||||
patches/ the RV1106 forward-port onto pristine linux-6.18.46 (subsystem-split)
|
||||
build/ the hermetic kernel build (fetch pinned source -> apply patches -> zImage + dtb)
|
||||
qemu/ the device simulator: QEMU -M virt boots the real kernel and real userspace;
|
||||
A/B disk layout, RS485 bridge into sim/, scenario tests
|
||||
sim/ register-level hardware models (Rust): membus, HPMCU, CRU, Modbus, RGA, NPU
|
||||
drivers/ hardened hardware-facing drivers with HAL seams and 100% MC/DC harnesses
|
||||
kernel/ forward-port provenance and bring-up records (point-in-time; patches/ is canonical)
|
||||
tools/ config-lint (static memory-map gates) and dev tooling
|
||||
docs/ architecture, ADRs (decisions/), CI/CD
|
||||
```
|
||||
| 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 (`/dev/mem`, ioctls, serial, `/proc`) or a simulated backend on
|
||||
the host. The same seam is what the driver-hardening effort measures MC/DC
|
||||
against and what the simulator implements, so the two reinforce rather than
|
||||
duplicate each other. Full detail: `docs/architecture.md`.
|
||||
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`.
|
||||
|
||||
Three simulators, by design not one:
|
||||
|
||||
| Simulator | What it runs | What it proves |
|
||||
| Simulator | Runs | Proves |
|
||||
|---|---|---|
|
||||
| `sim/` | register-level Rust models | driver and supervisor logic, with fault injection |
|
||||
| `qemu/` | the real kernel + real userspace on `-M virt` | boot, init, daemons, networking, OTA, watchdog, display + touch |
|
||||
| `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 |
|
||||
|
||||
The device simulator covers the UI as well: with the production UI binary in
|
||||
`qemu/payload/`, `run.sh --display on` opens the panel's 720x720 screen in a
|
||||
window with mouse clicks landing as touch — device and UI in one VM
|
||||
(headless + scripted: `qemu/tests/ui-shot.sh`).
|
||||
|
||||
Boots and passes under emulation are never treated as on-silicon evidence;
|
||||
the simulators narrow which claims need a panel, they do not replace it.
|
||||
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 (`rkdeveloptool`, source-built
|
||||
components, an open simulator); GPL-2.0-only.
|
||||
- **Hard**: every seam has a fault-injection path — recovery code is tested
|
||||
- **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,
|
||||
- **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 own private repo, flare-edge; issue references and checkout paths
|
||||
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 — including real over-the-air updates against
|
||||
a mock portal.
|
||||
production binaries unmodified — real over-the-air updates included.
|
||||
|
||||
## License
|
||||
|
||||
**GPL-2.0-only**, repo-wide (see `LICENSE`; a per-file SPDX identifier
|
||||
governs where present). The kernel material in `patches/` and `kernel/` is
|
||||
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).
|
||||
**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).
|
||||
|
||||
Reference in New Issue
Block a user