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/07-developers/onboarding-and-standards.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'docs/07-developers/onboarding-and-standards.md') 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 -- cgit v1.2.3