diff options
| -rw-r--r-- | tools/site/pages/Documentation.wiki | 1 | ||||
| -rw-r--r-- | tools/site/pages/Main-Page.wiki | 1 | ||||
| -rw-r--r-- | tools/site/pages/MediaWiki-Sidebar.wiki | 1 | ||||
| -rw-r--r-- | tools/site/titles.json | 1 | ||||
| -rw-r--r-- | wiki/.publish-manifest.json | 39 | ||||
| -rw-r--r-- | wiki/Project-Plan.md | 136 |
6 files changed, 164 insertions, 15 deletions
diff --git a/tools/site/pages/Documentation.wiki b/tools/site/pages/Documentation.wiki index f403842..9d3a9dc 100644 --- a/tools/site/pages/Documentation.wiki +++ b/tools/site/pages/Documentation.wiki @@ -4,6 +4,7 @@ This is the index of the Open-IOV wiki. If you are new, read '''[[Project Status == Start here == * [[Project Goals]] — what Open-IOV is for, and the status of each goal +* [[Project Plan]] — the phases, gates, workstreams and what is next * [[Project Status]] — what works today, what is in progress, what is not started * [[Install and First Run]] — build, load, and a stock guest driver in about half an hour * [[System Overview]] — the architecture in one page diff --git a/tools/site/pages/Main-Page.wiki b/tools/site/pages/Main-Page.wiki index 37a1eea..572b365 100644 --- a/tools/site/pages/Main-Page.wiki +++ b/tools/site/pages/Main-Page.wiki @@ -13,6 +13,7 @@ The only new component is one host kernel module (<code>vgsp.ko</code>), which i == Start here == * '''[[Project Goals]]''' — what Open-IOV is for, and the status of each goal. +* '''[[Project Plan]]''' — how the work is sequenced, gated, and what is next. * '''[[Project Status]]''' — the honest, dated state of the project. * '''[[Install and First Run]]''' — fresh host to a stock guest driver in about half an hour. * '''[[System Overview]]''' — how Open-IOV works, in one page. diff --git a/tools/site/pages/MediaWiki-Sidebar.wiki b/tools/site/pages/MediaWiki-Sidebar.wiki index 1653dbc..0085b42 100644 --- a/tools/site/pages/MediaWiki-Sidebar.wiki +++ b/tools/site/pages/MediaWiki-Sidebar.wiki @@ -1,6 +1,7 @@ * navigation ** mainpage|mainpage-description ** Project Goals +** Project Plan ** Project Status ** Documentation ** FAQ diff --git a/tools/site/titles.json b/tools/site/titles.json index b67955c..ed2c588 100644 --- a/tools/site/titles.json +++ b/tools/site/titles.json @@ -17,6 +17,7 @@ "WPR-Management.md": "WPR Management", "Project-Status.md": "Project Status", "Project-Goals.md": "Project Goals", + "Project-Plan.md": "Project Plan", "Performance.md": "Performance", "Interfaces-and-Stability.md": "Interfaces and Stability", "Install-and-First-Run.md": "Install and First Run", diff --git a/wiki/.publish-manifest.json b/wiki/.publish-manifest.json index 5a5c5d9..98ed37a 100644 --- a/wiki/.publish-manifest.json +++ b/wiki/.publish-manifest.json @@ -46,11 +46,11 @@ }, "Documentation": { "file": "Documentation.wiki", - "new_revid": 24026, - "old_revid": 23974, - "source_sha": "62069a87325561c8", - "summary": "2026-10-30 wiki refresh: goals, GSP, graphics, performance, interfaces", - "timestamp": "2026-10-30T17:06:43Z", + "new_revid": 24031, + "old_revid": 24026, + "source_sha": "04de62980311a5e4", + "summary": "2026-10-30 wiki refresh: add Project Plan page (phases, gates, workstreams, next steps)", + "timestamp": "2026-10-30T17:12:05Z", "title": "Documentation" }, "Error Codes": { @@ -190,20 +190,20 @@ }, "Main Page": { "file": "Main-Page.wiki", - "new_revid": 24025, - "old_revid": 24000, - "source_sha": "2418a3483e61245d", - "summary": "2026-10-30 wiki refresh: goals, GSP, graphics, performance, interfaces", - "timestamp": "2026-10-30T17:06:41Z", + "new_revid": 24030, + "old_revid": 24025, + "source_sha": "73ae8e2c1f093423", + "summary": "2026-10-30 wiki refresh: add Project Plan page (phases, gates, workstreams, next steps)", + "timestamp": "2026-10-30T17:12:04Z", "title": "Main Page" }, "MediaWiki:Sidebar": { "file": "MediaWiki-Sidebar.wiki", - "new_revid": 24027, - "old_revid": 23976, - "source_sha": "677c7b51253fd6a5", - "summary": "2026-10-30 wiki refresh: goals, GSP, graphics, performance, interfaces", - "timestamp": "2026-10-30T17:06:44Z", + "new_revid": 24032, + "old_revid": 24027, + "source_sha": "290bc8a24b8ab97c", + "summary": "2026-10-30 wiki refresh: add Project Plan to sidebar", + "timestamp": "2026-10-30T17:12:10Z", "title": "MediaWiki:Sidebar" }, "Migration Protocol": { @@ -260,6 +260,15 @@ "timestamp": "2026-10-30T17:04:55Z", "title": "Project Goals" }, + "Project Plan": { + "file": "Project-Plan.wiki", + "new_revid": 24029, + "old_revid": null, + "source_sha": "0440c98d1b4927fa", + "summary": "2026-10-30 wiki refresh: add Project Plan page (phases, gates, workstreams, next steps)", + "timestamp": "2026-10-30T17:12:02Z", + "title": "Project Plan" + }, "Project Status": { "file": "Project-Status.wiki", "new_revid": 24011, diff --git a/wiki/Project-Plan.md b/wiki/Project-Plan.md new file mode 100644 index 0000000..697e95f --- /dev/null +++ b/wiki/Project-Plan.md @@ -0,0 +1,136 @@ +# 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`](Project-Goals.md) says what the project is for, +> [`Project-Status.md`](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`](../docs/04-implementation/03-execution-frontier.md), +> the graphics ladder in +> [`../docs/04-implementation/05-graphics-execution-plan.md`](../docs/04-implementation/05-graphics-execution-plan.md), +> the five-rung evaluation ladder in +> [`../docs/05-operations/01-performance-correctness-security.md`](../docs/05-operations/01-performance-correctness-security.md), +> and the porting sequence in +> [`../docs/06-portability/03-device-validation-and-porting-sequence.md`](../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`](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`](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`](Execution-Frontier.md) | +| Graphics execution | The execution lanes, capture/decode, the M-GL ladder | [`Graphics-Execution.md`](Graphics-Execution.md) | +| Performance measurement | Microbenchmarks first, then the A/B corpus, then structural optimisation | [`Performance.md`](Performance.md) | +| Portability and versions | Profiles, measured deltas, the validation sequence; new driver/firmware families behind a review gate | [`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md) | +| Developer tooling | The firmware workbench: recorded sessions as evidence, offline-first investigation of walls | [`Riscv-GSP-RM-Debugger.md`](Riscv-GSP-RM-Debugger.md) | +| Security and isolation | Threat model, audits, fail-closed posture | [`../docs/05-operations/01-performance-correctness-security.md`](../docs/05-operations/01-performance-correctness-security.md) | +| Documentation and evidence | Docs tree canonical; dated status; replayable evidence for every claim | [`../docs/README.md`](../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`](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`](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`](Project-Goals.md) — the goals and their status. +* [`Project-Status.md`](Project-Status.md) — the dated milestone ladder. +* [`Execution-Frontier.md`](Execution-Frontier.md) — the compute frontier and + its gates. +* [`Graphics-Execution.md`](Graphics-Execution.md) — the graphics frontier and + the M-GL ladder. +* [`Performance.md`](Performance.md) — the measurement programme. +* [`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md) — the + portability plan and support ladder. +* [`../docs/README.md`](../docs/README.md) — the documentation front door and + the project's own status table. |