blueflare/bfe-core1106-sdk
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

public-readiness: scrub internal details, split licensing, hosted kernel-build

Browse Source 
Preparing the repo to go public (ADR-0007):

- CI: kernel-build moves from the self-hosted runner to ubuntu-latest
  (installs its own cross toolchain + qemu, caches the pristine tarball).
  On a public repo a registered self-hosted runner is reachable from
  approved fork-PR workflows — i.e. arbitrary code on private
  infrastructure — and the build never actually needed the SDK host.
  ADR-0004 marked superseded-in-part; docs/ci-cd.md rewritten (site
  specifics now live only in the private deployment log).
- Licensing: LICENSE gains the GPL-2.0 carve-out for patches/ and the
  kernel source excerpts (Linux derivatives; per-driver provenance was
  already tracked in PROVENANCE.md); patches/README.md states it too.
- Scrubbed from the tip: bench-unit dev credentials and its gadget IP
  (m2-boot notes), the site AP SSID+BSSID and a neighboring AP's BSSID
  and the device WLAN MAC (wifi bring-up evidence — BSSIDs are
  geolocatable), the runner mesh IP. NOTE: these remain in git history;
  decision on a pre-publication history rewrite is separate.
- Emoji cleanup across 21 tracked files (kernel port docs, review report,
  enforce-mcdc.sh) per repo text conventions: status marks became
  [x]/[wip]/[ ]/OK plain text.
- "[maintainer]-gated" process phrasing normalized to "maintainer-gated"
  (attributions in dated evidence docs kept).

