WikiBot: 2026-10-30 wiki refresh: add Project Plan page (phases, gates, workstreams, next steps)

2026-10-30T17:12:02Z

2026-10-30 wiki refresh: add Project Plan page (phases, gates, workstreams, next steps)

New page

{{About message}}

= Project Plan =

<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-10-30, tree <code>master @ b4930168</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 ==

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 ==

{| class="wikitable"
|-
! Phase
! What it delivers
! Exit gate
! State (2026-10-30)
|-
| '''P0 — Platform'''
| Emulated vGPU device, GSP boot and GSP-RM emulation, stock guest driver initialisation
| Driver-API smoke green (<code>ALL OK</code>) = evaluation rung 2
| <code>[done]</code>
|-
| '''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
| <code>[active]</code> — 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 <code>glxgears</code> non-black; M-GL3 GZDoom GL non-black through the mdev
| <code>[active]</code> — between M-GL1 and M-GL2; the pixel walls are named
|-
| '''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
| <code>[ahead]</code>
|-
| '''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
| <code>[ahead]</code>
|-
| '''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
| <code>[ahead]</code>
|}

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).''' Three walls, each with a named next fix: the GL client's submissions; program (SASS) delivery plus program-VA mapping; then non-black 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>]].
# '''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 X/GL wall (the X server and GLX run on the emulated vGPU); the engine executing the real GL method stream; 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:

{| class="wikitable"
|-
! 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) ==

{| class="wikitable"
|-
! Workstream
! What it does
! Entry point
|-
| Correctness and acceptance
| The regression battery, battery-first ordering, regression gates
| [[The Execution Frontier|<code>Execution-Frontier.md</code>]]
|-
| Graphics execution
| The execution lanes, capture/decode, the M-GL ladder
| [[Graphics Execution|<code>Graphics-Execution.md</code>]]
|-
| Performance measurement
| Microbenchmarks first, then the A/B corpus, then structural optimisation
| [[Performance|<code>Performance.md</code>]]
|-
| Portability and versions
| Profiles, measured deltas, the validation sequence; new driver/firmware families behind a review gate
| [[Hardware and Software Matrix|<code>Hardware-Software-Matrix.md</code>]]
|-
| Developer tooling
| The firmware workbench: recorded sessions as evidence, offline-first investigation of walls
| [[risc-v-gsp-rm-debugger|<code>Riscv-GSP-RM-Debugger.md</code>]]
|-
| Security and isolation
| Threat model, audits, fail-closed posture
| [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>]
|-
| Documentation and evidence
| Docs tree canonical; dated status; replayable evidence for every claim
| [https://git.vgpu.io/open-iov.git/tree/docs/README.md <code>../docs/README.md</code>]
|}

== 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 and Software Matrix|<code>Hardware-Software-Matrix.md</code>]] and 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|<code>Project-Status.md</code>]], 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|<code>Project-Goals.md</code>]] — the goals and their status.
* [[Project Status|<code>Project-Status.md</code>]] — the dated milestone ladder.
* [[The Execution Frontier|<code>Execution-Frontier.md</code>]] — the compute frontier and its gates.
* [[Graphics Execution|<code>Graphics-Execution.md</code>]] — the graphics frontier and the M-GL ladder.
* [[Performance|<code>Performance.md</code>]] — the measurement programme.
* [[Hardware and Software Matrix|<code>Hardware-Software-Matrix.md</code>]] — the portability plan and support ladder.
* [https://git.vgpu.io/open-iov.git/tree/docs/README.md <code>../docs/README.md</code>] — the documentation front door and the project's own status table.

Project Plan - Revision history

WikiBot: 2026-10-30 wiki refresh: add Project Plan page (phases, gates, workstreams, next steps)