NoahandClaude Opus 5
a367991998
LVGL and the vendor RV1106 SDK are what this platform is built against, and nothing in this repo said WHICH ones. The two live outside every worktree as shared checkouts, so "the version we build against" was whatever happened to be on the machine. They are pinned here now, by exact commit, with one script that obtains and verifies them. Not copied: between them they are ~21 GB, the vendor SDK bakes absolute paths into its host tools so it has to sit at one stable path anyway, and a 21 GB git repo would be unusable while still not making anything reproducible. What makes a build reproducible is knowing exactly which tree was used, which is a commit id -- the same reasoning build/fetch-kernel-tarball.sh already applies to the kernel, where a sha256 pin stands in for vendoring the tarball. Two behaviours worth stating, because both were wrong in the first draft: - A checkout is detected by `.git` EXISTING, not by it being a directory. LVGL is checked out as a worktree here, where `.git` is a file. - Local modifications are reported and are NOT a failure. The vendor SDK is supposed to carry them -- tools/build-firmware.sh applies our sdk-patches series into that tree on every build -- so a pristine checkout is the unusual state. Only a MISSING or DRIFTED tree fails. Nothing is ever reset automatically: a tree off its pin is reported, because a local change to a vendor tree is usually someone mid-debug, not something to throw away on their behalf. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T2D2KtdgwbhbF6Mo64eUrn
98 lines
5.1 KiB
Markdown
98 lines
5.1 KiB
Markdown
# bfe-core1106-sdk
|
|
|
|
[](https://github.com/blueflare-energy/bfe-core1106-sdk/actions/workflows/ci.yml)
|
|
|
|
|
|
|
|
|
|
|
|
A modern, open development environment for the **Luckfox Pico 86 Panel**
|
|
(Rockchip RV1106), replacing the vendor SDK, and honest about what runs on
|
|
real silicon versus what is simulated.
|
|
|
|
| | Vendor SDK | This repo |
|
|
|---|---|---|
|
|
| **Kernel** | 5.10.160, twice-forked, frozen | **6.18.46**: a reviewable, subsystem-split patch series onto pristine upstream; full peripheral set (display, touch, wifi, audio, NPU, ...) hardware-verified on a bench panel |
|
|
| **Build** | ~2 GB tree, absolute paths baked in, Kconfig options silently dropped | one hermetic script: sha256-pinned source fetch, fail-closed patch apply and config fragments |
|
|
| **Off-device testing** | none; every change means flashing a panel | register-level hardware models (`sim/`) plus a QEMU device VM booting the real kernel, real daemons, and the real UI with display + touch |
|
|
| **Config safety** | memory-map mistakes reach hardware (one bricked a bench unit) | static gates (`tools/config-lint`) catch them before any flash |
|
|
| **CI** | none | hosted pipeline: tests, coverage, benchmarks, patch-apply gate, kernel build with an in-CI QEMU boot smoke |
|
|
| **Flashing tools** | closed (`upgrade_tool`) | open (`rkdeveloptool`) |
|
|
| **License** | mixed | **GPL-2.0-only**, with a per-driver provenance ledger |
|
|
|
|
## 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 (driver harnesses), and Rust (for the simulators' tests).
|
|
|
|
```sh
|
|
# 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 # driver harnesses (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, test harnesses |
|
|
| `kernel/` | forward-port provenance and bring-up records (`patches/` is canonical) |
|
|
| `tools/` | `config-lint` (static memory-map gates) and dev tooling |
|
|
| `build/vendor.manifest` | the third-party trees this platform builds against (LVGL, the vendor RV1106 SDK), pinned to exact commits; `build/fetch-vendor.sh` obtains and verifies them |
|
|
| `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. The driver test harnesses
|
|
measure 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.
|
|
|
|
## 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).
|