From c17da06d6cd8b9c69449904637bf37729a962989 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). --- docs/06-portability/hardware-software-matrix.md | 46 +++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) (limited to 'docs/06-portability/hardware-software-matrix.md') diff --git a/docs/06-portability/hardware-software-matrix.md b/docs/06-portability/hardware-software-matrix.md index c839578..8fca9e9 100644 --- a/docs/06-portability/hardware-software-matrix.md +++ b/docs/06-portability/hardware-software-matrix.md @@ -35,7 +35,7 @@ yet and selection is compile-time (see §6). | Guest | Status | |---|---| -| Linux x86_64 (stock `nvidia.ko`, CUDA) | **Experimental** (bring-up; probe and `nvidia-smi` work, but there is no continuous guest testing and context creation is currently blocked — see §6.1) | +| Linux x86_64 (stock `nvidia.ko`, CUDA) | **Experimental** (bring-up; probe, `nvidia-smi` and the driver-API smoke pass, and CE copies are forwarded default-off, but kernel execution is blocked on GR engine-context validity and there is no continuous guest testing — see §6.1) | | Linux aarch64 | **Target** | | Windows x86_64 (WDDM driver, CUDA, 3D) | **Target** | | Other Unix (FreeBSD, ...) | Out of scope until demand | @@ -70,11 +70,34 @@ so new transports are a small, isolated implementation. 3. Record the differences; prefer configuration over code. 4. Publish the profile, the evidence, and any workarounds. +**Green-eye portability pipeline (experimental).** + + + +Before the profile change lands, run the firmware-side pipeline from +`debug/risc-v-gsp-rm-vm/` and attach its output: +`./greeneye.sh probe --symbols --record` for the first-touch map; +`./greeneye.sh symbols export ...` for a provenance-carrying symbol DB; +`python3 harness/portability_matrix.py --target --target +--out dumps/matrix-` for per-pair sessions and `compare` reports; +then classify profile-versus-logic deltas with the decision table in +`debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md` §4.1. The +command-level walkthrough is in the +[green-eye user guide](../05-operations/04-green-eye-user-guide.md); the +incident procedure, evidence expectations and rollback rules are in the +[Open-IOV Defensive Operations Runbook](../RUNBOOK.md) S5. + ### 5.2 New firmware version See [`../05-operations/02-debugging-and-maintenance-workflows.md`](../05-operations/02-debugging-and-maintenance-workflows.md) §4.1. Firmware images are versioned under `firmware/-GSP//` with -signatures and analysis artifacts. +signatures and analysis artifacts. The defensive procedure, evidence bundle +and rollback rules for this path are in the +[Open-IOV Defensive Operations Runbook](../RUNBOOK.md) S1. + + ### 5.3 New driver version @@ -118,6 +141,25 @@ config/ A profile is the *unit of support* — what is missing is the code that reads the profile files, not the profile schema. +**Evidence expectations for adding support.** + + + +A combination is entered in the matrix only with: the profile fields recorded; +the firmware/device pairing verified by hash and version string before any +debugging; a first-touch diff whose every changed address is explained as +profile or logic; a portability matrix report with per-pair `compare` results +and session hashes; the M1–M6 table with the reference-capture method and the +L2/L3 limits stated; and a supervised physical validation for the support +claim. "Tested and documented" is literal: an untested or simulator-only +combination stays **Target** or **Experimental**. The full bundle checklist +and fault tree are in the +[Open-IOV Defensive Operations Runbook](../RUNBOOK.md) §6–§7; the pipeline +commands are in the +[green-eye user guide](../05-operations/04-green-eye-user-guide.md). + ### 6.1 Userspace driver facts * **Guest CUDA driver** (`libcuda`) under test: **570.144** (md5 -- cgit v1.2.3