summaryrefslogtreecommitdiffstats
path: root/docs/03-architecture/10-interaction-and-scheduling.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/10-interaction-and-scheduling.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/10-interaction-and-scheduling.md')
-rw-r--r--docs/03-architecture/10-interaction-and-scheduling.md24
1 files changed, 12 insertions, 12 deletions
diff --git a/docs/03-architecture/10-interaction-and-scheduling.md b/docs/03-architecture/10-interaction-and-scheduling.md
index 3608dc5..ffc02d7 100644
--- a/docs/03-architecture/10-interaction-and-scheduling.md
+++ b/docs/03-architecture/10-interaction-and-scheduling.md
@@ -22,12 +22,12 @@ to, and where it stands.
| Guest doorbell signal (boot, mailbox, channel) | write into BAR0 shadow, observed by the polling service | steering only | [done] |
| Guest RPC request | element placed in a guest-sysmem message queue, read by the module over VFIO DMA | 10s of us per round trip | [done] |
| RPC reply + interrupt | module writes reply into the queue, signals eventfd, QEMU raises irqfd into KVM, MSI-X lands in the guest | us | [done] |
-| Push-buffer work | guest appends GPFIFO entries; the per-channel pump reads, decodes and applies them | per entry, us to low ms | [wip] |
-| Semaphore release to guest memory | module writes the payload word into the resolved guest page | us | [done] |
+| Push-buffer work | guest appends GPFIFO entries; the per-channel pump reads, decodes and applies them | per entry, us to low ms | [wip] (CE copies forward default-off; GR execution open) |
+| Semaphore release to guest memory | module writes the payload word into the resolved guest page; a forwarded CE copy can have the engine author it | us | [done] (relay default off) |
| VA-to-PA translation discovery | in-module structure walk, content scan, rescue, pins | us to seconds (scan bounded) | [wip] |
| Translation internalization from protocol | derive mappings from RM/UVM objects as they are created | us | [planned] |
-| Real channel submission | translated push stream on a real channel, real doorbell | us + hardware | [planned] |
-| Physical GPU interrupt | real MSI-X into the module's IRQ handler, relayed to guest trackers | us | [planned] |
+| Real channel submission | translated push stream on a real channel, real doorbell; the ladder's real submission is live | us + hardware | [wip] (guest forwarding default-off) |
+| Physical GPU interrupt | real MSI-X into the module's IRQ handler, relayed to guest trackers; forwarded-engine fault observation/relay exists | us | [wip] (default off) |
| mdev create / destroy | sysfs plus VFIO device registration | ms | [done] |
| Guest RAM mapping | VFIO / IOMMUFD maps guest pages for DMA | ms once | [done] |
| Teardown | ordered stop: VM, device close, mdev remove, module unload | s | [done] |
@@ -129,7 +129,7 @@ stateDiagram-v2
note right of Applying
State and notification operations are
applied from the emulation. Real engine
- work is forwarded [planned].
+ work is forwarded [wip/default-off].
end note
```
@@ -198,7 +198,7 @@ Rules the design enforces:
| Push entry decode | us per entry | thousands of entries per context |
| Rescue of an unreadable entry | bounded ms | only on translation misses |
| MSI-X to guest | us | completion latency floor |
-| Real submission + completion relay | hardware + us | the forwarded-work path [planned] |
+| Real submission + completion relay | hardware + us | the forwarded-work path [wip/default-off] |
The rule of thumb the architecture is built around: **state operations are
cheaper in the module than they would be on hardware; real work belongs on
@@ -250,7 +250,7 @@ flowchart TB
F --> G["KVM injects MSI-X vector"]
G --> H["Guest ISR runs"]
end
- subgraph PHY["Module and physical GPU [planned]"]
+ subgraph PHY["Module and physical GPU [wip/default-off]"]
I["Real channel doorbell"] --> J["GPU executes"]
J --> K["Physical MSI-X"]
K --> L["Module IRQ handler"]
@@ -260,9 +260,9 @@ flowchart TB
M -.-> E
classDef done fill:#d5f5d5,stroke:#1e7a1e
- classDef plan fill:#f8d7da,stroke:#9a1a1a
+ classDef wip fill:#fff3cd,stroke:#9a7b1a
class A,B,C,D,E,F,G,H done
- class I,J,K,L,M plan
+ class I,J,K,L,M wip
```
## 9. Lifecycle and teardown ordering
@@ -301,8 +301,8 @@ sequenceDiagram
participant GD as Guest driver
participant EMU as GSP-RM emulation
participant VT as Version profile
- participant BE as Execution backend [planned]
- participant FW as Real GSP firmware [planned]
+ participant BE as Execution backend (single live session)
+ participant FW as Real GSP firmware (live session)
GD->>EMU: version and capability queries
EMU->>VT: select profile for this driver family
@@ -327,7 +327,7 @@ sequenceDiagram
| Pin tables | authoritative injected translations | debug tooling; later protocol discovery | lookup fast path | [wip] |
| Pending release queue | releases awaiting a translation | decoder | service drain | [done] |
| Completion counters | per-channel progress published to guest pages | service | guest trackers | [done] |
-| Real channels and page tables | forwarding state | backend | real GPU | [planned] |
+| Real channels and page tables | forwarding state (real channel live; guest page tables open) | backend | real GPU | [wip] |
## See also