From 260c73e72674d55bf8f082c0e1011075a0365a78 Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Fri, 2 Oct 2026 11:28:49 -0400 Subject: docs: engineering-operations playbook and project-wide status accuracy pass - docs/eng-ops.md gains Part II, live physical-backend engineering operations: hard rules, the full module-parameter matrix, the routine supervised cycle and clean-release checklist, the debugfs inventory, how to read gsp-phys-state, a debugging scenario catalogue (CTXNOTVALID/promote wedge, fail-safe WPR2, unload hangs, guest wedges, MMU/PTE and PBDMA faults, relay symptoms), a hazard register (crash causes and debugging side effects), the physical-backend OODA loop, and the work-context map with porting flows - architecture, implementation, operations, orientation, getting-started, portability, ecosystem and reference docs corrected to the current state: CUDA driver-API smoke green, CE-class work forwarding and engine-authored releases plus fault relay in place (default off), GR execution blocked on engine-context validity, the promote wedge and designed locked fail-safe, and P5 wave-2 subsumed - internal-reference cleanup in tracked docs (no analysis-source or local-archive references); historical architecture document bannered - README reading list and STATE-CURRENT frontier refreshed; new pages (runbook, green-eye user guide, porting sequence, porting/packaging notes) linked from the tree Link check: scripts/check-docs-links.py passes (56 files, no broken links). --- .../02-debugging-and-maintenance-workflows.md | 28 ++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'docs/05-operations/02-debugging-and-maintenance-workflows.md') diff --git a/docs/05-operations/02-debugging-and-maintenance-workflows.md b/docs/05-operations/02-debugging-and-maintenance-workflows.md index 8d711c6..cfc452d 100644 --- a/docs/05-operations/02-debugging-and-maintenance-workflows.md +++ b/docs/05-operations/02-debugging-and-maintenance-workflows.md @@ -322,6 +322,34 @@ version × each hardware family, run the step-5 bring-up sequence. When adding a version, extend the matrix rather than replacing the old column — regressions across versions are the cheapest bugs to catch. +### 4.1.1 Green-eye-assisted upgrade/porting workflow (experimental) + + + +For firmware-side questions the experimental green-eye tooling (see +[`03-risc-v-gsp-rm-vm.md`](03-risc-v-gsp-rm-vm.md)) turns steps 3–5 above into +a repeatable pipeline that produces attachable evidence before any emulation +change. It never replaces the physical backend when silicon truth is required, +and it never touches a guest, a kernel module or the installed driver. + +| Rung | Command (from `debug/risc-v-gsp-rm-vm/`) | Output | +|---|---|---| +| Probe | `./greeneye.sh probe --symbols symbols-.json --record` | first-divergence report; first-touch map | +| Symbols | `./greeneye.sh symbols export --index --bias 0 -o symbols-.json` | runtime-address symbol DB with provenance | +| Version diff | `python3 harness/version_diff.py --old --new --out dumps/vdiff-` | shape/symbol/corpus/probe/behavior diff plus the M1–M6 skeleton | +| Portability matrix | `python3 harness/portability_matrix.py --target --target --out dumps/matrix-` | per-target sessions and per-pair `compare` reports | +| Decide | `./greeneye.sh compare dumps/ dumps/ --symbols` | symbol-attributed deltas; a product change only after physical confirmation | + +Decision discipline: verify the pairing first; behaviour that moved without a +code change is usually a state/ordering fix; changed code on a live path is +prioritised; a symbol never hit in either run is a coverage gap, not dead code. +The full incident procedures (symptoms, evidence, response order, rollback) are +in the [Open-IOV Defensive Operations Runbook](../RUNBOOK.md) S1 and its OODA +ordering; the quickstart and tool chooser are in the +[green-eye user guide](04-green-eye-user-guide.md). + ### 4.2 New guest driver version 1. Install the stock driver in a guest (no patches). -- cgit v1.2.3