summaryrefslogtreecommitdiffstats
path: root/docs/03-architecture/06-host-module-and-hybrid-model.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/03-architecture/06-host-module-and-hybrid-model.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/03-architecture/06-host-module-and-hybrid-model.md')
-rw-r--r--docs/03-architecture/06-host-module-and-hybrid-model.md37
1 files changed, 29 insertions, 8 deletions
diff --git a/docs/03-architecture/06-host-module-and-hybrid-model.md b/docs/03-architecture/06-host-module-and-hybrid-model.md
index d6b96e7..0dbc89a 100644
--- a/docs/03-architecture/06-host-module-and-hybrid-model.md
+++ b/docs/03-architecture/06-host-module-and-hybrid-model.md
@@ -140,7 +140,10 @@ section 3.7 for the analysis.
method streams and executes the work it understands in software - memsets,
copies and semaphore releases - and completes the corresponding semaphores.
That is a correctness bridge for memory operations, not the data plane: no
-CUDA kernel is forwarded to the physical GPU yet; the chosen execution backend
+CUDA kernel is forwarded to the physical GPU yet (default-off CE copy
+forwarding, engine-authored release relay and fault relay are implemented; see
+[`11-physical-backend-guest-wiring.md`](11-physical-backend-guest-wiring.md));
+the chosen execution backend
(a module-owned GPU running its real GSP firmware as the resource-manager
server) is in
[`08-physical-gpu-integration.md`](08-physical-gpu-integration.md), with the
@@ -149,10 +152,11 @@ trade-offs in
section 3.
**Subsystem status note.** Some components are compiled but not currently
-wired into the live path: the physical-GSP load/boot path is skipped in favour
-of emulation, and the runtime firmware analyzer, version tables, hardware
-abstraction tables and dynamic RPC dispatcher are not yet called by the live
-flow. Treat their descriptions here as intended design, not active code.
+wired into the live path: the physical-GSP load/boot path is default-off and
+runs only behind the supervised claim gates, and the runtime firmware
+analyzer, version tables, hardware abstraction tables and dynamic RPC
+dispatcher are not yet called by the live flow. Treat their descriptions here
+as intended design, not active code.
### 3.3 Event channels and interrupts
@@ -263,6 +267,22 @@ emulated device inspectable without rebuilding:
| `sema_map_add=<va>,<pa>` | teach the service one verified `{GPU VA -> guest PA}` pair |
| `dump_guest=<gpa>,<len>` | dump guest physical memory (length capped) |
+The physical-backend path adds a second, default-off parameter set:
+`gsp_phys_gpu`, `gsp_phys_hazard_ack`, `gsp_phys_fw`, `gsp_phys_mdev_owned`,
+`gsp_phys_static_live`, `gsp_phys_ctrl_forward`, `gsp_phys_work_forward`,
+`gsp_phys_guest_mem`, `gsp_phys_work_defer_release`,
+`gsp_phys_work_hw_primary`, `gsp_phys_relay`, `gsp_phys_fault_relay`,
+`gsp_phys_fault_inject`, `gsp_phys_rmcall_engine`,
+`gsp_phys_rmcall_gr_promote`, `gsp_phys_repower`, `gsp_phys_layout`,
+`gsp_phys_boot`, `gsp_phys_boot_dryrun`, `gsp_phys_nocat` and the
+`gsp_phys_fwsec*` stage controls. Their semantics, the physical-backend
+debugfs inventory (`gsp-phys-state`, `gsp-phys-rm-probe`, `gsp-phys-rm-call`,
+`gsp-phys-unload-rpc`, `gsp-phys-guest-ram`/`gsp-phys-guest-gpa`,
+`gsp-phys-log-dump`, `gsp-phys-status-drain`) and the supervised runbooks are
+maintained in the engineering-operations document
+([`../eng-ops.md`](../eng-ops.md), Part II); this document does not duplicate
+those tables.
+
These are development-grade but production-useful: they are how the memory
model was reverse-engineered, and they remain the fastest way to diagnose a
mismatch. Their workflows are documented in
@@ -312,8 +332,9 @@ in `kernel-open` first).
| Message queues + RPC + all init controls observed from stock 570.144 | implemented |
| Guest sysmem access + VA↔PA discovery | implemented (debug-grade, to be productized) |
| Push decoding + semaphore completion | demonstrated live; being productized |
-| Page-table population for server-owned ranges | designed, not implemented |
-| GPU work forwarding (GR/CE execution) | designed, not implemented |
-| Execution backend (module-owned GPU + direct real-GSP session) | mechanism chosen; ownership + firmware staging verified live; power-domain lock implemented, pending supervised verification; real GSP boot not started ([`08-physical-gpu-integration.md`](08-physical-gpu-integration.md)) |
+| Guest-RAM physical path | implemented default-off: guest RAM is file-backed shared memory and GPA→HPA goes through its page cache, verified live on the CE |
+| Page-table population for server-owned ranges | implemented default-off: forwarded CE copies map resolved host pages through module-built GMMU scratch page tables; real guest page tables remain |
+| GPU work forwarding (GR/CE execution) | CE forwarding, engine-authored release relay and fault relay implemented default-off and verified live; GR execution open |
+| Execution backend (module-owned GPU + direct real-GSP session) | live: boot, init-done, full static-config reply and clean releases proven; RM client allocates objects/channels and has executed real CE copies; currently in the designed locked fail-safe after a GR context-promote wedge ([`08-physical-gpu-integration.md`](08-physical-gpu-integration.md)) |
| Real VRAM backing | designed, not implemented |
| Windows guest, Xen transport, aarch64 hosts | designed, not implemented |