diff options
Diffstat (limited to 'debug')
| -rw-r--r-- | debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md | 319 | ||||
| -rw-r--r-- | debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md | 246 |
2 files changed, 565 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md b/debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md new file mode 100644 index 0000000..4669f93 --- /dev/null +++ b/debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md @@ -0,0 +1,319 @@ +# 28 — Porting automation: driver-version sweep and new-device scaffold + +> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status and +> [`GREEN-EYE-ROADMAP.md`](../GREEN-EYE-ROADMAP.md) H4/R6 for the program. + +Two stdlib-only orchestrators turn the docs/07 P1/P2 playbooks and the +docs/22 porting guide into one repeatable chain: a **driver-version sweep** +(`harness/port_driver_versions.py`) and a **device-port scaffold** +(`harness/port_new_device.py`). They reuse the version-diff, portability-matrix +and mutation machinery already documented in docs/18 and docs/21, add the +RM 610 gate verbatim from `version_diff.py`, and never download firmware, +never touch hardware, and write only under `--out`. Both are **unadmitted +pilots** under `eng-ops.md` §2 — the keep/retire evaluation is F2/F3 in +[`future-eng-ops.md`](../../../docs/future-eng-ops.md), and a sweep is not +routine release tooling until that record exists. + +| Tool | Roadmap | What it does | +|---|---|---| +| `harness/port_driver_versions.py` | **R6**, H4.1 | Finds each driver/firmware version's local image, runs version_diff vs a baseline, the portability matrix and a mutation smoke, and assembles per-version evidence bundles plus a cross-version summary with the docs/06 M1–M6 skeleton. | +| `harness/port_new_device.py` | **R6**, H4.1, docs/07 P2 | Creates/uses a user-supplied device profile, probes the device firmware's first touch, builds a symbol inventory, runs the matrix against a reference, and emits a port checklist with a go/no-go recommendation. | + +Both are dry-run by default, resume-safe (sweep), bounded by QEMU budgets plus +a per-step wall-clock net, and simulator-only (no `/dev`, kernel module, mdev, +guest or physical GPU). + +--- + +## 1. The chain + +```text +new driver / GSP image lands on disk (runfile, .fwimage, re-hosted ELF) + | + +-- port_driver_versions --dry-run plan: inputs found/missing, steps, artifacts + | | + | +-- --run per version: + | 1. target discovery/identification (never downloads) + | 2. version_diff vs the chosen baseline + | 3. portability_matrix (baseline + candidate) + | 4. mutation_smoke (bounded, seeded) + | 5. per-version bundle-manifest.json + | +-- sweep-summary.json/.md (M1-M6 skeleton, pass/fail interpretation) + | + +-- port_new_device --dry-run plan: profile fields, firmware, steps + | + +-- --run profile + probe-first-touch + symbols + matrix + checklist +``` + +The chain is the automation of docs/07 P1 (new GSP version), P2 (same version, +new device) and the docs/22 port checklists; the metric contract stays +docs/06 §5. Evidence is always attachable to the docs/07 checklist and the +docs/14 §6 pack. + +--- + +## 2. Driver-version sweep + +### 2.1 Known branch cadence + +The default version list documents the branch cadence and where to edit it — +the tool never invents an image or downloads one: + +| branch | expected image | default sweep | +|---|---|---| +| 540 | earlier branch | yes | +| 550 | earlier branch | yes | +| 560 | earlier branch | yes | +| 570 | current anchor (570.144 and patches) | yes | +| 580 | expected cadence, no local image assumed | no | +| 610 | RM 610 gate, refused without approval (docs/23) | no | + +Edit `DEFAULT_VERSIONS` in `harness/port_driver_versions.py`, or override on +the command line / in a config file. A branch with no local image is reported +`no-input`; it is not an error and nothing is fetched. + +### 2.2 Invocation + +Dry-run first (the default; reads input directories only): + +```bash +cd debug/risc-v-gsp-rm-vm +python3 harness/port_driver_versions.py --input-dir ../../firmware/57X-GSP \ + --versions 540,550,560,570 +``` + +Execute, resume-safe, with explicit targets and per-version symbol DBs: + +```bash +python3 harness/port_driver_versions.py --run \ + --versions 570.144 \ + --target 570.144=../../firmware/57X-GSP/570.144/gsp-570.144.fwimage.bin \ + --baseline 570.144 \ + --symbols 570.144=symbols-570.144.json \ + --out dumps/sweep-570.144 +``` + +Cron (weekly, quiet, resume-safe; completed versions are skipped): + +```cron +17 3 * * 1 cd /path/to/open-iov/debug/risc-v-gsp-rm-vm && \ + python3 harness/port_driver_versions.py --run \ + --input-dir ../../firmware/57X-GSP --versions 540,550,560,570 \ + --out dumps/sweep-570 >> dumps/sweep-570/cron.log 2>&1 +``` + +Agent (docs/20): run the dry-run to get the plan, use +`portability_matrix_run`/`mutation_run` for single steps if the sweep itself is +not exposed by MCP yet, then read `sweep-summary.json` and the per-version +`bundle-manifest.json` from the bundle instead of recomputing. The dry-run plan +is machine-readable (`greeneye-port-sweep-plan/1`) and side-effect free. + +Flags that matter: + +* `--versions` / `--config` — explicit list or JSON config (below); +* `--input-dir` — recursive discovery of local `.fwimage`, `.fwimage.bin`, + `.elf`, `.bin` and `.run` files; version matching uses file and directory + names (`570` matches `570.144`); +* `--target VERSION=PATH`, `--symbols VERSION=PATH`, + `--ghidra-exports VERSION=PATH` — explicit inputs, no discovery; +* `--baseline` — version diffed against (default: earliest version found); +* `--extract-runfiles` — opt in to local `sh <runfile> --extract-only` + extraction when only a driver runfile is present (still never downloads); +* `--force` — re-run versions whose `version.json` reports `ok`/`partial`; +* `--step-timeout` — wall-clock safety net per step (`0` disables; QEMU + budgets remain the first bound); +* the usual `version_diff`/`matrix`/`mutation` budgets. + +### 2.3 Configuration file + +```json +{ + "format": "greeneye-port-sweep-config/1", + "versions": ["540", "550", "560", "570.144"], + "baseline": "570.144", + "input_dir": "../../firmware/57X-GSP", + "targets": {"570.144": ["../../firmware/57X-GSP/570.144/gsp-570.144.fwimage.bin"]}, + "symbols": {"570.144": "symbols-570.144.json"} +} +``` + +Unknown keys are refused so a typo cannot silently change the sweep. CLI flags +override config values. + +### 2.4 Output and evidence bundle + +```text +<out>/ + sweep-summary.json cross-version report (also .md) + bundle-manifest.json sha256 + size of every artifact below + <version>/ + version.json status, inputs, steps, M1-M6, sha256 + version.md rendered per-version report + bundle-manifest.json per-version evidence bundle + version-diff/ docs/21 §2.3 tree + portability-matrix/ portability-report.json|.md, symbols/, sessions/, compare/ + mutation-smoke/ findings.jsonl, summary.md, sessions/ +``` + +`sweep-summary.json` carries per-version status, the cross-version M1–M6 +skeleton (every agreement metric `not measured` without a reference capture, +docs/06 §5), the RM 610 gate record, and an explicit `interpretation` string: +`pass`, `fail` (with the failing versions) or `not-run`. + +### 2.5 Reading failures + +| Status | Meaning | Action | +|---|---|---| +| `ok` | all steps ran, none errored | attach the bundle to the docs/07 checklist | +| `partial` | a step skipped (e.g. no QEMU, no mutation kernel) | explain the skip; re-run where the capability exists | +| `error` | a step raised or timed out | inspect `<version>/version.json`, then the step report (`version-diff.json`, `portability-report.json`, `findings.jsonl`) | +| `no-input` | no local image found for the version | add the image under `--input-dir`, pass `--target`, or drop the version from the list | +| resumed | `version.json` already reported `ok`/`partial` | use `--force` to re-run | + +`--run` exits non-zero when any executed version errored or when nothing ran +at all; skipped steps alone do not fail the sweep, but they are always listed. +An unexplained delta blocks the docs/07 acceptance: an empty +unexplained-delta list is a claim, not a default. + +### 2.6 RM 610 gate (hard, testable) + +Versions numerically `>= 610` or labelled `rm610`/`RM-610` are refused before +any target file is opened — in dry-run too — unless `--approval-token +RM610-APPROVED` is passed or `GREENEYE_RM610_APPROVED=1` is set. The refusal +text points at [`docs/23-RM610-READINESS.md`](23-RM610-READINESS.md) and +states that nothing was downloaded and no target was opened. Do not put a 610 +input in a default list or a cron line before the §6 approval message exists. + +--- + +## 3. New-device scaffold + +### 3.1 Profile + +`--device <name>` uses `--profile FILE` or `<out>/profiles/<name>.json`. A +missing profile is created as a scaffold (`greeneye-device-profile/1`) with the +user-supplied sections and a `where_to_fill` map: + +* `pci` — vendor/device/subsystem IDs (`lspci`, vendor docs); +* `bars` — BAR layout and sizes (guest `lspci -vvv`, host sysfs); +* `fb` — VRAM/BAR1 geometry (host oracle `rmtool mem stats --format=json`); +* `engines` — engine inventory (host oracle `rmtool engine list --format=json`); +* `interrupts` — interrupt topology (MSI-X); +* `rom` — ROM/VBIOS notes and hash; +* `firmware` / `reference` — local image paths (or `--firmware`/`--reference`); +* `firmware_family` / `firmware_version` — the pairing record (docs/07 P2.2); +* `physical_validation` — supervised physical evidence, recorded by the human, + never by this tool. + +Profile data is user-supplied; the tool never guesses a device ID, BAR or +engine list. `config/hardware/*.yaml` remains a design target (see +hardware-software-matrix §6) — do not treat it as live configuration. + +### 3.2 Invocation + +```bash +# dry-run: check profile fields and inputs, create nothing +python3 harness/port_new_device.py --device rtx4090 --profile profiles/rtx4090.json + +# execute: scaffold profile (if absent), probe, symbols, matrix, checklist +python3 harness/port_new_device.py --run --device rtx4090 \ + --firmware ../../firmware/57X-GSP/570.144/gsp-570.144.fwimage.bin \ + --reference firmware/uproc_demo/build/uproc_demo.elf \ + --out dumps/port-rtx4090 +``` + +Output tree: + +```text +<out>/<device>/ + device-port.json / device-port.md + port-checklist.json / port-checklist.md + symbols/<device>.json merged ELF/Ghidra/green-eye DB + provenance + sessions/<firmware>-probe/ recorded first-touch session + portability-matrix/ matrix report + sessions + compare + bundle-manifest.json sha256 of every artifact +<out>/profiles/<device>.json scaffolded profile (when absent) +``` + +The checklist items are the docs/07 evidence checklist plus the docs/22 §3.1 +profile fields; the recommendation is `hold` until the simulator-side items +are complete, `simulator-evidence-complete` while physical validation is +pending, and `go` only when `physical_validation.status` is recorded. The last +row is deliberately outside this tool's reach: simulator-only evidence never +justifies a support claim (docs/22 §3.5, hardware-software-matrix §5.1). + +--- + +## 4. Tests, CI and MCP ties + +```bash +python3 -m unittest tests.test_porting_automation -v +make test # includes these with the rest of the suite +``` + +`tests/test_porting_automation.py` is deterministic: `--help` clean, +dry-runs side-effect free, missing-input handling without tracebacks, resume +detection, config validation, the RM 610 gate (refusal, token, env), and a +tiny one-version QEMU sweep against the demo ELF that must produce the +evidence bundle; QEMU-dependent tests skip cleanly when QEMU or the demo ELF +is absent. The repository CI workflow (docs/21 §5) runs the suite on pushes +and PRs touching the tool tree; a full sweep against real firmware is driven +manually/agentically, dry-run first, because it needs versioned inputs and +symbol DBs — the same policy as `ci_release` (docs/21 §4.1). + +MCP (docs/20) exposes the step-level tools (`probe_firmware`, +`portability_matrix_run`, `mutation_run`); the sweep is the CLI/agent entry +point that sequences them and owns the bundle. An agent should read the dry-run +plan, run, then read `sweep-summary.json`/`device-port.json` and the manifests +rather than recompute hashes. + +--- + +## 5. When to extend + +* **New branch cadence** — add the version to `--versions`/config; if it should + be swept by default, edit `DEFAULT_VERSIONS` and the cadence table above. + Never add an image you do not have; never add 580/610 to a default. +* **New per-version artifact** — add a step function in + `harness/port_driver_versions.py`, register it in `run_version`, and list the + path in `_expected_artifacts`. +* **New device profile field** — add it to `scaffold_profile`, `PROFILE_HELP` + and `profile_missing_fields`, and surface it in the checklist. +* **New architecture (GB10-class, aarch64)** — follow docs/07 P3 first; the + sweep handles the ISA/image shape and the matrix records the first-touch + deltas, but PMU/SOE and partition-model work belongs to the roadmap. +* **New product behaviour** — out of scope: these tools produce evidence, they + never edit `open-iov-vfio`. Product changes need the docs/07 P4 escalation + and a physical reference. + +--- + +## 6. Safety and limits + +* No downloads: discovery and `--extract-runfiles` only read files already on + disk; a driver runfile is never fetched. +* Simulator-only: own QEMU processes on demo/re-hosted ELF or raw firmware; + never a guest, kernel module, mdev, existing gdbstub or physical GPU. +* Bounded: QEMU probe/scenario/mutation budgets plus `--step-timeout`; the + mutation harness refuses non-demo ELFs unless explicitly allowed. +* No support claims: the sweep records what changed; the device checklist + holds until physical validation; the matrix and RUNBOOK process own the + "Supported" label (hardware-software-matrix §1). +* Fidelity limits are docs/06: L0/L1 observations only, L2/L3 (timing, + interrupts, device model) explicitly not claimed. + +## 7. Roadmap mapping + +| Item | Where this doc/tool contributes | +|---|---| +| **R6 — multi-version orchestration** | One sweep over 540→current with version_diff + matrix + mutation and a cross-version report | +| **H4.1 — semantic diffing** | Per-version symbol/corpus/behaviour deltas and recorded sessions | +| **H4.3 — mutation/fuzzing** | Seeded mutation smoke per version | +| **docs/07 P1/P2** | The playbooks become dry-run plans and evidence bundles | +| **docs/23 C5/C7** | Release pipeline extended by a sweep-scale orchestrator; 610 gate reused | +| **H7 — agentic platform** | Machine-readable plans, summaries and bundles for monitored agent runs | + +<!-- change (2026-10-02): state the unadmitted-pilot status and link the +future-eng-ops F2/F3 evaluation from the document that ships the scaffolds; +scope: intro only; benefit: no reader mistakes the sweep for admitted release +tooling. --> diff --git a/debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md b/debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md new file mode 100644 index 0000000..8be3704 --- /dev/null +++ b/debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md @@ -0,0 +1,246 @@ +# 29 — Packaging and trialing: sim + injected code as a deliverable + +> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> This is a development-only convenience layer over docs/12 (injection SDK), +> docs/16 (native simulator) and docs/24 (device map). It makes no hardware, +> timing or security claim; the real `.fwimage` path is honestly blocked on +> H2.2 and says so in every result. + +## 1. Purpose + +green-eye can already load an injected service into the native simulator and +invoke it (docs/12, docs/16 §1.1, `harness/value_demos/s06_inject_service.py`). +That evidence lives in the tool tree: a reviewer needs the checkout, the built +demo and SDK, and the exact command sequence. `harness/package_sim.py` turns +"the s06 scenario" into a self-contained, hash-addressed package that a third +party can run, inspect and compare: + +* one directory (or deterministic `.tar.gz`) containing the target, the service + blob, the scenario and a manifest of hashes; +* one entry point (`run.sh`) that boots the target **natively**, registers the + injected service, invokes it directly and through the firmware dispatcher, + runs a hook/watch pass, and writes `results.json` + `results.md`; +* a machine-readable manifest so a recipient can verify exactly which inputs + produced a result before trusting it. + +It exists to make a code addition trialable and reviewable, not to ship +anything: the eventual target is a modified, **unsigned** GSP image for the +simulator with tested injected code (§7). + +## 2. Exact usage + +All commands run from `open-iov/debug/risc-v-gsp-rm-vm`. Prerequisites: +`make demo && make sdk` (or pass `--service`), Python 3.10+; no QEMU needed. + +```bash +# 1) Demo trial (defaults: demo uproc + sdk/build/injected_demo.elf, slot 6) +python3 harness/package_sim.py --out /tmp/greeneye-trial-demo + +# 2) Build, archive and immediately run the trial +python3 harness/package_sim.py --out /tmp/greeneye-trial-demo --tar --run +/tmp/greeneye-trial-demo/run.sh # or run it yourself + +# 3) Combined artifact: the service is pre-injected at a fixed offset +python3 harness/package_sim.py --pack-image --out /tmp/greeneye-trial-packed +python3 harness/package_sim.py --pack-image --tar --run --out /tmp/greeneye-trial-packed + +# 4) Real 570.144 fwimage: image + service + lenient device map (blocked, see §5) +python3 harness/package_sim.py --target image \ + --image /path/to/gsp-570.144.fwimage.bin \ + --device-map dumps/570.144-device-map.json \ + --out /tmp/greeneye-trial-image + +# 5) Custom scenario and slot +python3 harness/package_sim.py --script my_scenario.py --slot 6 --out /tmp/my-trial + +# 6) Tests +python3 -m unittest tests.test_package_sim -v # 6 tests, ~4 s +``` + +Measured on the reference host (2026-10-02, CPython 3.12): a demo build plus +`run.sh` reports `trial: ok` in ~1 s wall; the test file (6 tests, including +the real-image bounded probe) runs in ~4.1 s. + +Flags: `--target demo|image` (default demo), `--image`, `--service`, +`--device-map`, `--script`, `--slot 0..7` (default 6), `--pack-image`, +`--tar`, `--run`, `--run-timeout`. `--out` must be empty or absent; builds do +not overwrite. + +## 3. Package layout and manifest schema + +``` +<out>/ + README.md what this is, how to run, what to expect, safety + run.sh single entry; finds the tool root (GREENEYE_HOME) and runs scenario.py + manifest.json format/version + hashes + component list + run contract + scenario.py the pre-scripted scenario as run (builtin or --script) + payload/ + <target>.elf|fwimage the target as supplied + injected_demo.elf the service blob + device_map.json only for image packages when no --device-map was given + combined.elf only with --pack-image + preinject.json only with --pack-image (placement config) + results/ produced by run.sh: results.json, results.md, session/ +``` + +`manifest.json` (`greeneye-trial/1`): + +| Key | Contents | +|---|---| +| `format`, `greeneye_version`, `created`, `results_schema` | identity; `created` is the only timestamp | +| `target` | `kind` (demo/image), `file`, `input` (repo-relative when possible), `sha256`, `entry`, `min_vaddr`, `max_vaddr`, `bias`, `runnable`, `limitations` | +| `service` | `file`, `input`, `sha256`, `entry`, `entry_symbol` (`ge_demo_service_dispatch`), `slot` | +| `device_map` | `file`, `input`, `sha256`, `lenient`, `learn` (null for a plain demo) | +| `script` | `kind` (builtin/custom), `name`, `input`, `sha256` | +| `preinject` | `file`, `runnable`, `reason`, `target_load_addr`, `target_entry`, `service_load_addr`, `service_offset`, `service_entry`, `entry_addr`, `slot`, `size`, `segments` (null without `--pack-image`) | +| `scenario` | demo boot/settle seconds, image instruction budget, `memory_mb`, expected call values | +| `run` | `command`, expected result paths, `exit_nonzero_on: "assertion failure"` | +| `safety`, `determinism` | policy text carried into the package | +| `components` | sorted `{path, role, bytes, sha256}` for every packaged file except the manifest itself | + +`results.json` (`greeneye-trial-results/1`): `status` (`ok`/`failed`/ +`blocked`), `success`, `backend`, `target`, `service` (load/entry addresses, +`preinjected`), `calls` (remote vs firmware with expected/agree), `hooks` +(`rpc_dispatch` hits and first entries), `watches` (`gsp_ctrl.result` hits), +`control`, `handlers_slot`, `uart_excerpt`, `session`, `assertions` +(`checks`, `failed`), `limitations`, plus `error` and the blocked fields +(§5) where applicable. `results.md` renders the same. + +## 4. How a user trials it and reads results + +1. Receive `<package>.tar.gz` plus its sha256 out of band; verify + `sha256sum <package>.tar.gz`. +2. Extract and run: `./run.sh` (add `--budget N` for image packages). The + script finds the green-eye tree by walking up, or via + `GREENEYE_HOME=/path/to/risc-v-gsp-rm-vm`. Exit codes: `0` pass (or the + documented blocked image status), `1` assertion failure, `3` tree not found. +3. Read `results/results.md` first, then `results/results.json` for machines. + Anything other than `status: ok` on a demo package is a finding, not a + flake: `assertions.failed` names the check (`handlers_slot_registered`, + `remote_ping`, `routes_agree`, `dispatch_hook_hits`, `uart_banner`, ...). +4. For deeper review, point the tools at `results/session/`: + `./greeneye.sh analyze <pkg>/results/session` and + `python3 -m greeneye compare baseline/results/session candidate/results/session`. +5. Verify provenance: each `components[].sha256` must match the packaged file; + `target.sha256`/`service.sha256` identify the inputs. + +The demo package asserts: the service is registered in +`gsp_ctrl.handlers[slot]`; direct and mailbox invocations agree with the SDK +ABI (`cmd 1: a0 ^ 0xbeef`, `cmd 2: a0 + a1`); at least one `rpc_dispatch` +hook hit and one `gsp_ctrl.result` watch hit; and the UART banner/self-test +lines are present. A bisected or broken service fails these and exits 1. + +## 5. The `--pack-image` path and its honest limits + +For the demo, `--pack-image` writes `payload/combined.elf`: the demo's PT_LOAD +segments plus the service's segments relocated to `target_base + 0x01000000` +(the same address `greeneye.inject.load_service` uses by default), merged into +one ELF64. `payload/preinject.json` records the placement, and the scenario +boots the combined ELF, writes the entry into the handler slot and skips the +separate blob load. Round-trip verified in +`tests/test_package_sim.py::test_pack_image_round_trip`: call results are +identical to the load/register path and `service.preinjected` is `true` in +`results.json`. This is the trial starting with the injected code already part +of the simulated system. + +For the real `.fwimage`, the package contains the image, the service blob and +a lenient `greeneye-device-map/1` map (given or emitted empty with +`learn: true`). **The native simulator cannot boot it yet**: the H2.2 device +model is absent. The scenario therefore runs a bounded, deterministic lenient +first-touch probe and records `status: blocked`, +`blocked_on_device_model: true`, `instructions_executed`, the stop PC, the +unmodelled MMIO list and (when learning) `results/learned_device_map.json`. +Reference measurement: a 200 000-instruction budget (199 998 executed), +stopped at `pc=0x84009070` (firmware `0x4009070`), exactly one unmodelled +access at `0x84009014` reading `0x2000000000000a00`, matching docs/24 §5. No +service is loaded, because no RM service registration point exists yet (M5) and the default load +address would overwrite the image. Exit is 0 for the documented blocked +status; a thrown error is recorded and exits 1. + +## 6. Sharing the results of a code addition + +1. Author builds the package with the service under review + (`service.sha256` is the code addition's identity) and runs it. +2. Attach `manifest.json`, `results/results.json`, `results/results.md` and + the `results/session/` directory; pre-injection evidence is in the session + as `service_injected`, `call_enter`/`call_return`, `watch_hit` and `bp_hit` + events, so the claim is replayable. +3. A baseline package with the previous service is diffed with + `greeneye compare`; the delta is the behavior change. +4. A reviewer re-runs the received package on the tool tree, verifies hashes + and expects the same `status`/call results. Divergence is a finding against + the package or the tree, not a nuance. +5. Nothing here is product evidence by itself: any conclusion that would + change `open-iov-vfio` still escalates to a physical capture (docs/06 §6, + docs/25 §2.1). The package makes that physical confirmation cheap, it does + not replace it. + +## 7. Eventual path: a modified GSP image for the simulator + +Once H2.2 can boot the real image (docs/16 M4) and the RM service registry +exists (M5), the same pipeline packages a **modified, unsigned** image: + +1. take the original `.fwimage` (hash in `target.sha256`); never a signed + production image, never a copy that can be flashed; +2. record the patch/injection recipe (`preinject`) and the verified device map + as versioned profile data keyed by `(device, firmware-family, profile)` per + docs/16 §7; +3. run the package's scenario, which boots the image under the H2.2 device + model, registers the tested service with the simulated RM core, and asserts + its behavior end to end; +4. attach the session as evidence and escalate any product-relevant finding to + hardware. + +Until M4/M5, image packages are deliberately non-runnable and labelled so; the +`preinject.runnable: false` + `reason` fields and the blocked result keep the +gap visible instead of implying a boot. + +## 8. Security and safety + +* The package executes only inside the in-process simulator: no hardware + access, no mdev, no guest, no kernel module, no network. `run.sh` invokes + Python in the tool tree found locally. +* Injected code runs with the simulator's full privileges and may corrupt + simulated firmware state (docs/12 §9). Treat every package as untrusted + code: run only packages whose sha256 and `manifest.json` you have verified, + in a scratch copy of the tree, and restart clean after a crash. +* Never use a package to inject into a guest, a shipped environment or real + hardware; never sign, flash or install a modified `.fwimage`. +* `/tmp` outputs are scratch; packages and sessions contain firmware bytes and + are development artifacts, not for redistribution outside the project. + +## 9. Review/evaluation criteria (keep vs prune) + +Keep the feature only while it earns its maintenance. This is an **unadmitted +pilot** under `eng-ops.md` §2: the evaluation recorded in +[`future-eng-ops.md`](../../../docs/future-eng-ops.md) F4 is the admission +decision. It is worth keeping if: + +* `python3 -m unittest tests.test_package_sim` stays green in CI in well under + a minute, including the bounded real-image probe; +* two builds under a fixed `SOURCE_DATE_EPOCH` are byte-identical + (manifest and `.tar.gz`) and an intentionally broken service fails the + assertions and exits 1 (add that negative test if it is missing); +* at least one code addition was actually reviewed from a package by someone + who did not author it, with hashes verified and results reproduced; +* the tar carries enough provenance (`manifest.components`, target/service/ + device-map/script hashes, `preinject` placement) for a reviewer to trust a + result without touching the author's checkout; +* the image path converts into a real H2.2 boot when M4/M5 land, and its + `blocked` status is removed rather than quietly left in place. + +Prune or rework it if: packages are never shared or reviewed (the s06 demo is +enough); the M5 native service registry subsumes `--pack-image`; the manifest +format churns without consumers; the real-image path stays permanently blocked +and adds only maintenance; or package results are being quoted as product or +hardware evidence. + +Evidence for this document: `harness/package_sim.py`, +`tests/test_package_sim.py` (6 tests), docs/12, docs/16 §1.1, docs/24 §4–5, +docs/25 §5–6. + +<!-- change (2026-10-02): use the tree's stdlib unittest runner instead of an +undeclared pytest dependency, and state the unadmitted-pilot status with the +future-eng-ops F4 evaluation; scope: §2 command, §9 only; benefit: the test +command runs with the same interpreter as CI and the keep/prune decision is +linked. --> |