site: 2026-10-30 wiki refresh - new Project Goals, Performance and Interfaces and Stability pages; GSP explainer expanded (bare-metal behaviour + the two emulation modes); graphics pages (Graphics Execution, OpenGL, Vulkan, DirectX) with two new diagrams; status refresh across 15 pages; canonical docs updated (README status table, purpose-and-scope, performance contract); published to open-iov.org (67 pages, 0 problems)

1 files changed, 122 insertions, 0 deletions

diff --git a/wiki/OpenGL.md b/wiki/OpenGL.md
new file mode 100644
index 0000000..8264620
--- /dev/null
+++ b/wiki/OpenGL.md
@@ -0,0 +1,122 @@
+# OpenGL
+
+> **Scope.** How a stock guest OpenGL application's commands travel through the
+> unmodified NVIDIA stack on the emulated vGPU, and the honest state of running
+> OpenGL on it. The host-side execution machinery shared by all graphics APIs
+> is on [`Graphics-Execution.md`](Graphics-Execution.md); CUDA compute is on
+> [`Execution-Frontier.md`](Execution-Frontier.md). Canonical sources:
+> [`../docs/04-implementation/05-graphics-execution-plan.md`](../docs/04-implementation/05-graphics-execution-plan.md)
+> (the plan and milestones),
+> [`../docs/04-implementation/04-real-render-walls.md`](../docs/04-implementation/04-real-render-walls.md)
+> (the measured walls) and
+> [`../docs/03-architecture/02-guest-stack-and-cudasw.md`](../docs/03-architecture/02-guest-stack-and-cudasw.md)
+> (the guest stack). The docs tree wins on disagreement.
+
+Status: 2026-10-30, tree `master @ b4930168`. Tags: `[live]` observed with the
+stock guest driver; `[wip]` partial; `[wall]` current blocker; `[target]`
+defined success state.
+
+## 1. The guest OpenGL stack
+
+On Linux, an OpenGL application does not talk to the kernel driver directly:
+it talks to the GL implementation, and — when a display is involved — through
+the X server's GLX extension:
+
+```text
+application (toolkit / SDL / GLFW / raw GLX)
+  -> libGL (dispatch)                    -> libGLX_nvidia (NVIDIA GLX client)
+  -> libnvidia-glcore (the vendor GL engine: state, programs, shaders, draws)
+  -> ioctls + mappings to nvidia.ko      -> channels, buffers, synchronization
+X server (Xorg)
+  -> GLX extension module (glxserver_nvidia) and the NVIDIA DDX (X driver)
+  -> owns the screen, drawables and the present path
+```
+
+Two forms of operation exist, and both are visible in the guest:
+
+* **Direct rendering** — the normal desktop case. The GL client builds GPU
+  commands in its own process and the X server coordinates buffers and
+  presents. The client's channel is the source of truth for per-draw state.
+* **Indirect GLX** — the client's GL protocol is serialised to the X server,
+  which executes it against its own GL context. Here the X server's channel
+  carries the graphics stream.
+
+On the emulated vGPU the readable command source today is the **X server's
+channel**, whose graphics-class (`0xC597`, `TURING_A`) sections the emulation
+captures and executes ([`Graphics-Execution.md`](Graphics-Execution.md) §3).
+
+## 2. What an NVIDIA GL frame involves (observed shapes)
+
+* **Context and state setup** — shader programs (SASS) uploaded to device
+  memory, constant/descriptor banks, render targets and depth surfaces
+  allocated and mapped.
+* **Per-draw work** — a graphics-class method stream: state binds (viewport,
+  render target, ZS, blend/ROP), program and constant binds, vertex/index
+  data, and draw-issuing methods that drive the fixed-function pipeline
+  (vertex fetch, primitive assembly, rasterisation, fragment work, ROP).
+* **Program/descriptor delivery** — the driver uploads shader code and
+  descriptors through its copy/utility-channel inline-data path; this upload
+  is the piece the emulation must materialise for the engine to run *real*
+  programs ([`Vulkan.md`](Vulkan.md) has the mirror-image of the same gap).
+* **Present** — the X server's present/readback path runs as light 2D-class
+  and copy-engine operations; the emulator decodes and executes those shapes.
+
+## 3. Status on the emulated vGPU
+
+Rated honestly, against the milestone ladder in the plan:
+
+| Item | State |
+|---|---|
+| X server initialises on the emulated vGPU (driver push-DMA sanity test, ScreenInit) | `[live]` |
+| `glxinfo -B` reports the NVIDIA renderer (OpenGL 4.6.0, driver 570.144) | `[live]` |
+| The X driver's RC-watchdog channel registers and its notifier is authored | `[live]` |
+| GZDoom launches and runs on the emulated vGPU | `[live]` (menu/frames black) |
+| X server's `0xC597` graphics section captured and decoded | `[live]` |
+| Engine executes a launch built from the captured section (real `sm_75` SASS retired) | `[live]` |
+| Verbatim 3D method-stream replay retired by the engine, no MMU fault | `[live]` |
+| Direct GL client: device-init gate handled; client channels allocate; readback path returns with no GL error | `[wip]` |
+| Direct GL client submits its per-frame draws | `[wall]` (no submissions observed) |
+| Non-black rendered frames through the emulated vGPU | `[wall]` |
+| 60 fps sustained, no forcing (M-GL4) | `[target]` |
+
+## 4. How OpenGL runs are verified
+
+Instruments that matter, in order of usefulness: the X server log and
+`xdpyinfo` (did the server initialise?), `glxinfo -B` (which renderer is
+real), the application's own progress output, and frame capture at the GL
+source (a swap-hook capture is the ground truth for pixels — the X screen
+itself is not, on some stacks). Captures are decoded offline and scored:
+fraction of pixels above a luminance threshold, colour count, and
+frame-to-frame motion. A run counts only when the capture shows motion with
+the NVIDIA renderer in use.
+
+## 5. Milestones on this path
+
+The graphics plan defines M-GL1 (client context-init decodes and executes; the
+client leaves its retry loop), M-GL2 (`glxgears` non-black), M-GL3 (GZDoom GL
+non-black through the mdev), M-GL4 (60 fps, no forcing), M-GL5 (two VMs, two
+mdevs), M-GL6 (split-screen video). The project sits **between M-GL1 and
+M-GL2**: the interface work is done — the client creates its channels and its
+readback path is clean — and pixels are the gate.
+
+## 6. What is not claimed
+
+* No OpenGL frame from the emulated vGPU has produced real rendered pixels
+  yet; every capture so far is black.
+* No frame-rate or latency numbers.
+* The published two-VM GZDoom demo videos used the labelled `virtio-gpu`/
+  `virgl` path, not the emulated vGPU.
+
+## 7. Related pages
+
+* [`Graphics-Execution.md`](Graphics-Execution.md) — the shared execution
+  machinery and the ranked walls.
+* [`Vulkan.md`](Vulkan.md) — the sibling API path, further along in the
+  pipeline lifecycle.
+* [`DirectX.md`](DirectX.md) — the Windows/DirectX target.
+* [`CUDA-Userspace-Driver.md`](CUDA-Userspace-Driver.md) — how the NVIDIA
+  userspace stack is analysed.
+* [`Install-and-First-Run.md`](Install-and-First-Run.md) — bringing the stack
+  up.
+* [`../docs/04-implementation/05-graphics-execution-plan.md`](../docs/04-implementation/05-graphics-execution-plan.md) —
+  the canonical plan, gap list and gates.