diff options
| author | Arthur Hanson Rasmusson <arthur@vgpu.io> | 2026-10-02 11:28:49 -0400 |
|---|---|---|
| committer | Arthur Hanson Rasmusson <arthur@vgpu.io> | 2026-10-02 11:28:49 -0400 |
| commit | c17da06d6cd8b9c69449904637bf37729a962989 (patch) | |
| tree | b51618fd63b776cd545f64fd40729af6154996b2 /docs/07-developers | |
| parent | 002e3d7d13c414ea874abbee8d82803dd3a72fe5 (diff) | |
| download | open-iov-c17da06d6cd8b9c69449904637bf37729a962989.tar.gz open-iov-c17da06d6cd8b9c69449904637bf37729a962989.zip | |
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).
Diffstat (limited to 'docs/07-developers')
| -rw-r--r-- | docs/07-developers/02-development-and-analysis-environment.md | 8 | ||||
| -rw-r--r-- | docs/07-developers/onboarding-and-standards.md | 12 |
2 files changed, 16 insertions, 4 deletions
diff --git a/docs/07-developers/02-development-and-analysis-environment.md b/docs/07-developers/02-development-and-analysis-environment.md index 370cefc..114345b 100644 --- a/docs/07-developers/02-development-and-analysis-environment.md +++ b/docs/07-developers/02-development-and-analysis-environment.md @@ -189,6 +189,7 @@ capture them into sessions. make -C tools/rmtool && make -C tools/rmtop tools/rmtool/rmtool gpu list --format=json tools/rmtool/rmtool engine list && tools/rmtool/rmtool mem stats +cd debug/risc-v-gsp-rm-vm ./rmharness/harness.sh --session dumps/real-rm -- rmtool engine list --format=json ``` @@ -312,7 +313,7 @@ Detailed procedures are not duplicated here. |---|---|---|---| | New CUDA userspace (`libcuda` bump) | `cudatool.py info/delta`, `fdematch`, `diff_corpus.py`, name-map apply | guest smoke (`cuda_drv_test.c`), `cuda-ab`, symbol spot-checks | [`userspace/cuda/docs/07`](../../userspace/cuda/docs/07-version-upgrade-playbook.md); green-eye [`22`](../../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md) §2 | | New GSP/RM firmware version | decompile + diff RPC dispatcher/controls; Ghidra symbol inventory | `greeneye probe` first-touch, scripted/re-hosted `record`, `compare`, `version_diff.py` | [`05-operations/02` §4.1](../05-operations/02-debugging-and-maintenance-workflows.md) (upgrade runbook); green-eye [`07 P1`](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), [`21`](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md), [`22`](../../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md) §3 | -| New device / architecture | device profile data, ISA/image shape, PMU/SOE deltas | portability matrix, probe first-touch on the new image | [`06-portability/hardware-software-matrix.md`](../06-portability/hardware-software-matrix.md); green-eye [`07 P2/P3`](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), [`18`](../../debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md) | +| New device / architecture | device profile data, ISA/image shape, PMU/SOE deltas | portability matrix, probe first-touch on the new image | [`06-portability/hardware-software-matrix.md`](../06-portability/hardware-software-matrix.md) and [`03-device-validation-and-porting-sequence.md`](../06-portability/03-device-validation-and-porting-sequence.md); green-eye [`07 P2/P3`](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), [`18`](../../debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md) | | A/B accuracy ritual (real vs emulated) | M1–M6 metric definition | hardware/VFIO reference capture vs green-eye session | [`05-operations/01`](../05-operations/01-performance-correctness-security.md); green-eye [`06`](../../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md), [`07 P4`](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), [`25`](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md) | | RM 610 family | — | gate first; nothing opened before approval | green-eye [`23`](../../debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md) (hard gate), [`21` §3](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md) | @@ -361,3 +362,8 @@ dynamic session disposes, and physical confirmation gates any product change. Every path in this document was verified at the time of writing; when a tool moves, update this table first — it is the front door. + +<!-- change (2026-10-02): fix the host-oracle capture command to run from the +tool root and link the device-validation/porting sequence from the porting +table; scope: §7, §12 only; benefit: the copied rmharness command resolves the +wrapper and the device-port path is discoverable from the environment map. --> diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md index e62ec28..78100c4 100644 --- a/docs/07-developers/onboarding-and-standards.md +++ b/docs/07-developers/onboarding-and-standards.md @@ -62,8 +62,8 @@ open-iov/ ├── scripts/ build/load/test automation, VM harness ├── config/ hardware/version profiles (the portability surface) ├── firmware/ versioned firmware images + decompilation artifacts -├── (private) reverse-engineering study notes live untracked; -│ see the maintainers' study index +├── (private) reverse-engineering study notes live untracked, +│ outside the published tree ├── docs/ THIS documentation tree (start at docs/README.md) └── wiki/ long-form firmware/protocol deep dives ``` @@ -156,7 +156,7 @@ The following rules each come from a real bug and are enforced in review: | `tools/cuda-ab/` | host-vs-guest CUDA A/B harness (one deterministic workload, diffed results) | | `tools/rmq/` | host RM-API oracle for ground-truth GPU/RM data | | `tools/firmware_analyzer.py` + Ghidra scripts | firmware analysis pipeline | -| module debug parameters | guest-memory scanning/poking, VRAM inspection | +| module debug parameters | guest-memory scanning/poking, VRAM inspection; physical-backend parameters and debugfs state/control files (see [`../eng-ops.md`](../eng-ops.md) Part II) | | QEMU gdbstub workflow | guest virtual-memory inspection/writing | | `debug/risc-v-gsp-rm-vm/` (green-eye) | **# TOOL IN DEVELOPMENT - NOT READY YET!** — RISC-V GSP/uproc VM runtime inspection, session recording and `gsp-rm-vfio` accuracy measurement (see [`../05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md)) | | `wiki/` documents | protocol and firmware deep dives | @@ -193,6 +193,12 @@ make clean * Protocol changes: diff the RPC inventory before/after; attach both. * Memory-model changes: re-run the VA↔PA discovery tooling and a guest CUDA start-up; attach the trace. +* Live physical-backend cycles are **supervised only**: one cycle at a time, + never unattended, with the module sha256 recorded before and after and the + clean-release checklist walked every time. Do not retry after a + mutating-RPC failure or a wedge. A requested reboot needs a written reason + and a post-reboot plan before approval is asked (project hard rule). See + [`../eng-ops.md`](../eng-ops.md) Part II. * Never land a change that makes a rung regress, even "temporarily". ## 8. Security hygiene for contributors |
