Project Plan

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.md says what the project is for, Project-Status.md 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 ../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-10-30, tree master @ b4930168. 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:

1. 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.
2. 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.
3. Correctness before speed; no number without methodology. Performance claims carry their harness, versions and A/B baseline.
4. 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.
5. 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-10-30)
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; 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	[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:

1. 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.md §6.
2. 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.
3. 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.
4. 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:

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.md 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.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.