summaryrefslogtreecommitdiffstats
path: root/docs/07-developers/onboarding-and-standards.md
diff options
context:
space:
mode:
authorArthur Hanson Rasmusson <arthur@vgpu.io>2026-10-02 11:28:49 -0400
committerArthur Hanson Rasmusson <arthur@vgpu.io>2026-10-02 11:28:49 -0400
commitc17da06d6cd8b9c69449904637bf37729a962989 (patch)
treeb51618fd63b776cd545f64fd40729af6154996b2 /docs/07-developers/onboarding-and-standards.md
parent002e3d7d13c414ea874abbee8d82803dd3a72fe5 (diff)
downloadopen-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/onboarding-and-standards.md')
-rw-r--r--docs/07-developers/onboarding-and-standards.md12
1 files changed, 9 insertions, 3 deletions
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