Difference between revisions of "Project Plan"
m (2026-11-15 status refresh: DS stage image authored+live (st0=st1=020a0481; DS 0x86040626->0x84000420, two boots); draw-issue mac=0x22 and stores remain; X start lottery limits the run rate) |
m (2026-11-15 (evening) status refresh: saved-window release carrier deterministic (c772), slot-34 census + SA[34] golden fill (0x265), release-window reorder landed but unexercised; the remaining blocker is call order; pack-completion lottery; DS 0x84000420 and stores remain) |
||
| Line 5: | Line 5: | ||
<blockquote>'''Scope.''' The sequence of work: the phases, the gates that close them, what comes next, and how the plan itself is maintained. This is the ''roadmap'' view — [[Project Goals|<code>Project-Goals.md</code>]] says what the project is for, [[Project Status|<code>Project-Status.md</code>]] says where it stands today, and this page says in what order the remaining work happens and what must be true before each step. Canonical sources: the compute milestone ladder in [https://git.vgpu.io/open-iov.git/tree/docs/04-implementation/03-execution-frontier.md <code>../docs/04-implementation/03-execution-frontier.md</code>], the graphics ladder in [https://git.vgpu.io/open-iov.git/tree/docs/04-implementation/05-graphics-execution-plan.md <code>../docs/04-implementation/05-graphics-execution-plan.md</code>], the five-rung evaluation ladder in [https://git.vgpu.io/open-iov.git/tree/docs/05-operations/01-performance-correctness-security.md <code>../docs/05-operations/01-performance-correctness-security.md</code>], and the porting sequence in [https://git.vgpu.io/open-iov.git/tree/docs/06-portability/03-device-validation-and-porting-sequence.md <code>../docs/06-portability/03-device-validation-and-porting-sequence.md</code>]; the docs tree wins on disagreement.</blockquote> | <blockquote>'''Scope.''' The sequence of work: the phases, the gates that close them, what comes next, and how the plan itself is maintained. This is the ''roadmap'' view — [[Project Goals|<code>Project-Goals.md</code>]] says what the project is for, [[Project Status|<code>Project-Status.md</code>]] says where it stands today, and this page says in what order the remaining work happens and what must be true before each step. Canonical sources: the compute milestone ladder in [https://git.vgpu.io/open-iov.git/tree/docs/04-implementation/03-execution-frontier.md <code>../docs/04-implementation/03-execution-frontier.md</code>], the graphics ladder in [https://git.vgpu.io/open-iov.git/tree/docs/04-implementation/05-graphics-execution-plan.md <code>../docs/04-implementation/05-graphics-execution-plan.md</code>], the five-rung evaluation ladder in [https://git.vgpu.io/open-iov.git/tree/docs/05-operations/01-performance-correctness-security.md <code>../docs/05-operations/01-performance-correctness-security.md</code>], and the porting sequence in [https://git.vgpu.io/open-iov.git/tree/docs/06-portability/03-device-validation-and-porting-sequence.md <code>../docs/06-portability/03-device-validation-and-porting-sequence.md</code>]; the docs tree wins on disagreement.</blockquote> | ||
Status: 2026-11-15, tree <code>master @ | Status: 2026-11-15, tree <code>master @ a03a68ea</code>. Tags: <code>[done]</code>, <code>[active]</code>, <code>[ahead]</code> — the plan's own state vocabulary, distinct from the goal tags. | ||
== 1. How the plan works == | == 1. How the plan works == | ||
| Line 39: | Line 39: | ||
| OpenGL/Vulkan draw commands executed by the physical 3D pipeline and delivered as readable pixels | | OpenGL/Vulkan draw commands executed by the physical 3D pipeline and delivered as readable pixels | ||
| The graphics ladder: M-GL1 client context-init executes; M-GL2 <code>glxgears</code> non-black; M-GL3 GZDoom GL non-black through the mdev | | The graphics ladder: M-GL1 client context-init executes; M-GL2 <code>glxgears</code> non-black; M-GL3 GZDoom GL non-black through the mdev | ||
| <code>[active]</code> — between M-GL1 and M-GL2 with M-GL2's off-screen half proven: the display/KMS and DDX replay machinery work, X + stock GLX are green, the first non-black GPU-rendered frames and videos are captured, the X DDX/ScreenInit stability walls are closed, captured GL sections execute on the engine, the direct-GL submission is fully decoded (macro-driven, no classic draw header), the client's draw-state push reaches the engine, the MME pack completes, the <code>DRAW_IAB</code> macro executes, the DS stage image is authored and live for both vertex slots (<code>st0=st1=020a0481</code>); the remaining walls are the remaining DS stage type/context bits | | <code>[active]</code> — between M-GL1 and M-GL2 with M-GL2's off-screen half proven: the display/KMS and DDX replay machinery work, X + stock GLX are green, the first non-black GPU-rendered frames and videos are captured, the X DDX/ScreenInit stability walls are closed, captured GL sections execute on the engine, the direct-GL submission is fully decoded (macro-driven, no classic draw header), the client's draw-state push reaches the engine, the MME pack completes, the <code>DRAW_IAB</code> macro executes, the DS stage image is authored and live for both vertex slots (<code>st0=st1=020a0481</code>), and the saved-window release carrier deterministically replays the held window once the pack is resident; the remaining walls are the release call order (<code>a03a68ea</code>, landed but unexercised), the pack-completion lottery, the remaining DS stage type/context bits and the stores, the window/screen present, and the per-boot binding/X first-generation start lottery | ||
|- | |- | ||
| '''P3 — Sustained and multi-tenant''' | | '''P3 — Sustained and multi-tenant''' | ||
| Line 63: | Line 63: | ||
Ranked, in dependency order: | Ranked, in dependency order: | ||
# '''Graphics pixels (P2).''' The client and display stacks execute, X and the stock GLX path are fully green (<code>glxinfo -B</code> rc 0, ~520 FPS <code>glxgears</code>), the X DDX/ScreenInit stability walls are closed (X green >10 minutes), the DDX 3D replay runs, the first non-black GPU-rendered frames and videos are captured off-screen, captured GL sections execute on the engine, the direct-GL submission is fully decoded (macro-driven; no method-grammar draw header), and the client's draw-state push reaches the engine with the golden MME overlay. The MME pack then completes and <code>DRAW_IAB</code> (<code>mac=0x22</code>) executes with the SPH-BIND prelude intact and the DS stage VAs populated. The '''DS stage-0/1 image is now authored and live''' (a VTG SPH at <code>family+0x900</code>, first word <code>020a0481</code>; the window's own slot-1 bind is rewritten to it; DS <code>0x86040626 -> 0x84000420</code>, two boots). The named walls are the | # '''Graphics pixels (P2).''' The client and display stacks execute, X and the stock GLX path are fully green (<code>glxinfo -B</code> rc 0, ~520 FPS <code>glxgears</code>), the X DDX/ScreenInit stability walls are closed (X green >10 minutes), the DDX 3D replay runs, the first non-black GPU-rendered frames and videos are captured off-screen, captured GL sections execute on the engine, the direct-GL submission is fully decoded (macro-driven; no method-grammar draw header), and the client's draw-state push reaches the engine with the golden MME overlay. The MME pack then completes and <code>DRAW_IAB</code> (<code>mac=0x22</code>) executes with the SPH-BIND prelude intact and the DS stage VAs populated. The '''DS stage-0/1 image is now authored and live''' (a VTG SPH at <code>family+0x900</code>, first word <code>020a0481</code>; the window's own slot-1 bind is rewritten to it; DS <code>0x86040626 -> 0x84000420</code>, two boots). The release path is now host-deterministic when the pack completes: the saved-window release carrier replays the held window with the calls released, and the slot-34 census plus the SA[34] golden fill prove <code>client=golden=used=0x265</code>. The named walls are the release call order (the 728-B window places slot-34 after the <code>0x33/0x39</code> setup, so the DS latch pre-empts it; the reorder <code>a03a68ea</code> is landed but unexercised), the pack-completion lottery, the remaining DS stage type/context bits (SPH5/SPH10/SPH18) and the stores, the window/screen present path (glxgears' window is black and a window draw wedges X), the per-boot binding/X first-generation start lottery (even <code>modeNum</code> required; now the dominant throughput limiter), and then non-black window frames. Full detail: [[Graphics Execution|<code>Graphics-Execution.md</code>]] §6. | ||
# '''Compute hardening (P1).''' The staged-transfer class (failure modes proven, fixes in flight); the every-boot acceptance campaign; per-guest execution isolation. Detail: [[The Execution Frontier|<code>Execution-Frontier.md</code>]]. | # '''Compute hardening (P1).''' The staged-transfer class (failure modes proven, fixes in flight); the every-boot acceptance campaign; per-guest execution isolation. Detail: [[The Execution Frontier|<code>Execution-Frontier.md</code>]]. | ||
# '''The visible sequence after these''': first non-black frame → 60 fps in one VM with no forcing → two VMs on two mdevs → the CUDA battery 15/15 plus a soak → video → Windows. | # '''The visible sequence after these''': first non-black frame → 60 fps in one VM with no forcing → two VMs on two mdevs → the CUDA battery 15/15 plus a soak → video → Windows. | ||
Revision as of 21:34, 15 November 2026
An absence of critical technical documentation has historically slowed growth and adoption of developer ecosystems for GPU virtualization.
This CC-BY-4.0 licensed content can either be used with attribution, or used as inspiration for new documentation, created by GPU vendors for public commercial distribution as developer documentation.
Where possible, this documentation will clearly label dates and versions of observed-but-not-guaranteed behaviour vs. vendor-documented stable interfaces/behaviour with guarantees of forward or backward compatibility.
Project Plan
Scope. The sequence of work: the phases, the gates that close them, what comes next, and how the plan itself is maintained. This is the roadmap view —
Project-Goals.mdsays what the project is for,Project-Status.mdsays where it stands today, and this page says in what order the remaining work happens and what must be true before each step. Canonical sources: the compute milestone ladder in../docs/04-implementation/03-execution-frontier.md, the graphics ladder in../docs/04-implementation/05-graphics-execution-plan.md, the five-rung evaluation ladder in../docs/05-operations/01-performance-correctness-security.md, and the porting sequence in../docs/06-portability/03-device-validation-and-porting-sequence.md; the docs tree wins on disagreement.
Status: 2026-11-15, tree master @ a03a68ea. Tags: [done], [active], [ahead] — the plan's own state vocabulary, distinct from the goal tags.
1. How the plan works
Five rules shape every phase below, and they are the project's contract with itself:
- Every milestone has a gate and an acceptance signal, named before the work starts. A wall is closed only by its acceptance signal — not by an intention, a decompiler reading, or a lucky run.
- The evaluation ladder is the spine. A platform advances initialization → runtime start → execution → sustained → multi-tenant, and nothing claims a rung it has not reached and reproduced.
- Correctness before speed; no number without methodology. Performance claims carry their harness, versions and A/B baseline.
- Default-off until validated. New mechanisms land behind parameters (the forwarding and graphics seams today) and graduate only after their gate passes; graduation replaces the knob with documented configuration.
- No patches anywhere, and profiles over rewrites. Guest drivers, host drivers, firmware and hypervisors stay stock; a new driver, firmware or GPU enters the plan as a profile plus a measured delta.
2. The phases
| Phase | What it delivers | Exit gate | State (2026-11-15) |
|---|---|---|---|
| P0 — Platform | Emulated vGPU device, GSP boot and GSP-RM emulation, stock guest driver initialisation | Driver-API smoke green (ALL OK) = evaluation rung 2
|
[done]
|
| P1 — First execution (compute) | Guest CUDA kernels executing on the physical GPU, with engine-authored completions; then hardening | Verified clients + engine-authored completion = rung 3 core; hardening: staged-transfer class, every-boot acceptance, per-guest isolation | [active] — execution green; hardening in progress
|
| P2 — Graphics execution | OpenGL/Vulkan draw commands executed by the physical 3D pipeline and delivered as readable pixels | The graphics ladder: M-GL1 client context-init executes; M-GL2 glxgears non-black; M-GL3 GZDoom GL non-black through the mdev
|
[active] — between M-GL1 and M-GL2 with M-GL2's off-screen half proven: the display/KMS and DDX replay machinery work, X + stock GLX are green, the first non-black GPU-rendered frames and videos are captured, the X DDX/ScreenInit stability walls are closed, captured GL sections execute on the engine, the direct-GL submission is fully decoded (macro-driven, no classic draw header), the client's draw-state push reaches the engine, the MME pack completes, the DRAW_IAB macro executes, the DS stage image is authored and live for both vertex slots (st0=st1=020a0481), and the saved-window release carrier deterministically replays the held window once the pack is resident; the remaining walls are the release call order (a03a68ea, landed but unexercised), the pack-completion lottery, the remaining DS stage type/context bits and the stores, the window/screen present, and the per-boot binding/X first-generation start lottery
|
| P3 — Sustained and multi-tenant | Frame rates without assistance; multiple VMs sharing the GPU with measured fairness; soak-stable operation | Graphics M-GL4 (60 fps, no forcing) and M-GL5 (two VMs, two mdevs); CUDA battery + soak; per-guest execution isolation = rungs 4/5 | [ahead]
|
| P4 — Breadth | Video (NVENC/NVDEC), Windows/DirectX guests, live migration, non-KVM hypervisor transports | Per-case bring-up gates plus the matrix's evidence expectations | [ahead]
|
| P5 — Scale and portability | New GPU generations and driver families carried forward; published performance programme | A profile + measured delta per version, validated on hardware; A/B numbers published per the measurement contract | [ahead]
|
The phases overlap on purpose: the graphics workstream is what unblocks P3's first exit gate, and portability work starts from whichever hardware becomes available (P5 runs across the whole plan).
3. Where the plan stands, and what is next
Ranked, in dependency order:
- Graphics pixels (P2). The client and display stacks execute, X and the stock GLX path are fully green (
glxinfo -Brc 0, ~520 FPSglxgears), the X DDX/ScreenInit stability walls are closed (X green >10 minutes), the DDX 3D replay runs, the first non-black GPU-rendered frames and videos are captured off-screen, captured GL sections execute on the engine, the direct-GL submission is fully decoded (macro-driven; no method-grammar draw header), and the client's draw-state push reaches the engine with the golden MME overlay. The MME pack then completes andDRAW_IAB(mac=0x22) executes with the SPH-BIND prelude intact and the DS stage VAs populated. The DS stage-0/1 image is now authored and live (a VTG SPH atfamily+0x900, first word020a0481; the window's own slot-1 bind is rewritten to it; DS0x86040626 -> 0x84000420, two boots). The release path is now host-deterministic when the pack completes: the saved-window release carrier replays the held window with the calls released, and the slot-34 census plus the SA[34] golden fill proveclient=golden=used=0x265. The named walls are the release call order (the 728-B window places slot-34 after the0x33/0x39setup, so the DS latch pre-empts it; the reordera03a68eais landed but unexercised), the pack-completion lottery, the remaining DS stage type/context bits (SPH5/SPH10/SPH18) and the stores, the window/screen present path (glxgears' window is black and a window draw wedges X), the per-boot binding/X first-generation start lottery (evenmodeNumrequired; now the dominant throughput limiter), and then non-black window frames. Full detail:Graphics-Execution.md§6. - Compute hardening (P1). The staged-transfer class (failure modes proven, fixes in flight); the every-boot acceptance campaign; per-guest execution isolation. Detail:
Execution-Frontier.md. - The visible sequence after these: first non-black frame → 60 fps in one VM with no forcing → two VMs on two mdevs → the CUDA battery 15/15 plus a soak → video → Windows.
- Then P4/P5 row by row: each item ships with its own gate, profile and evidence, and only then moves in the matrix.
Recently closed, as evidence the gates work: the boot-poisoning defect and the post-reboot client-stall defect (compute reproducibility); the display/KMS bring-up (NvKms registers, X settles, GL 4.6); the UVM channel-pool tracker; the direct-GL ring/release and CE-ring discovery; the X DDX kick-channel decode and its three wait fixes (class-aware display arm, 0x8000 -> 0 notification completion, decoded GL release applied); the GSP event-IRQ fix that completes swaps; the X DMA-init fix (ebf3130f); the GR backend timeout fix (backend_timeout=0); the 2D path end-to-end; the DDX 3D replay and the first non-black GPU-rendered frames with captured videos (the ring-ledger scrub release, f6184ac3); the direct-GL ring/VAS and USERD hardening (verified page-directory discovery, eager push pins, client-allocated USERD resolution); the full green X/GLX path (glxinfo -B rc 0, ~520 FPS glxgears); the guest adapter-init regression (RMInstLoc lost to a kernel-cmdline override) and its fix; the emulated FB/GART sizing traps (FB info in KB, GART 256 MiB) that removed the 4 GiB guest-allocation class; and the guest Vulkan pipeline running end to end.
4. The gates
Each gate's full text lives in its canonical document; this is the map:
| Gate | What must be true | Where it is defined |
|---|---|---|
| Rung gate | The previous rung is green and reproducible for this platform before the next is claimed | Evaluation ladder |
| Execution gate | Engine-authored release plus verified guest results, reproduced across fresh boots | Execution frontier |
| Graphics gate | Milestone definitions: capture shows motion, no forcing, no diagnostic mirror, renderer is the NVIDIA driver | Graphics plan (§C) |
| Performance gate | A/B ratios from the published harness; no absolute numbers; variance and run counts reported | Measurement contract |
| Portability gate | Profile fields recorded, firmware/device pairing hashed, first-touch differences explained, supervised physical validation done | Porting sequence + matrix |
| Isolation gate | Fail-closed enforcement; fairness measured before any multi-tenant claim | Security document |
| Security gate | Adversarial review before multi-tenant or production claims | Security document |
5. Workstreams (always on)
| Workstream | What it does | Entry point |
|---|---|---|
| Correctness and acceptance | The regression battery, battery-first ordering, regression gates | Execution-Frontier.md
|
| Graphics execution | The execution lanes, capture/decode, the M-GL ladder | Graphics-Execution.md
|
| Performance measurement | Microbenchmarks first, then the A/B corpus, then structural optimisation | Performance.md
|
| Portability and versions | Profiles, measured deltas, the validation sequence; new driver/firmware families behind a review gate | Hardware-Software-Matrix.md
|
| Developer tooling | The firmware workbench: recorded sessions as evidence, offline-first investigation of walls | Riscv-GSP-RM-Debugger.md
|
| Security and isolation | Threat model, audits, fail-closed posture | ../docs/05-operations/01-performance-correctness-security.md
|
| Documentation and evidence | Docs tree canonical; dated status; replayable evidence for every claim | ../docs/README.md
|
6. Contributing to the plan
- The unit of contribution is a profile plus evidence, evaluated through the five-rung ladder — see "Adding a new combination" in
Hardware-Software-Matrix.mdand the porting sequence document. - Nasty bugs (non-reproducible, cross-subsystem, blocking a gate) get a tracked issue in the repository; ordinary work stays in the live handoffs.
- Support claims are made only by recording hardware + driver + firmware + rung + date in the matrix with the evidence bundle behind them.
7. How this plan is maintained
The plan is a living sequence, not a dated roadmap: each milestone's gate is owned by its canonical document, the current state is tracked on Project-Status.md, and the plan changes only when a gate is named and its evidence rules are written down. When a wall closes, the canonical doc is updated first and the site pages follow on the next refresh.
8. Related pages
Project-Goals.md— the goals and their status.Project-Status.md— the dated milestone ladder.Execution-Frontier.md— the compute frontier and its gates.Graphics-Execution.md— the graphics frontier and the M-GL ladder.Performance.md— the measurement programme.Hardware-Software-Matrix.md— the portability plan and support ladder.../docs/README.md— the documentation front door and the project's own status table.