Difference between revisions of "OpenGL"

From Open-IOV
Jump to navigation Jump to search
m (2026-11-09 evening refresh 2: forced GLX selects libnvidia-glcore; windowed glxgears hangs in the glcore kick wait; kernel-visible present completion is the wall)
m (2026-11-10 status refresh: guest GL draws forward and execute on the physical GPU; the 0-pixel wall is the constant-buffer (MVP) content)
Line 5: Line 5:
<blockquote>'''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|<code>Graphics-Execution.md</code>]]; CUDA compute is on [[The Execution Frontier|<code>Execution-Frontier.md</code>]]. Canonical sources: [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 plan and milestones), [https://git.vgpu.io/open-iov.git/tree/docs/04-implementation/04-real-render-walls.md <code>../docs/04-implementation/04-real-render-walls.md</code>] (the measured walls) and [https://git.vgpu.io/open-iov.git/tree/docs/03-architecture/02-guest-stack-and-cudasw.md <code>../docs/03-architecture/02-guest-stack-and-cudasw.md</code>] (the guest stack). The docs tree wins on disagreement.</blockquote>
<blockquote>'''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|<code>Graphics-Execution.md</code>]]; CUDA compute is on [[The Execution Frontier|<code>Execution-Frontier.md</code>]]. Canonical sources: [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 plan and milestones), [https://git.vgpu.io/open-iov.git/tree/docs/04-implementation/04-real-render-walls.md <code>../docs/04-implementation/04-real-render-walls.md</code>] (the measured walls) and [https://git.vgpu.io/open-iov.git/tree/docs/03-architecture/02-guest-stack-and-cudasw.md <code>../docs/03-architecture/02-guest-stack-and-cudasw.md</code>] (the guest stack). The docs tree wins on disagreement.</blockquote>


Status: 2026-11-09, tree <code>master @ 21e0d611</code>. Tags: <code>[live]</code> observed with the stock guest driver; <code>[wip]</code> partial; <code>[wall]</code> current blocker; <code>[target]</code> defined success state.
Status: 2026-11-09, tree <code>master @ cb8e822b</code>. Tags: <code>[live]</code> observed with the stock guest driver; <code>[wip]</code> partial; <code>[wall]</code> current blocker; <code>[target]</code> defined success state.


== 1. The guest OpenGL stack ==
== 1. The guest OpenGL stack ==
Line 54: Line 54:
| <code>[live]</code>
| <code>[live]</code>
|-
|-
| GZDoom obtains a real GL context; windowed GZDoom reaches renderer startup
| X server green with <code>sema_vas_cand_ms=1</code>; <code>glxinfo -B</code> NVIDIA 4.6.0 direct
| <code>[live]</code> (menu/frames black)
| <code>[live]</code>
|-
|-
| GZDoom reaches <code>MAP01</code> on Mesa llvmpipe (not the emulated vGPU path)
| GSP event-IRQ fix wakes the guest poll; glxgears completes swaps
| <code>[wip]</code>
| <code>[live]</code>
|-
|-
| Forced GLX (<code>SDL_VIDEO_X11_FORCE_EGL=0</code>) selects <code>libnvidia-glcore</code>
| 2D path end-to-end: accelerated X fills read back via <code>xwd</code>
| <code>[live]</code>
| <code>[live]</code>
|-
|-
| Windowed GL present/kick completion (minimal <code>glxgears</code>)
| Guest's real GL draws forward and execute on the physical GPU (<code>work_gr backend_ok=9</code>)
| <code>[wall]</code>
|-
| X server survives the GZDoom run on a 12 GB guest (the DDX's 4 GB sysmem allocation forces the size)
| <code>[live]</code>
| <code>[live]</code>
|-
|-
| X server's <code>0xC597</code> graphics section captured and decoded
| Beef GR channel <code>0xbeef0100</code> captures real GL draw sections
| <code>[live]</code>
| <code>[live]</code>
|-
|-
Line 78: Line 75:
| <code>[live]</code>
| <code>[live]</code>
|-
|-
| Direct GL client: device-init gate handled; client channels allocate; readback path returns with no GL error
| Direct GL client submits and retires its per-frame draws (GR <code>0xbeef0100</code>, CE <code>0xbeef0101</code>/<code>0xbeef0102</code>); DDX kick channel decoded
| <code>[live]</code>
| <code>[live]</code>
|-
|-
| Direct GL client submits and retires its per-frame draws (GR <code>0xbeef0100</code>, CE <code>0xbeef0101</code>/<code>0xbeef0102</code>); DDX kick channel decoded
| X server survives the run on a 12 GB guest (the DDX's 4 GB sysmem allocation forces the size)
| <code>[live]</code>
| <code>[live]</code>
|-
|-
| Guest kernel observes the kick completion and signals the modeset event
| Constant-buffer (MVP) page resolves and the draw writes render-target pixels
| <code>[wall]</code>
| <code>[wall]</code>
|-
|-
| NVIDIA Vulkan ICD creates a device
| MME front-end defer / GR stale-wedge stability
| <code>[wall]</code>
| <code>[wall]</code>
|-
|-
Line 93: Line 90:
| <code>[wall]</code>
| <code>[wall]</code>
|-
|-
| Physical dispatch of the direct-GL draws (<code>forwarded=0</code>)
| NVIDIA Vulkan ICD creates a device
| <code>[wall]</code>
| <code>[wall]</code>
|-
|-
Line 109: Line 106:
== 5. Milestones on this path ==
== 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 (<code>glxgears</code> 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 and execution work is done — the display/KMS stack registers, X settles, the client submits and retires its GR/CE channels, and the engine authors stores — and the remaining gates are the kernel-visible GL present/kick completion, the X DDX get-word/notifier completion, and physical dispatch of the client's draws before the first rendered frame.
The graphics plan defines M-GL1 (client context-init decodes and executes; the client leaves its retry loop), M-GL2 (<code>glxgears</code> 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 and execution work is done — the display/KMS stack registers, X settles, the client submits and retires its GR/CE channels, and the guest's GL draws forward and execute on the physical GPU. The remaining gates are the constant-buffer (MVP) page, the MME front-end/stale-wedge stability, and the X DDX get-word/notifier completion before the first rendered frame.


== 6. What is not claimed ==
== 6. What is not claimed ==


* No OpenGL frame from the emulated vGPU has produced real rendered pixels yet; every capture so far is black. GZDoom reaching <code>MAP01</code> on Mesa llvmpipe is not a rendered frame from the emulated vGPU, and the forced-GLX run selects <code>libnvidia-glcore</code> but hangs in the present/kick wait (<code>glxgears</code> reproduces it).
* No OpenGL frame from the emulated vGPU has produced real rendered pixels yet; every capture so far is black. glxgears completes swaps and its GL draws execute on the physical GPU, but the constant-buffer (MVP) page does not resolve, so the engine writes 0 pages.
* No frame-rate or latency numbers.
* No frame-rate or latency numbers.
* The published two-VM GZDoom demo videos used the labelled <code>virtio-gpu</code>/ <code>virgl</code> path, not the emulated vGPU.
* The published two-VM GZDoom demo videos used the labelled <code>virtio-gpu</code>/ <code>virgl</code> path, not the emulated vGPU.

Revision as of 10:23, 10 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.

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; CUDA compute is on Execution-Frontier.md. Canonical sources: ../docs/04-implementation/05-graphics-execution-plan.md (the plan and milestones), ../docs/04-implementation/04-real-render-walls.md (the measured walls) and ../docs/03-architecture/02-guest-stack-and-cudasw.md (the guest stack). The docs tree wins on disagreement.

Status: 2026-11-09, tree master @ cb8e822b. 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:

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 sources today are the direct GL client's own channels — the GR channel 0xbeef0100 and its CE siblings 0xbeef0101/0xbeef0102 — and the X server's channels, whose graphics-class (0xC597, TURING_A) sections the emulation captures and whose DDX kick channel (0xbfef0002) is decoded from its ring head (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. The GL draw path decodes these uploads and the engine executes the draw; Vulkan's inline-to-memory arm is the remaining mirror-image gap (Vulkan.md).
  • 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]
nvidia-modeset/NvKms registers (/dev/dri/card0, renderD128, fb0); nvidia-smi -L enumerates [live] (campaign configuration)
glxinfo -B reports the NVIDIA renderer (OpenGL 4.6.0, driver 570.144, direct rendering) [live]
The X driver's RC-watchdog channel registers and its notifier is authored [live]
X server green with sema_vas_cand_ms=1; glxinfo -B NVIDIA 4.6.0 direct [live]
GSP event-IRQ fix wakes the guest poll; glxgears completes swaps [live]
2D path end-to-end: accelerated X fills read back via xwd [live]
Guest's real GL draws forward and execute on the physical GPU (work_gr backend_ok=9) [live]
Beef GR channel 0xbeef0100 captures real GL draw sections [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 submits and retires its per-frame draws (GR 0xbeef0100, CE 0xbeef0101/0xbeef0102); DDX kick channel decoded [live]
X server survives the run on a 12 GB guest (the DDX's 4 GB sysmem allocation forces the size) [live]
Constant-buffer (MVP) page resolves and the draw writes render-target pixels [wall]
MME front-end defer / GR stale-wedge stability [wall]
DDX push-buffer get-word publish and notifier recycle [wall]
NVIDIA Vulkan ICD creates a device [wall]
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 and execution work is done — the display/KMS stack registers, X settles, the client submits and retires its GR/CE channels, and the guest's GL draws forward and execute on the physical GPU. The remaining gates are the constant-buffer (MVP) page, the MME front-end/stale-wedge stability, and the X DDX get-word/notifier completion before the first rendered frame.

6. What is not claimed

  • No OpenGL frame from the emulated vGPU has produced real rendered pixels yet; every capture so far is black. glxgears completes swaps and its GL draws execute on the physical GPU, but the constant-buffer (MVP) page does not resolve, so the engine writes 0 pages.
  • 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