bfe-core1106-sdk/README.md

# warden-sdk

The build, driver, and simulation SDK for WardenOS (the Luckfox Pico 86-Panel /
RV1106 HMI). A from-scratch replacement for the twice-ported vendor stack
(Rockchip SDK → Luckfox SDK → our patched fork), built to the same standard as
the rest of the firmware: tested, benchmarked, reproducible, and honest about
what runs on real silicon versus what we simulate.

> Status: **bootstrapping.** This repo is being stood up incrementally; today it
> hosts the hardware **simulator** and its tests. The kernel forward-port and the
> hermetic image build move in as each is proven. Until then, flare-edge still
> builds firmware from the vendored SDK + `sdk-patches/`; nothing here is on the
> production build path yet.

## Why a new SDK

The vendored SDK is a ~2 GB opaque fork of a fork. Our real changes to it lived,
until recently, as uncommitted edits in one working copy (`flare-edge/sdk-patches/`
is the tracked form). It bakes absolute paths, needs `python` (not python3),
silently drops Kconfig options, and — the failure that motivated this repo — gives
us **no way to test hardware-dependent code off the device.** Every driver change
had to be validated by flashing a panel. That is slow, and it is dangerous: it is
how a boot-loaded-watchdog change bricked a bench unit (the load address collided
with unreserved kernel RAM — a mistake a target-config check or a memory-map model
would have caught before any flash).

The SDK's job is to make the firmware **buildable, testable, and hardenable
without a panel in the loop**, and to move us onto a modern, maintained kernel.

## Goals (from future-features)

1. **Modern kernel.** Move to the newest stable Linux we can run on our current
   Buildroot LTS (2025.02.x). The realistic ceiling is **plan44's OpenWrt RV1106
   fork — Linux 6.6**, which carries 152 RV1106 patches and a devicetree for our
   exact board. Mainline is not viable (no DT/clk/display/RGA/NPU/flash-boot).
   This is a bounded, evidence-backed forward-port, not a mainline chase.
2. **Ported, hardened drivers → 100% MC/DC on the code we own.** "100% MC/DC on
   100% of drivers" is infeasible as literally stated: ~97% of driver LOC is
   vendor blobs (the AIC8800 wifi driver alone is 88.5K lines). So the target is
   **tiered**: real MC/DC on *our* hardware code (modbus master, relays, RGA
   wrapper, HPMCU supervisor, devmem/reset ladder); fault-injection + branch
   hardening for the vendor blobs behind a stable seam.
3. **A proper simulator.** Simulate the hardware the vendor SDK cannot: **RGA**
   (2D blitter), the **RISC-V HPMCU** coprocessor, and the **NPU** — plus the
   register/SRAM (`/dev/mem`) and sysfs surfaces the drivers touch — so driver and
   supervisor logic runs and is tested on the host, in CI, with no panel.
4. **Its own repo, held to firmware standards.** Tests, benchmarks, reproducible
   builds, CI. This repo.

## Architecture — one seam, two backends

The organizing idea is a thin **Hardware Abstraction Seam** per hardware block.
Firmware code talks to the seam (a trait in Rust, a function table in C); the seam
has two backends:

```
        firmware / driver logic
                  │
          Hardware Abstraction Seam        (devmem, hpmcu, rga, npu, modbus, gpio)
             ┌────┴────┐
        real backend   sim backend
      (/dev/mem, ioctl, (software model,
       /proc, serial)    host-testable)
```

- **On-device**, the seam binds the real backend (mmap `/dev/mem`, `librga`
  ioctls, the serial port, `/proc/rknpu`).
- **On the host**, it binds the **sim backend** — a faithful software model of the
  block. The HPMCU sim, for example, runs the SCR1 watchdog firmware's exact state
  machine (boot-grace, heartbeat-timeout, fire) against an in-memory mailbox, so
  the flared supervisor's arm/beat protocol is exercised end-to-end in a unit test.

The seam is the same object the driver-hardening effort measures MC/DC against,
and the same object the simulator implements — so the two goals reinforce rather
than duplicate each other.

## Layout

```
sim/        the hardware simulator (Rust): mailbox/devmem model, HPMCU, RGA, NPU.
drivers/    our own hardened drivers + their seams (as they migrate in).
patches/    the vendor-SDK delta (mirrors flare-edge/sdk-patches until it moves here).
build/      the hermetic image-build wrapper (kernel → rootfs → image), incremental.
ci/         CI: patches-still-apply, host tests, coverage, benchmarks.
docs/       architecture + ADRs (decisions/).
tools/      dev tooling.
```

## Principles

Evaluated against the stack philosophy — **openness, hardness, modernness**:

- **Open** over closed where we can: `rkdeveloptool` over the closed `upgrade_tool`;
  source-buildable `librga` over blobs where a source path exists; the simulator is
  fully open and ours.
- **Hard**: every seam has a fault-injection path (a wedged SDIO link, a stalled
  MCU, an RGA timeout) so recovery code is tested against failure, not just success.
  On-device claims still need on-device evidence; the sim narrows *which* claims
  need a panel, it does not replace that rule.
- **Modern**: newest kernel we can actually run; current Buildroot LTS; Rust for new
  host-testable code; reproducible builds.

## Relationship to flare-edge

flare-edge (WardenOS: the LVGL UI + the `flared` daemon) is the product; warden-sdk
is what builds and tests it. During bootstrap, flare-edge consumes warden-sdk piece
by piece: first the simulator (as a dev/test dependency), later the image build.
No flare-edge code moves here — only the SDK/build/sim/driver-seam layer.