Verified: zero emojis tracked; scrub grep clean; patches carry no internal
references; ci.yml parses; shellcheck unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018HUayid7W5w7jBdb9Rrj1K
This commit is contained in:
BFE Engineering
2026-08-30 07:25:57 -06:00
co-authored by Claude Fable 5
parent fea36faaec
commit 5155224594
33 changed files with 213 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+3 -3
View File
@@ -65,7 +65,7 @@ supervisor logic runs in CI with no panel.
the boot-mode register's survives-warm-reset / cleared-by-POR behaviour (the MaskRom
recovery maneuver). The matching firmware-side `Bus` seam on flared's `devmem` — so
the shipped ladder can be asserted to poke the confirmed offset, never the wrong-SoC
one — lands when flare-edge consumes warden-sdk (§7 item 3, [maintainer]-gated), not yet on
one — lands when flare-edge consumes warden-sdk (§7 item 3, maintainer-gated), not yet on
flare-edge `main`.
- **`modbus` — RS-485 device end.** Done. `ModbusSlave`: a byte-in/byte-out RTU slave
(CRC16 byte-identical to the master, FC 0x01–0x06/0x0F/0x10/0x11, exception replies,
@@ -88,7 +88,7 @@ supervisor logic runs in CI with no panel.
Integration with flare-edge: flared implements `MemBus` for `/dev/mem` and gains
`#[cfg(test)]` tests driving its real arm/beat logic against `HpmcuSim`. This needs
warden-sdk reachable as a Cargo dependency in CI — i.e. a remote for this repo,
which is a **[maintainer]-go-ahead item** (credential/remote creation). Until then the
which is a **maintainer go-ahead item** (credential/remote creation). Until then the
firmware-side seam and a local test double land in flare-edge, unified with `sim/`
once the dependency exists. No duplication of *logic* — only the tiny trait.
@@ -185,7 +185,7 @@ memory-map faults; and "boots under emulation" is never on-silicon evidence.
2. **C-driver MC/DC harnesses** — `relays.c` and `freshness.c` at 100% MC/DC, CI-gated
via the shared `drivers/enforce-mcdc.sh`. **Done** (the first C coverage gate).
3. **flared devmem/hpmcu seam + tests** — firmware-side trait, unified with `sim/`
once flare-edge consumes warden-sdk (a separate, [maintainer]-gated step). **Pending.**
once flare-edge consumes warden-sdk (a separate, maintainer-gated step). **Pending.**
4. **Config-lint CI gates** (§5) — the brick-class of bug. **Done.**
5. **Hermetic kernel build** (`build/build-kernel.sh` + the `patches-apply` gate). **Done.**
6. **Kernel 5.10→6.18.46 forward-port** (§6, ADR-0001). **Done** (hardware-verified).
docs/ci-cd.md
+18 -48
View File
@@ -1,63 +1,33 @@
# CI/CD
`.github/workflows/ci.yml` — everything portable runs on GitHub-hosted
`ubuntu-latest`; only the heavy kernel build uses the self-hosted runner.
`.github/workflows/ci.yml` — every job runs on GitHub-hosted `ubuntu-latest`.
No self-hosted runner is (or may be) reachable from this repo's workflows:
the repo is public, and a fork PR that gets one approved run could otherwise
execute code on private infrastructure (ADR-0007).
## Jobs
| Job | Runner | What it does |
|---|---|---|
| `test` | ubuntu-latest | `cargo test` (sim + config-lint) + `cargo-llvm-cov` line coverage on `sim`; outputs `passed`/`coverage`. |
| `test` | ubuntu-latest | `cargo test` (sim + config-lint + qemu/rs485-bridge) + `cargo-llvm-cov` line coverage on `sim`; outputs `passed`/`coverage`. |
| `mcdc` | ubuntu-latest | 100% MC/DC enforced on every `drivers/*/test` (gcc-14 `-fcondition-coverage`). |
| `bench` | ubuntu-latest | Smoke-runs the sim micro-benchmarks; emits ns/op trend JSON. |
| `bench` | ubuntu-latest | Smoke-runs the sim + rs485-bridge micro-benchmarks; emits ns/op trend JSON. |
| `patches-apply` | ubuntu-latest | Fetches pristine linux-6.18.46 (cached, sha256-verified) and applies `patches/*` in order. |
| `kernel-build` | **[self-hosted, warden-sdk]** | `build/build-kernel.sh` → `zImage` + `rv1106-warden.dtb`, uploaded as an artifact. Dispatch-gated until the runner is fully provisioned (below). |
| `qemu-tools` | ubuntu-latest | shellcheck on `qemu/**.sh`; builds the initramfs (pinned busybox) and the A/B disk image. |
| `kernel-build` | ubuntu-latest, **dispatch-only** | apt-installs the cross toolchain + qemu, `build/build-kernel.sh` → `zImage` + `rv1106-warden.dtb`, QEMU `-M virt` boot smoke (fail-closed), artifact upload (best-effort). Trigger: `gh workflow run ci.yml`. |
| `prune-artifacts` | ubuntu-latest, dispatch-only | Deletes `kernel-rv1106` artifacts beyond the newest 3. |
| `badges` | ubuntu-latest | Renders loc/tests/coverage shields on push to `main` (`[skip ci]` + `paths-ignore` loop guard). |
## The self-hosted runner (`bfe-mpc-0640`)
## History: the self-hosted runner (retired)
A **third** repo-scoped runner instance on `bfe-mpc-0640` (alongside `flare` and
`flare-edge`), registered with the label **`warden-sdk`** as
`bfe-mpc-0640-warden-sdk`, in `~/actions-runner-warden-sdk`.
> **INSTALLED + ONLINE (2026-08-25).** The runner is a running systemd service
> (`actions.runner.bfe-noah-warden-sdk.bfe-mpc-0640-warden-sdk.service`, `enabled`,
> cgroup-capped `CPUQuota=400%`/`MemoryMax=6G`) and `kernel-build` has been verified
> end-to-end (RV1106 6.18.46 → `zImage` 8.25 MB + `rv1106-warden.dtb`). Steps 1–2
> below are the record of that install (they needed `user`'s sudo on 0640); steps
> 3–4 are handled inside the workflow, so the host needs no manual toolchain/python.
1. **Install as a service** (persistence): `cd ~/actions-runner-warden-sdk &&
sudo ./svc.sh install user && sudo ./svc.sh start`. Until then the runner is
*offline* and `kernel-build` only runs when dispatched against an online runner.
2. **Resource cap** (protect the shared host): a drop-in at
`/etc/systemd/system/actions.runner.bfe-noah-warden-sdk.*.service.d/*.conf` with
`CPUQuota=400%` + `MemoryMax=6G`, then `sudo systemctl daemon-reload`. The build
inherits that cgroup. (The workflow also passes `JOBS=4` as a belt-and-braces bound.)
3. **Kernel cross toolchain** — done in the workflow: the `kernel-build` job sets
`CROSS_COMPILE=arm-linux-gnueabihf-` (Debian `gcc-arm-linux-gnueabihf`, already on
the runner) and `build-kernel.sh` honors it. The kernel is freestanding, so the
generic arm cross compiler links it — no Luckfox SDK toolchain path needed. (To use
the SDK uclibc toolchain instead, set `SDK_TC` to its `bin/` and drop the override.)
4. **`python`** (not python3) — done in the workflow: the `kernel-build` job symlinks
`python`→`python3` into `$RUNNER_TEMP/bin` and prepends it to `$GITHUB_PATH`. No
host-side venv/shim needed.
Host build deps: `dtc bc flex bison libssl-dev` — already present on 0640.
5. **`qemu-system-arm`** (for the boot-smoke step inside `kernel-build`, added
with the `qemu/` device sim — ADR-0006): one-time
`sudo apt-get install qemu-system-arm` on 0640. The step is
**fail-closed** — a missing qemu binary fails the job with a message
pointing here; it never silently skips.
> **INSTALLED (2026-08-30).** QEMU 10.0.11 via apt as `user` on 0640
> (reached over the mesh at `[mesh-ip]`); `cpio` and `curl` were already
> present. Recorded in flare-deployment `docs/deploy-log.md`. First
> dispatched `kernel-build` will exercise the smoke step end-to-end once
> the account-wide Actions billing stall is cleared.
`kernel-build` originally ran on a repo-scoped self-hosted runner (ADR-0004,
2026-08-25, verified end-to-end) because hosted minutes were metered on the
private repo. Going public made hosted minutes free and made a self-hosted
registration a liability, so ADR-0007 moved the job to `ubuntu-latest` and
retired the registration. Site-specific install records for that runner live
in our private deployment log, not here.
## Badges
Static shields SVGs are committed by the `badges` job (private repo can't use
dynamic shields). The GitHub-native `ci.yml` status badge works live regardless.
Static shields SVGs are committed by the `badges` job. The GitHub-native
`ci.yml` status badge works live regardless.
docs/decisions/0003-standalone-repo.md
+2 -2
View File
@@ -10,11 +10,11 @@ no CI, tests, or versioning of their own. The SDK requirement (future-features-2
## Decision
A **private** `bfe-noah/warden-sdk` GitHub repo, standalone from day one with its own
CI/versioning. Work lands on a `bringup` branch; the first commit to `main` is gated
on a passing code-review-harness run, green CI, and [maintainer]'s fresh explicit go-ahead.
on a passing code-review-harness run, green CI, and the maintainer's fresh explicit go-ahead.
## Consequences
- flare-edge consumes warden-sdk later (flared depending on `warden-sim`, drivers
built from here) — a separate, [maintainer]-gated integration step; flare-edge is not
built from here) — a separate, maintainer-gated integration step; flare-edge is not
edited by the SDK-completion effort.
- Private for now (references bench devices / in-progress hardening); can be opened
later once scrubbed, matching how `flare-deployment` is handled.
docs/decisions/0004-ci-runner.md
+3 -1
View File
@@ -1,6 +1,8 @@
# ADR 0004 — CI/CD runner: 3rd repo-scoped self-hosted runner on 0640
**Status:** Accepted (2026-08-25).
**Status:** Superseded in part by ADR-0007 (2026-08-30) — `kernel-build` moved
to GitHub-hosted runners for the public repo and the self-hosted registration
is retired. Original decision below, kept for the record. (2026-08-25.)
## Context
The heavy kernel/firmware build needs the SDK toolchain and Buildroot's baked-in
docs/decisions/0005-driver-source-of-truth.md
+1 -1
View File
@@ -12,7 +12,7 @@ scratch tree (`flare-edge/research/linux-6.18.46/`).
Bring **hardened copies into `warden-sdk/drivers/`** as the canonical source-of-truth,
each with its HAL seam and a 100% MC/DC host harness. The RV1106 kernel deltas are
formalized as a patch series in `patches/`. flare-edge consumes warden-sdk later
(separate, [maintainer]-gated step).
(separate, maintainer-gated step).
## Consequences
- Realizes the seam architecture (ADR-referenced in `docs/architecture.md`).
docs/decisions/0007-public-repo-hosted-kernel-build.md
+37
View File
@@ -0,0 +1,37 @@
# ADR 0007 — Public repo: kernel-build moves to GitHub-hosted runners
**Status:** Accepted (2026-08-30). Supersedes the runner half of ADR-0004.
## Context
The repo is going public (free Actions minutes for hosted runners; open-source
alignment with the stack philosophy). Two facts change the ADR-0004 calculus:
1. **A self-hosted runner on a public repo is a standing hazard.** A fork PR
can modify workflow files; once any run of theirs is approved, workflows
can target the repo's registered self-hosted runners — i.e. arbitrary code
on the private host, which also serves production. GitHub's own guidance is
to never attach self-hosted runners to public repos, and personal-account
repos have no runner groups to scope the risk away.
2. **The build never needed the SDK host.** ADR-0004's premise ("needs the SDK
toolchain and Buildroot's baked-in absolute paths") does not apply to
`kernel-build`: the hermetic build is freestanding, uses Debian's
`gcc-arm-linux-gnueabihf`, and self-provisions `python`. It fits a hosted
runner (4 vCPU / 16 GB), and public-repo minutes are free.
## Decision
`kernel-build` runs on `ubuntu-latest`, apt-installing its toolchain, kernel
build deps, and qemu-system-arm, with the pristine tarball cached like
`patches-apply` does. It stays `workflow_dispatch`-only for now (a full build
per push is still noisy; flipping it to push-on-main later is one line). The
`warden-sdk` self-hosted runner instance is **deregistered from this repo**
before it goes public; the flare and flare-edge runner instances on the same
host are unaffected (those repos stay private).
## Consequences
- No path from public workflows to private infrastructure; nothing to babysit
in fork-PR approval settings beyond GitHub's defaults (still set "require
approval for all outside contributors" as belt-and-braces).
- Kernel artifacts no longer persist on the runner host; the GitHub artifact
(5-day retention + prune job) is the only build output channel.
- Hosted kernel builds are slower than the 0640 box but free and parallel;
the boot-smoke step rides along unchanged.