Virtual Display
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.
Virtual Display
Scope. How a guest's rendered frames are presented when there is no physical monitor attached to the GPU the guest is using — the guest virtual-display program that reads the real GL back buffer and streams it out, and the host vGPU display-control lane (
NVA080/NVA083) that accepts a guest-supplied scanout surface. This page also records why a separate virtual-display path exists on a single emulated pDevice, and the gates that currently stand between a running GL client and captured frames. The shared 3D machinery is onGraphics-Execution.md; the guest OpenGL stack is onOpenGL.md. Canonical sources:../docs/04-implementation/05-graphics-execution-plan.md(the plan and the separate-scanout decision) and the trackedtools/guest-diag/vdisp/guest program and its measured recipe.
Status: 2026-11-22, tree vgpu/campaign/r76 @ 1c4c9bd2. Tags: [live] observed end to end; [wip] partially built; [wall] current blocker; [target] defined success state.
1. Why a virtual display
The acceptance target is a stock guest application rendering through the emulated vGPU, with the image observable without trusting the guest to screenshot itself. On a normal desktop the last step is a physical scanout: the X driver sets a mode on a connected display head and the GPU scans the surface out. A virtualized GPU usually has no such head, and the project's requirement is stronger: the presentation path must not depend on attaching the emulated device to a host monitor, and it must not patch the guest driver.
On a single vGPU pDevice the physical-display route also carries a specific structural cost. A native X11 GL client needs two things at once:
- Buffer locations from the GLS adapter set, which require a bound GPU-screen/
GPUDeviceassociation and a real-mode primary surface. - An even
screens[0].modeNum, the shared nvClip progress word the client's__glNVStateInittests. With an odd value the client clears its init bits,BufferObjectExpandLocationsreturns nothing, and every buffer-object allocation fails (GL_OUT_OF_MEMORY 0x505, aNULLmap).
Binding the GPU screen closes/regenerates the master during ScreenInit, and the screen-close path performs a raw modeNum++ — about 0.5-0.9 s after X starts, before any client can connect. Removing the association keeps the word even but leaves the GLS adapter set with no render device. With one pDevice the two requirements are mutually exclusive on the physical-display path. The DDX also refuses a GPU screen on a pDevice that already has a protocol screen, and VT switches only increment the counter further. Recorded in the graphics plan as the two-path deadlock (2026-11-22).
The virtual-display route avoids the physical screen binding altogether: the guest hands the surface (or the rendered pixels) to a presentation path that does not own a display head. The project supports two independent halves of that route, described below.
2. The guest virtual-display program [live]
The supported presentation mechanism today is a guest userspace program that makes the real GL rendering observable without a second pDev and without a host display round-trip. It lives in the tracked tools/guest-diag/vdisp/ package:
| Piece | Role |
|---|---|
sdl_cap.c -> sdl_cap.so
|
LD_PRELOAD interposer on glXSwapBuffers. Before the real swap it calls glFinish() and glReadPixels(GL_BACK), then streams raw RGBA frames to a FIFO. It is a sink, not a renderer: the pixels come from the guest NVIDIA GL driver's real back buffer for the X11 GLX drawable.
|
win-run.sh
|
Guest driver: wait for a settled boot, start the accelerated NoScanout X, apply the mode-parity gate, probe the GL object path, run the application with the capture shim, encode with ffmpeg.
|
win-host.sh
|
Host driver: flock-serialised cycle — module, one mdev, QEMU, guest asset push, guest gate, pull the mp4 and logs back through the QEMU user-net upload sink.
|
mode-even-gate.sh
|
Deterministic mode-parity gate: start X on its own VT, sample the shared word, restart X once if it is odd, re-verify, then run the client with DISPLAY exported.
|
globjprobe.c
|
GLX gate: renderer check, non-NULL glBufferData(data), glMapBufferRange, FBO completeness, non-black readback.
|
glburn.c
|
Keep-alive GLX client so the GLX screen device survives across clients. |
xorg.conf.guest-noscanout
|
The proven accelerated headless X configuration (UseDisplayDevice None, AllowEmptyInitialConfiguration, UseSysmemPixmapAccel False, Virtual 1920x1080).
|
guest_upload.py / upload_sink.py
|
Guest-to-host transfer (the guest reaches the host at 10.0.2.2).
|
Properties of this route:
- One mdev, one guest, stock driver. No second pDevice, no guest-driver patch, no second VM.
- Native rendering. The application keeps its OpenGL renderer; the shim only reads the finished back buffer; the application itself renders it.
- Source-level capture. The sink observes the drawable the GL client actually rendered, not a host-side screen scrape; a capture is therefore evidence of the guest GL path, and the frame is checked for motion and colour offline.
3. The mode-parity gate [live]
The shared nvClip screens[0].modeNum is the client's __GL_DEV_MODESWITCH_TEST_COMPLETE word. On this stack its first generation has two writer classes in the X server process: the screen-close path does a raw modeNum++, and the GLS server-device disable adds two and then sets the low bit. A 5 ms sampler on a clean boot shows the lifecycle:
| t (s) | event |
|---|---|
| 242.850 | first X ScreenInit: GLS server-device enable -> 2
|
| 243.539 | first X: +1 -> 3 (0.69 s after the enable, before GLX init)
|
| 254.749 | first X killed: screen-close raw increment -> 4 |
| 254.757 | same kill: GLS server-device disable -> 7 |
| 255.108 | restarted X ScreenInit -> 2, and it stays even
|
The +1 is a one-time first-generation event: it is independent of AutoAddGPU/AutoBindGPU, of -keeptty, and of -noreset. A restarted X does not repeat it, including when GL clients connect. The deterministic recipe is therefore: start the accelerated NoScanout X, wait for it to settle, sample the word, restart X once if it is odd, re-verify, and only then start the application. mode-even-gate.sh encodes this.
Measured result: in the vid1 cycle the gate read MODE 3 on the first X, restarted, then held 15,458/15,458 samples at MODE 2, including the whole GZDoom window. With the gate applied and the campaign module loaded, the VBO gate is green: glBufferData(data) returns err=0, glMapBufferRange returns a valid pointer, and the mapped content reads 0xa5. The FBO path still returns 0x8cdd (unsupported) but no longer blocks buffer objects.
4. The host vGPU display-control lane [live] (implemented, not selected by the stock DDX)
The X driver contains a vGPU virtual-display HAL that hands the guest's scanout surface to the host instead of binding a physical GPU screen. It uses two control classes:
NVA083(virtual-display head queries) —GET_NUM_HEADS,GET_MAX_RESOLUTION,GET_DEFAULT_EDID,IS_ACTIVE,IS_CONNECTED,GET_MAX_PIXELS.NVA080(KEPLER_DEVICE_VGPU) —VGPU_GET_CONFIG,VGPU_DISPLAY_SET_SURFACE_PROPERTIES(head index, primary flag, memory handle, offset, layout, block height, pitch, format, width, height, rect, size) andVGPU_DISPLAY_CLEANUP_SURFACE_PARAMSon head teardown.
The host module implements this lane:
GET_CLASSLIST_V2(0x800292) advertises the TU104 class list plus0xA083;GET_VIRTUALIZATION_MODE(0x800289) reports the vGPU mode; theA083queries and theA080config/set/cleanup controls are answered.- A per-vgpu surface record is kept. The surface's
hMemoryis resolved through the RM memory-object table (sysmem only); an unresolved kernel-local vidheap handle still succeeds and records the metadata, without synthesising a physical address. - A pitch-linear present copies the registered surface into the emulated BAR1 scanout window (default offset
0x200000; no pixel synthesis; bounds 64 MiB / 4096 px). Module parameters:disp_vgpu(enable),disp_vgpu_present,disp_vgpu_surf_gpa(evidence override) anddisp_vgpu_scanout_off.
Current limitation (measured). The stock X driver's built-in virtual HAL is selected only when the guest kernel's class list advertises NVA083_GRID_DISPLAYLESS (0xA083). That class list is answered inside the guest kernel from its compiled TU104 descriptor list, which carries the Kepler vGPU device and the NVA081/NVA084 classes but not 0xA083. The host's GET_CLASSLIST_V2 emulation therefore never sees the query, and the stock DDX cannot select the virtual HAL. The guest-side virtual-display program (§2) is the supported route; the host lane remains the interface for a guest program that chooses to use the vGPU display controls directly.
The lane was validated for wire correctness in a live cycle: the guest-side virtual HAL did not run (as expected from the class list), and the host lane is inert when the guest never sends the 0xA08x controls.
5. Current state and walls (2026-11-22)
Both old blockers on the path to a captured frame are closed:
- mode parity is deterministic with the restarted-X gate (§3);
- the VBO path allocates and maps with an even word (§3);
- the engine no longer faults on the emitted replay window:
r1783(3b7310e1) walks the emitted 3D window with the FIFO run grammar and cuts it at the last complete run boundary before any prepend. Measured: zeroCh 00000001 ... Off 0x1654/0x1b34/0x2024/0x2294/0x2504/0x2774data faults, zeroILLEGAL_OPCODE, andGUEST GR LAUNCH OKon the direct-GL launch. - the 4 GiB context-buffer class is gone:
r1784(841b51b5) clamps the sevenNV_U32_MAXentries in the physical KGR context-buffer snapshot to 0 before it is served (KGR ctxbuf snapshot: clamped 7 ...), removing the allocation/OOM class that killed earlier attempts.
The remaining wall is MME pack residency on the second direct-GL window. In the vid2c cycle the first 0xbeef0100 carrier is load-only and reports MME-PRELUDE pack-part ir_words=1608/2805 split=1 with pack_done_gen=0; the launch completes. The next carrier replays a shorter window (178 words) with no IR continuation, and the MME latches esr=badf1201 pc_valid=1 pc=513 macro_addr=0xf1. The lane is poisoned, the hard re-arm cannot recover the context, and the launch ends in GR LAUNCH FAILED timeouts. The guest's GL thread is then found spinning in libnvidia-glcore (sched_yield), waiting for a GPU-side completion, not in an X/GLX reply poll. The application stops at V_Init: allocate screen and glXSwapBuffers is never reached, so the sink captures zero frames.
A/B results (all one mdev, stock guest driver):
| Arm | Result |
|---|---|
| Baseline (prelude + split pack) | Partial pack 1608/2805, second window poisons the MME (esr=badf1201 pc=513), no draw, no swap
|
sema_gl_mme_prelude=0 (pack/golden off)
|
0 poison, 0 wedge, 301/301 GR OK, engine stable — but no draw admission (has_draw=0)
|
sema_gl_mme_partial_keep_window=0
|
0 poison/0 wedge, but 19 timeouts: the windowless pack-drain carriers themselves time out |
sema_gl_mme_block_cap=3968 sema_gl_mme_pack_split=0
|
The >2000-word block does not start; 3 poisons, 9 re-arms, 6 park recoveries |
r1785 diagnostics (BLOCKVAL with the hardware's 13-bit count, emitted-block dump)
|
0 bad words in every emitted block: the window grammar and the tail trim are correct; the poison is executing draw state while only 1608/2805 pack IR words are resident |
The negative result is itself useful: the window grammar is valid and the emitted window is not malformed. The failure is the pack drain: the missing pack continuation was never emitted on the next launch (the cursor stayed at 1608, and no second MME-PACK-EMIT appeared).
Next steps, in order:
- Make the pack drain mandatory before any window: keep
pack_done_gen=0launches windowless, or force the missing continuation onto the next launch, so the MME never executes draw state against a partial pack. - Keep the RT0 colour-target admission independent of the MME prelude so the prelude-off arm can still admit the draw.
- Re-run the
vid1recipe (HOME=/root, 1536x864,sdl_cap.so+ffmpeg) and require non-black captured frames with motion. - Only then treat the virtual-display path as ready for the release video.
6. How to run it
Host (clean host: vgsp unloaded, no QEMU, no mdev):
bash tools/guest-diag/vdisp/win-host.sh <tag>
That command runs the flock-serialised cycle (module + one mdev + QEMU), pushes the guest package, applies the mode-parity gate, runs the GL object probe and then the application with the capture shim, and pulls the evidence back. The guest-side recipe (already encoded in mode-even-gate.sh) is:
# guest, as root, after a settled boot (uptime >= 240 s) /tmp/mode-even-gate.sh <tag> /tmp/globjprobe
Build the guest-side binaries:
cc -O2 -o globjprobe globjprobe.c -lGL -lX11 cc -O2 -o glburn glburn.c -lGL -lX11 cc -shared -fPIC -O2 -o sdl_cap.so sdl_cap.c -lX11 -lGL -ldl
7. What is not claimed
- This page does not claim a vGPU-rendered video yet. The mode parity, VBO and engine-fault gates are green, but no swap has been reached under the capture shim since those fixes, so
sdl_capproduced zero frames andmp4=0in every cycle. No vGPU-rendered video exists yet. - The host
NVA080/NVA083lane is implemented and wire-correct, but the stock DDX does not select its virtual HAL on the stock guest kernel's class list. It is not the mechanism the current sink uses. - No frame-rate claim is made here; the X/GLX speed wall is tracked on
OpenGL.mdandGraphics-Execution.md.
8. Related pages
Graphics-Execution.md— the 3D execution lanes, including the display engine that serves the guest's modeset push buffers.OpenGL.md— the guest OpenGL stack and the X/GLX speed wall.Project-Status.md— the dated project state.Project-Plan.md— the graphics phase and its gates.Physical-GPU-Backend.md— how guest work reaches the physical GPU.Host-Module.md— where the display-control lane and the emulated scanout window live.