Difference between revisions of "Graphics Execution"
m (2026-11-15 (evening) status refresh: saved-window release carrier deterministic (c772), slot-34 census + SA[34] golden fill (0x265), release-window reorder landed but unexercised; the remaining blocker is call order; pack-completion lottery; DS 0x84000420 and stores remain) |
m (2026-11-18 late status refresh: CUDA CE push page + fresh-CE walk seed fixed; the wall is now the guest-side UVM page-tree-init push; GL pixel gate held; checkpoint 5b23a983 noted) |
||
| (6 intermediate revisions by the same user not shown) | |||
| Line 5: | Line 5: | ||
<blockquote>'''Scope.''' How the emulated vGPU runs '''3D graphics''' work — the OpenGL and Vulkan command streams a stock guest submits — on the physical GPU, and what is proven about it. This is the shared machinery behind [[OpenGL|<code>OpenGL.md</code>]], [[Vulkan|<code>Vulkan.md</code>]] and the Windows/DirectX target ([[DirectX|<code>DirectX.md</code>]]); CUDA compute uses the same submission and completion path for a different engine workload ([[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 milestone ladder) and [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); the docs tree wins on disagreement.</blockquote> | <blockquote>'''Scope.''' How the emulated vGPU runs '''3D graphics''' work — the OpenGL and Vulkan command streams a stock guest submits — on the physical GPU, and what is proven about it. This is the shared machinery behind [[OpenGL|<code>OpenGL.md</code>]], [[Vulkan|<code>Vulkan.md</code>]] and the Windows/DirectX target ([[DirectX|<code>DirectX.md</code>]]); CUDA compute uses the same submission and completion path for a different engine workload ([[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 milestone ladder) and [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); the docs tree wins on disagreement.</blockquote> | ||
Status: 2026-11- | Status: 2026-11-18, tree <code>master @ 5b23a983</code>. Tags: <code>[live]</code> observed end to end; <code>[wip]</code> partially built; <code>[wall]</code> current blocker; <code>[target]</code> defined success state; <code>[planned]</code> designed, not built. | ||
== 1. What "real pixels" means == | == 1. What "real pixels" means == | ||
| Line 31: | Line 31: | ||
# '''Verbatim 3D method-stream replay''' <code>[live]</code>. The emulation captures the X server's graphics-class (<code>0xC597</code>, <code>TURING_A</code>) section from its channel, relocates the operand addresses into host-built shadow pages the engine can reach, and submits the stream unchanged. The engine retires it: the uploads (<code>LINE_LENGTH_IN</code>/<code>LAUNCH_DMA</code>), the state, program and texture binds, and the release all execute with no MMU fault. This proves the ''mechanics'' of 3D execution — object bind, window placement, operand relocation, completion — on real hardware. | # '''Verbatim 3D method-stream replay''' <code>[live]</code>. The emulation captures the X server's graphics-class (<code>0xC597</code>, <code>TURING_A</code>) section from its channel, relocates the operand addresses into host-built shadow pages the engine can reach, and submits the stream unchanged. The engine retires it: the uploads (<code>LINE_LENGTH_IN</code>/<code>LAUNCH_DMA</code>), the state, program and texture binds, and the release all execute with no MMU fault. This proves the ''mechanics'' of 3D execution — object bind, window placement, operand relocation, completion — on real hardware. | ||
# '''Synthesized launch from a captured section''' <code>[live]</code>. A compute-shaped launch built from the captured section (operand list, program, a 64-word launch descriptor) reaches the engine and retires real <code>sm_75</code> SASS; the Turing shader-program-header form (<code>V3</code>) is accepted with zero header faults across repeated launches. This proved engine-side dispatch before the verbatim lane existed. The program itself is still a development stand-in at this rung — execution proof, not pixels. | # '''Synthesized launch from a captured section''' <code>[live]</code>. A compute-shaped launch built from the captured section (operand list, program, a 64-word launch descriptor) reaches the engine and retires real <code>sm_75</code> SASS; the Turing shader-program-header form (<code>V3</code>) is accepted with zero header faults across repeated launches. This proved engine-side dispatch before the verbatim lane existed. The program itself is still a development stand-in at this rung — execution proof, not pixels. | ||
# '''Forwarding the client's own pushes''' <code>[wip]</code>. The X DDX channel <code>0x1000014</code> executes its 3D replay (12 launches per cycle), the 2D path is green, and a guest pbuffer <code>glClear(red)+glFinish+glReadPixels</code> probe returns a real pixel (<code>pixel=ff0000ff</code>): the replay and readback machinery works. The off-screen frame path then produced '''500/500 non-black 640x480 animated frames''' per run and captured videos (45.4 s on 2026-11-11; a 50 s 640x480 h264 capture on 2026-11-12). X and the stock NVIDIA GLX path are fully green (<code>glxinfo -B</code> returns 0, OpenGL 4.6.0 direct, <code>glxgears</code> ~520 FPS), and GZDoom reaches <code>V_Init: allocate screen</code> with its GL 4.6.0 context whenever the shared nvClip <code>modeNum</code> is even. The direct-GL ring/VAS anchor and USERD machinery are substantially hardened (verified page-directory discovery, per-rank content scans, eager push pins, client-allocated USERD resolution, foreign-USERD skip, aperture-aware fallback, wrapped-PUT acceptance), and the 11-12/11-13 wave closed the X side of the path: the DDX idle-DMA/ScreenInit wall, the USERD-latch lifetime, the same-pass re-probe thrash, the post-ScreenInit Xorg kernel-mode spin (a display-engine GET-past-PUT on a driver ring wrap) and the flip-event timeout are all fixed, and captured GL sections now execute on the engine (<code>GR LAUNCH submitted</code> / <code>GUEST GR LAUNCH OK</code>) with the data window populated (<code>n_data</code> 0 -> 1024). The direct-GL client's submission is now '''fully decoded''': no client push carries a method-grammar draw header — its nine NV906F GPFIFO entries tile one contiguous buffer and its per-frame work is carried as rewritten data-block blobs plus small real state pushes (324/476/728 B, head <code>90110087 80000800</code>) that invoke MME macros (the QMD-carrier hypothesis was tested and refuted: the entry format has no QMD bit, the blob is not a QMD, and no QMD magic exists in the 256 MiB BAR1). Delivery into the lane then landed: a content-gated FB-shadow rescue (<code>e1eac368</code>) and the LOW-band rescue (<code>b7f09616</code>) recover the recycled client pushes, the 324-B draw-state push opens a <code>C597</code> section, is captured and marked for the verbatim 3D lane (the first direct-GL stream3d marks), and with the golden MME overlay satisfying the prelude gate it '''reaches the engine''' (<code>GR LAUNCH submitted</code> + OK, MME-PRELUDE pack 1701 IR words, MME-GOLDEN slot 0 accepted). The MME chain then advanced from the multi-part gate to '''draw-macro execution''': the multi-part keep-window mechanism won multi-frame windows, the part-launch poison was eliminated (the real fault was the client's own <code>SET_REPORT_SEMAPHORE</code>/<code>SET_NOTIFY</code> writes to client VAs remapped by the host scratch page-table pool — redirected to a mapped scratch slot; 49 cycles with zero poison and zero MMU faults), the 2799-word pack completes (2799/2799), engine-global completion plus keep-done-across-recycle produced the first <code>MME-PACK-REARM</code>, the fixed-CB region is aliased, and the released calls run macros through to '''<code>DRAW_IAB</code> (<code>mac=0x22</code>)'''. Two synthesized-prelude defects were then fixed: the SPH-BIND prelude self-destructed because an auto-dropped run broke its kept/final count (<code>444ae2c1</code>), and the stage block was silently skipped by a double-counted budget; with both fixed the prelude emits 84 words and the DS stage VAs populate (one validated boot carried the full post-REARM chain, <code>mac=0x22</code> and <code>DS 86040624</code>). The '''DS stage-0/1 image is now authored and live''': the module writes a VTG SPH at <code>family+0x900</code> (<code>SPH-AUTHOR</code>, first word <code>020a0481</code>), rewrites the window's own later <code>0x2054</code> slot-1 bind to the authored page (<code>SPH-SLOT1-REWRITE</code>), and the DS latch reads the authored image for both vertex slots (<code>DS-IMAGE st0=st1=020a0481 code=ff007321</code>; the DS value fell <code>0x86040626 -> 0x84000420</code>), reproduced on two boots. The release path is now host-deterministic when the pack completes: a saved-window release carrier snapshots the held window at <code>MME-CALL-HOLD</code> and re-submits it with the calls released once the pack is resident (c772: <code>MME-CARRY-SAVE win=240 held=68</code> -> <code>MME-CARRY-FIRE mode=release</code> -> synthetic <code>GR LAUNCH push=0x6d6d6500</code> -> <code>MME-PACK-REARM</code> gen=5 -> DS <code>0x84000420</code> -> <code>MME-CARRY-COMPLETE</code>), and the held-CALL census plus the SA[34] golden fill prove the <code>DRAW_IAB</code> call and its target are present (<code>MME-CALL-TARGET slot=34 method=0x3910 client=0x265 golden=0x265 used=0x265</code>; <code>MME-GOLDEN sa-fill slot=34 entry=0x265</code>). | # '''Forwarding the client's own pushes''' <code>[wip]</code>. The X DDX channel <code>0x1000014</code> executes its 3D replay (12 launches per cycle), the 2D path is green, and a guest pbuffer <code>glClear(red)+glFinish+glReadPixels</code> probe returns a real pixel (<code>pixel=ff0000ff</code>): the replay and readback machinery works. The off-screen frame path then produced '''500/500 non-black 640x480 animated frames''' per run and captured videos (45.4 s on 2026-11-11; a 50 s 640x480 h264 capture on 2026-11-12). X and the stock NVIDIA GLX path are fully green (<code>glxinfo -B</code> returns 0, OpenGL 4.6.0 direct, <code>glxgears</code> ~520 FPS), and GZDoom reaches <code>V_Init: allocate screen</code> with its GL 4.6.0 context whenever the shared nvClip <code>modeNum</code> is even. The direct-GL ring/VAS anchor and USERD machinery are substantially hardened (verified page-directory discovery, per-rank content scans, eager push pins, client-allocated USERD resolution, foreign-USERD skip, aperture-aware fallback, wrapped-PUT acceptance), and the 11-12/11-13 wave closed the X side of the path: the DDX idle-DMA/ScreenInit wall, the USERD-latch lifetime, the same-pass re-probe thrash, the post-ScreenInit Xorg kernel-mode spin (a display-engine GET-past-PUT on a driver ring wrap) and the flip-event timeout are all fixed, and captured GL sections now execute on the engine (<code>GR LAUNCH submitted</code> / <code>GUEST GR LAUNCH OK</code>) with the data window populated (<code>n_data</code> 0 -> 1024). The direct-GL client's submission is now '''fully decoded''': no client push carries a method-grammar draw header — its nine NV906F GPFIFO entries tile one contiguous buffer and its per-frame work is carried as rewritten data-block blobs plus small real state pushes (324/476/728 B, head <code>90110087 80000800</code>) that invoke MME macros (the QMD-carrier hypothesis was tested and refuted: the entry format has no QMD bit, the blob is not a QMD, and no QMD magic exists in the 256 MiB BAR1). Delivery into the lane then landed: a content-gated FB-shadow rescue (<code>e1eac368</code>) and the LOW-band rescue (<code>b7f09616</code>) recover the recycled client pushes, the 324-B draw-state push opens a <code>C597</code> section, is captured and marked for the verbatim 3D lane (the first direct-GL stream3d marks), and with the golden MME overlay satisfying the prelude gate it '''reaches the engine''' (<code>GR LAUNCH submitted</code> + OK, MME-PRELUDE pack 1701 IR words, MME-GOLDEN slot 0 accepted). The MME chain then advanced from the multi-part gate to '''draw-macro execution''': the multi-part keep-window mechanism won multi-frame windows, the part-launch poison was eliminated (the real fault was the client's own <code>SET_REPORT_SEMAPHORE</code>/<code>SET_NOTIFY</code> writes to client VAs remapped by the host scratch page-table pool — redirected to a mapped scratch slot; 49 cycles with zero poison and zero MMU faults), the 2799-word pack completes (2799/2799), engine-global completion plus keep-done-across-recycle produced the first <code>MME-PACK-REARM</code>, the fixed-CB region is aliased, and the released calls run macros through to '''<code>DRAW_IAB</code> (<code>mac=0x22</code>)'''. Two synthesized-prelude defects were then fixed: the SPH-BIND prelude self-destructed because an auto-dropped run broke its kept/final count (<code>444ae2c1</code>), and the stage block was silently skipped by a double-counted budget; with both fixed the prelude emits 84 words and the DS stage VAs populate (one validated boot carried the full post-REARM chain, <code>mac=0x22</code> and <code>DS 86040624</code>). The '''DS stage-0/1 image is now authored and live''': the module writes a VTG SPH at <code>family+0x900</code> (<code>SPH-AUTHOR</code>, first word <code>020a0481</code>), rewrites the window's own later <code>0x2054</code> slot-1 bind to the authored page (<code>SPH-SLOT1-REWRITE</code>), and the DS latch reads the authored image for both vertex slots (<code>DS-IMAGE st0=st1=020a0481 code=ff007321</code>; the DS value fell <code>0x86040626 -> 0x84000420</code>), reproduced on two boots. The release path is now host-deterministic when the pack completes: a saved-window release carrier snapshots the held window at <code>MME-CALL-HOLD</code> and re-submits it with the calls released once the pack is resident (c772: <code>MME-CARRY-SAVE win=240 held=68</code> -> <code>MME-CARRY-FIRE mode=release</code> -> synthetic <code>GR LAUNCH push=0x6d6d6500</code> -> <code>MME-PACK-REARM</code> gen=5 -> DS <code>0x84000420</code> -> <code>MME-CARRY-COMPLETE</code>), and the held-CALL census plus the SA[34] golden fill prove the <code>DRAW_IAB</code> call and its target are present (<code>MME-CALL-TARGET slot=34 method=0x3910 client=0x265 golden=0x265 used=0x265</code>; <code>MME-GOLDEN sa-fill slot=34 entry=0x265</code>). '''The draw macro now executes end to end.''' c788 proved <code>DRAW_IAB</code> (<code>mac=0x22</code>) running on the released held window after the <code>MME-DRAW-PLAN</code>/<code>MME-DRAW-MOVE</code> reorder (<code>MME-FAST ... mac=0x22 run=1</code>), and the per-stage SPH disable (TCS off, <code>45dbcdcd</code>) clears the DS latch entirely — the <code>0x84000420</code> was the synthesized TCS bind. The DRAW_IAB body decodes with the public Mesa MME toolchain (<code>mme_tu104_sim</code>): slot 34 (<code>0x265</code>) emits 8 draws of 3 vertices (<code>SET_VERTEX_ARRAY_START</code> 0..21, <code>DRAW_VERTEX_ARRAY</code> 3). A synthetic full-RT viewport (<code>dab4a02c</code>) and a release chained after any GR launch (<code>3481e62d</code>) complete the replay. '''The 11-16 wave then proved the host-side chain end to end.''' The real frame pushes are admitted: the colour-target bind is persisted from an earlier trusted push (<code>RT-PERSIST</code>; the client binds the target once, not per frame), draw markers are accepted inside counted method runs, and the 14.8-thousand-word window is admitted and replayed as 40 chunks with a data-led start snap (<code>WIN-START-SNAP</code>) and a 128-slot candidate ring. The beef draw lane latches a '''clean DS''' (<code>DS-FAST2 ... ds_after=80000000</code>, c963) at the live-derived GS attribute map (maps=6), with no SPH18; the draw anchor now moves the call after the first <code>0x3810</code> vertex-stream run and the raster enables are emitted. Capture-less boots get a '''golden 2799-word MME pack''' built from the golden library (<code>MME-GOLDEN</code>, <code>MME-PRELUDE</code>), and the chain <code>MME-CALL-HOLD -> MME-CARRY-SAVE -> MME-CARRY-FIRE -> MME-PACK-REARM -> MME-SA-REARM</code> fires; the prelude latch survives the per-fire channel recycle (<code>MME-LATCH-KEEP</code>) and every admitted-window chunk is forwarded in order. '''The late-11-16 wave crossed the guest submission gap.''' An offscreen SDL EGL/GBM shim (<code>GZ_EGL</code>) gives the guest a real NVIDIA GL context without Xorg/DDX (<code>GL_RENDERER: NVIDIA GeForce RTX 2080 SUPER/PCIe/SSE2</code>, <code>GL_VERSION: 4.6.0 NVIDIA 570.144</code> — no llvmpipe). The real GZDoom draw window then surfaced: 12068 B at push <code>0x402f9d8</code> (3017 words), carrying no <code>0x3910/0x3914</code> write. Its draw is an IMMD (op 4) CALL to method <code>0x3800</code> (<code>imm=0xd48</code> = 3400) plus CALL slots 44/57/58 (<code>0x3960</code>, <code>0x39c8</code>, <code>0x39d0</code>), 7x <code>0x1b00</code> inline uploads, and state words. The window carries no colour-target bind of its own, so RT-gated admission had refused it (it retired through the compute-QMD lane); recognition now covers the real marker (<code>0x3800</code> op=4 with <code>imm>=0x100</code>, plus the three secondaries; <code>0x3910/0x3914</code> kept), admission happens on the real marker even without a bind, the CALL-bearing chunk is forced first, and every chunk is replayed verbatim. c1025 receipts: <code>GL-FLUSH ... admitted=1</code>, <code>DRAW-WRITE ... m=0x3800 op=4 data=0xd48</code>, <code>3D mark admitted (CALL(0) 0x3800 draw marker)</code>, <code>3D stream chunked</code> (4 chunks), <code>3D chunk launch ... draw=1</code>, <code>MME-CALL-ARGS slot=0 data=0xd48</code>, <code>MME-EXEC-CALL slot=0</code>. '''CALL(0) no longer wedges''': eng89t resolves the CALL(0) immediate as an IR address through the client SA[0] (then golden) and elides an op=4 CALL(0) whose body is not resident for this launch to a NOP (<code>MME-CALL-UNMAPPED ... reason=not-resident</code>) so the ladder continues. On c1026/c1027 the real draw's CALL(0) entered its captured macro (<code>macro-status=00000004</code>, <code>mpc</code> 0->4) without trapping, and c1027 produced the first DS with real stage data (<code>DS-FAST2 ds_after=83044206 stage=015e0900,015e0a00,015c0400</code>). The trap code <code>0x80001528</code> is decoded as the sticky <code>NV_PGRAPH_TRAPPED_ADDR</code> latch (bit31 INVALID, subch 0, method <code>0x1528</code> = <code>SET_SHADER_EXCEPTIONS</code>), not a cause/PC; the surviving wedge is the synthetic golden macro body (<code>badf1201 pc=513 mac=0xf1</code>) on a non-CALL(0) launch. '''Remaining gap (precise):''' the client's per-draw MME macro body was never captured — the 59580-byte prelude carries only the 12 setup macros (573 code words, pc 0..0x98), the draw push has no <code>0x114/0x11c</code>, and <code>0xd48</code> is a macro length/argument, not an IR entry. The engine has the real draw method stream but not the body to execute. Next: capture the per-draw <code>0x114</code> upload (every beef push plus the X/2D channel) or implement/verify the MME64 body, install it before the draw launch, then check <code>DS-FAST2 ds_after=8[01]</code>, <code>GUEST-WIT va=0x15d</code>, <code>wrote>0</code>, <code>px0!=0</code>. No vGPU surface store or pixel is proven yet (<code>wrote=0</code>, no <code>px_nonblack</code>). The software-GL GZDoom video (four files, 22 s flight + 18 s orbit, 640x480/1280x960, 30 fps, byte-verified) remains the guaranteed-quality deliverable and is not a vGPU rendering claim; the pack-completion and X-start lotteries still gate run rate. | ||
== 4. The channel and object picture == | == 4. The channel and object picture == | ||
| Line 45: | Line 45: | ||
The acceptance signal is the '''engine-authored release''': a semaphore the engine writes when the work completes. For GL, completion flows through the channel's semaphores/notifications to the X server and the app's swap wait; for Vulkan, the client's fence value is released; for CUDA, the launch's release group wakes the client. The emulation relays engine completions into guest-observable memory (MSI-X plus a poller), and the guest resumes from there. | The acceptance signal is the '''engine-authored release''': a semaphore the engine writes when the work completes. For GL, completion flows through the channel's semaphores/notifications to the X server and the app's swap wait; for Vulkan, the client's fence value is released; for CUDA, the launch's release group wakes the client. The emulation relays engine completions into guest-observable memory (MSI-X plus a poller), and the guest resumes from there. | ||
For the display path, completion is the notifier write and <code>UPDATE -> FINISHED</code>; a completion event deferred by the reply path is force-retried until it posts, so the X server's mode set finishes. For the X DDX's own 2D push buffers, completion also requires the GPU-written engine get word to advance and the notifier to be recycled to <code>0xffff</code> after a kick; both are host-side levers now, and a diagnostic write of the get word released the DDX's reserve loop. For a windowed GL client the present is a kick; the GSP event-IRQ fix now sets the RISC-V SWGEN0 IRQSTAT/IRQMASK/IRQDEST and latches the CPU-tree leaf, so the guest services the event and glxgears completes swaps, and the GR backend no longer times out (the pair-close/pair-safe replay fixes are default ON; draws retire in 3-2400 ms). The stock GLX path is fully green (<code>glxinfo -B</code> returns 0 with OpenGL 4.6.0 direct rendering; <code>glxgears</code> renders ~520 FPS; the Xorg channel-idle WAIT count is zero), the DDX 3D replay renders and reads back a pbuffer pixel (<code>pixel=ff0000ff</code>), the off-screen frame path produced non-black animated frames and captured videos (45.4 s and 50 s), the RM write-lock holder (Xorg in the DDX vidheap scrub wait) is fixed (<code>df6e71bb</code>), the X DDX/ScreenInit stability walls are closed, and the direct-GL ring/USERD machinery is hardened. The MME pack completes and the draw macro runs, and the authored DS stage image is live for both vertex slots; the | For the display path, completion is the notifier write and <code>UPDATE -> FINISHED</code>; a completion event deferred by the reply path is force-retried until it posts, so the X server's mode set finishes. For the X DDX's own 2D push buffers, completion also requires the GPU-written engine get word to advance and the notifier to be recycled to <code>0xffff</code> after a kick; both are host-side levers now, and a diagnostic write of the get word released the DDX's reserve loop. For a windowed GL client the present is a kick; the GSP event-IRQ fix now sets the RISC-V SWGEN0 IRQSTAT/IRQMASK/IRQDEST and latches the CPU-tree leaf, so the guest services the event and glxgears completes swaps, and the GR backend no longer times out (the pair-close/pair-safe replay fixes are default ON; draws retire in 3-2400 ms). The stock GLX path is fully green (<code>glxinfo -B</code> returns 0 with OpenGL 4.6.0 direct rendering; <code>glxgears</code> renders ~520 FPS; the Xorg channel-idle WAIT count is zero), the DDX 3D replay renders and reads back a pbuffer pixel (<code>pixel=ff0000ff</code>), the off-screen frame path produced non-black animated frames and captured videos (45.4 s and 50 s), the RM write-lock holder (Xorg in the DDX vidheap scrub wait) is fixed (<code>df6e71bb</code>), the X DDX/ScreenInit stability walls are closed, and the direct-GL ring/USERD machinery is hardened. The MME pack completes and the draw macro runs, and the authored DS stage image is live for both vertex slots; the released replay executes the <code>DRAW_IAB</code> (<code>mac=0x22</code>) with a synthetic viewport, and the 11-16 wave proved the whole host chain deterministic (admission of the real pushes, clean DS, golden pack, CALL hold, carry fire, SA re-arm). The late-11-16 wave then crossed the guest submission gap: a real NVIDIA EGL context without Xorg/DDX, the real GZDoom op=4 <code>CALL(0)</code> <code>0x3800</code> draw admitted and replayed, <code>CALL(0)</code> entering its captured macro without trapping, and the first DS with real stage data. The '''GL pixel gate closed on 2026-11-18''' (<code>b5a68b9a</code>): a stock guest <code>glReadPixels</code> now reads a non-black frame produced by the physical engine through the emulated vGPU (<code>GL_FRAME nonblack=291840 px0=(255,0,0)</code>, two consecutive boots; live <code>t/04</code> green, <code>EXPECT_GL_PIXELS=closed</code>). The remaining public wall is the window/screen present (glxgears/X), X start speed and the boot lottery. | ||
During bring-up the module also carries a '''diagnostics-only mirror''' for apps that spin on a shared progress word; it exists so a run can proceed while the natural completion path is being finished. The 60-fps milestone explicitly requires it switched off, along with any external poke. | During bring-up the module also carries a '''diagnostics-only mirror''' for apps that spin on a shared progress word; it exists so a run can proceed while the natural completion path is being finished. The 60-fps milestone explicitly requires it switched off, along with any external poke. | ||
| Line 51: | Line 51: | ||
== 6. Where the frontier is (ranked walls) == | == 6. Where the frontier is (ranked walls) == | ||
'''Closed - the GL pixel gate (2026-11-18).''' The long per-draw-MME-macro investigation ended without that body being needed. The host archives the first accepted window that carries the client clear (0x19d0) or the direct-GL CALL(0) marker and replays it when a later window of the same channel carries neither (<code>f2a4f1be</code>, <code>sema_gl_win_keep</code>; receipt <code>GL-WIN-SELECT keep ... clear=0 call0=1 win=369 alias_gen=1</code>); the engine clear then stores red on the guest surface (<code>OUT-UNCH ... guest=ff0000ff</code>, <code>GUEST-WIT retire ... changed</code>); the CE D2H readback follows the copy's source VA rather than the X-screen guess (<code>b5a68b9a</code>, <code>RB-SURF adopt</code>), with a generation-pinned snapshot (<code>439c52c9</code>) and the low-aperture fence delivered with the copy (<code>7fa7528e</code>, <code>439c52c9</code>; the driver's measured ~11 s wait fell to 2.3-7.2 ms in the winning boots). Two consecutive boots read <code>GL_FRAME nonblack=291840 px0=(255,0,0)</code>; the live acceptance lane is green (<code>t/04</code>, <code>EXPECT_GL_PIXELS=closed</code>); the gate was re-verified in r27e/r28d/r29c/r31b; the proof frame is <code>r23j-artifact/{frame.raw,ppm,png,mp4}</code>. The per-draw macro body remains a research path (<code>[wip]</code>), not a pixel blocker. The boot lottery (an engine store after the guest's read, or no store at all) survives as a hardening item. | |||
# '''Window/screen present''' <code>[wall]</code>. The pbuffer and off-screen frame paths are proven (<code>pixel=ff0000ff</code>, 500/500 non-black frames, captured videos), but a windowed present does not land: glxgears' window is black, the DDX shared-surface <code>gpuRefCount</code>/<code>lastKickoffRefCount</code> poll (W1) must be satisfied through a verified surface VA, and a synchronous window draw wedges X. | # '''Window/screen present''' <code>[wall]</code>. The pbuffer and off-screen frame paths are proven (<code>pixel=ff0000ff</code>, 500/500 non-black frames, captured videos), but a windowed present does not land: glxgears' window is black, the DDX shared-surface <code>gpuRefCount</code>/<code>lastKickoffRefCount</code> poll (W1) must be satisfied through a verified surface VA, and a synchronous window draw wedges X. | ||
# '''X screen-init and stability''' <code>[wip]</code> (was <code>[wall]</code>). The idle-DMA/ ScreenInit class, the USERD-latch lifetime, the same-pass re-probe thrash, the post-ScreenInit Xorg kernel-mode spin (display-engine GET-past-PUT on a driver ring wrap) and the flip-event timeout are fixed, and X has stayed green for >10 minutes in a validated window. What remains is a per-boot '''first-generation lottery''' that became the dominant throughput limiter for the graphics A/B runs: only an X started immediately after boot passes the DDX DMA init (3/7 windows in one runoff; long dead-start stretches later, with one green first-start boot, c382), later DMA instances can still fail, and the shared nvClip <code>modeNum</code> must be even for the GL client's state init (an odd value is guest userspace X-driver state, cleared by one X restart — not a host bug). Wrapped PUTs and the kick-idle marker/GET publication are handled; a guest kernel panic after a wedge is recovered by an offline filesystem check. | # '''X screen-init and stability''' <code>[wip]</code> (was <code>[wall]</code>). The idle-DMA/ ScreenInit class, the USERD-latch lifetime, the same-pass re-probe thrash, the post-ScreenInit Xorg kernel-mode spin (display-engine GET-past-PUT on a driver ring wrap) and the flip-event timeout are fixed, and X has stayed green for >10 minutes in a validated window. What remains is a per-boot '''first-generation lottery''' that became the dominant throughput limiter for the graphics A/B runs: only an X started immediately after boot passes the DDX DMA init (3/7 windows in one runoff; long dead-start stretches later, with one green first-start boot, c382), later DMA instances can still fail, and the shared nvClip <code>modeNum</code> must be even for the GL client's state init (an odd value is guest userspace X-driver state, cleared by one X restart — not a host bug). Wrapped PUTs and the kick-idle marker/GET publication are handled; a guest kernel panic after a wedge is recovered by an offline filesystem check. | ||
| Line 159: | Line 160: | ||
| <code>[live]</code> | | <code>[live]</code> | ||
|- | |- | ||
| <code>DRAW_IAB</code> (<code>mac=0x22</code>) executes on the | | <code>DRAW_IAB</code> (<code>mac=0x22</code>) executes on the released held window after the <code>MME-DRAW-PLAN</code>/<code>MME-DRAW-MOVE</code> reorder (c788: <code>MME-FAST ... mac=0x22 run=1</code>); the body decodes with the public Mesa MME toolchain (<code>mme_tu104_sim</code>: slot 34, 8 draws of 3 vertices) | ||
| <code>[live]</code> | |||
|- | |||
| DS stage-0/1 image: a VTG SPH is authored at <code>family+0x900</code> and the window's own slot-1 bind rewritten to it; the DS latch reads <code>st0=st1=020a0481</code> | |||
| <code>[live]</code> | |||
|- | |||
| Saved-window release carrier (held window snapshotted at <code>MME-CALL-HOLD</code> and re-submitted with calls released once the pack is resident, c772); held-CALL census + SA[34] golden fill (<code>client=golden=used=0x265</code>); synthetic full-RT viewport (<code>dab4a02c</code>); release chained after any GR launch (<code>3481e62d</code>) | |||
| <code>[live]</code> | |||
|- | |||
| Per-stage SPH disable (TCS off, <code>45dbcdcd</code>) clears the DS latch (the <code>0x84000420</code> was the synthesized TCS bind) | |||
| <code>[live]</code> | |||
|- | |||
| Real frame pushes admitted: persisted colour-target bind from an earlier trusted push (<code>RT-PERSIST</code>), draw markers accepted inside counted method runs, 14.8-thousand-word window admitted and replayed as 40 chunks (<code>3D stream chunked ... -> 40 chunk(s)</code>), data-led start snap (<code>WIN-START-SNAP</code>), 128-slot candidate ring | |||
| <code>[live]</code> | |||
|- | |||
| Clean DS on the beef draw lane after the full-window chunking (<code>DS-FAST2 ... ds_after=80000000</code>, c963) at the live-derived GS attribute map (maps=6), no SPH18; draw anchor after the first <code>0x3810</code> and raster enables emitted | |||
| <code>[live]</code> | |||
|- | |||
| Golden 2799-word MME pack on capture-less boots (<code>MME-GOLDEN overlay</code>, <code>MME-PRELUDE pack ir_words=2799</code>); <code>MME-CALL-HOLD -> MME-CARRY-SAVE -> MME-CARRY-FIRE -> MME-PACK-REARM -> MME-SA-REARM</code> fires; prelude latch kept across the per-fire channel recycle (<code>MME-LATCH-KEEP</code>); admitted-window chunks forwarded in order | |||
| <code>[live]</code> | |||
|- | |||
| Guest GL submission crossed (late 11-16): offscreen SDL EGL/GBM shim (<code>GZ_EGL</code>) gives GZDoom a real NVIDIA GL context without Xorg/DDX (<code>GL_RENDERER: NVIDIA GeForce RTX 2080 SUPER/PCIe/SSE2</code>, <code>GL_VERSION: 4.6.0 NVIDIA 570.144</code>; no llvmpipe) | |||
| <code>[live]</code> | | <code>[live]</code> | ||
|- | |- | ||
| | | Real GZDoom draw decoded and admitted: 12068 B window at push <code>0x402f9d8</code>, op=4 IMMD CALL to method <code>0x3800</code> (<code>imm=0xd48</code>) plus slots 44/57/58 (<code>0x3960/0x39c8/0x39d0</code>), no <code>0x3910/0x3914</code>; marker recognition, bind-free admission, draw-chunk-first, verbatim chunk replay (<code>3D chunk launch ... draw=1</code>) | ||
| <code>[live]</code> | | <code>[live]</code> | ||
|- | |- | ||
| | | <code>CALL(0)</code> executes without trapping: immediate resolved as an IR address through client SA[0] then golden (<code>MME-CALL-RESOLVE</code>), not-resident calls elided (<code>MME-CALL-UNMAPPED ... reason=not-resident</code>); c1026/c1027 entered the captured macro (<code>macro-status=00000004</code>, mpc 0->4), first DS with real stage data (<code>DS-FAST2 ds_after=83044206 stage=015e0900,015e0a00,015c0400</code>); trap <code>0x80001528</code> decoded as a sticky TRAPPED_ADDR latch, not a cause/PC | ||
| <code>[live]</code> | | <code>[live]</code> | ||
|- | |- | ||
| | | The GL pixel gate, closed 2026-11-18 (<code>b5a68b9a</code>): the first clear/CALL(0)-bearing window is archived and replayed, the engine clear stores red on the guest surface, the readback fence is delivered with the copy (11.03-11.05 s -> 2.3-7.2 ms), and the CE D2H copy's source VA is adopted as the readback surface; two consecutive boots read <code>GL_FRAME nonblack=291840 px0=(255,0,0)</code>, live <code>t/04</code> green; re-verified in r27e/r28d/r29c/r31b | ||
| <code>[live]</code> | | <code>[live]</code> | ||
|- | |- | ||
| | | Per-draw MME macro body capture (research path, not on the pixel critical path): never captured; the synthetic golden body (<code>badf1201</code>) remains the wedge on a non-CALL(0) launch | ||
| <code>[ | | <code>[wip]</code> | ||
|- | |- | ||
| | | GZDoom video via the guest '''software GL''' path (Mesa llvmpipe): four byte-verified files (22 s flight + 18 s orbit, 640x480/1280x960, 30 fps) — a guaranteed-quality deliverable, '''not''' a vGPU rendering claim | ||
| <code>[ | | <code>[live]</code> (software path) | ||
|- | |- | ||
| | | Pack-completion and shallow-boot lotteries gate the deterministic release (throughput limiters) | ||
| <code>[ | | <code>[wip]</code> | ||
|- | |- | ||
| Window/screen present produces non-black window pixels | | Window/screen present produces non-black window pixels | ||
| Line 186: | Line 208: | ||
| <code>[wip]</code> | | <code>[wip]</code> | ||
|- | |- | ||
| Non-black screen pixels from the emulated vGPU's 3D pipeline | | Non-black '''window/screen''' pixels from the emulated vGPU's 3D pipeline | ||
| <code>[wall]</code> | | <code>[wall]</code> | ||
|- | |- | ||
| Line 195: | Line 217: | ||
== 8. What is not claimed == | == 8. What is not claimed == | ||
* No '''window/screen''' pixel has been produced by the emulated vGPU's 3D pipeline yet; every screen capture so far is black. The | * No '''window/screen''' pixel has been produced by the emulated vGPU's 3D pipeline yet; every vGPU screen capture so far is black. What is proven is a '''guest GL readback''': a stock <code>glReadPixels</code> reads a non-black frame (<code>GL_FRAME nonblack=291840 px0=(255,0,0)</code>, two consecutive boots) produced by the physical engine through the emulated vGPU, enforced by the live acceptance lane (<code>EXPECT_GL_PIXELS=closed</code>). The non-black frames and the videos (45.4 s and 50 s) also come from the off-screen pbuffer path (pbuffer -> sysmem -> kvmfr ivshmem -> host reader), not from a windowed X screen capture. | ||
* Display/KMS bring-up (NvKms, <code>/dev/dri</code>, X, a real GL context) is not a rendered-frame claim. GZDoom reaching <code>V_Init: allocate screen</code> proves the client's GL init | * '''The 2026-11-16 GZDoom video is a software-GL deliverable, not a vGPU result.''' It was rendered by Mesa llvmpipe inside the guest (<code>GL_RENDERER: llvmpipe</code>) and captured through the same SDL hook; it exists as a guaranteed-quality demonstration while the GPU-GL pixel path is being worked. It must not be read as the emulated vGPU's 3D pipeline rendering GZDoom. | ||
* Display/KMS bring-up (NvKms, <code>/dev/dri</code>, X, a real GL context) is not a rendered-frame claim. GZDoom reaching <code>V_Init: allocate screen</code> proves the client's GL init, not the game loop or a presented frame. The late-11-16 wave went further — a real NVIDIA GL context without Xorg/DDX, the real op=4 CALL(0) draw admitted and replayed, <code>CALL(0)</code> entering its captured macro without trapping, and a clean DS with real stage data — but the client's per-draw MME macro body was never captured, the surviving wedge is the synthetic golden body, and no surface store or pixel exists yet (<code>wrote=0</code>, no <code>px_nonblack</code>), so the window stays black. | |||
* The real-NVIDIA EGL context is a guest-GL-path result, not a vGPU pixel result: it proves the guest's GL stack now submits through the emulated device, not that the draw's stores reached a render target. | |||
* The engine-zero-write (NOWRITE) campaign is not a rendering result: it and the draw census together proved the submission is macro-driven (no method-grammar draw header exists), that RT routing is not the cause, and that the store wall is macro/front-end execution; they are measurements of the wall, not a 3D-pipeline defect or a pixels claim. | * The engine-zero-write (NOWRITE) campaign is not a rendering result: it and the draw census together proved the submission is macro-driven (no method-grammar draw header exists), that RT routing is not the cause, and that the store wall is macro/front-end execution; they are measurements of the wall, not a 3D-pipeline defect or a pixels claim. | ||
* No frame-rate or latency numbers: the scheduled measurement is defined (60 fps over 60 s, no forcing) but not yet met. | * No frame-rate or latency numbers: the scheduled measurement is defined (60 fps over 60 s, no forcing) but not yet met. | ||
Latest revision as of 03:25, 19 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.
Graphics Execution
Scope. How the emulated vGPU runs 3D graphics work — the OpenGL and Vulkan command streams a stock guest submits — on the physical GPU, and what is proven about it. This is the shared machinery behind
OpenGL.md,Vulkan.mdand the Windows/DirectX target (DirectX.md); CUDA compute uses the same submission and completion path for a different engine workload (Execution-Frontier.md). Canonical sources:../docs/04-implementation/05-graphics-execution-plan.md(the plan and milestone ladder) and../docs/04-implementation/04-real-render-walls.md(the measured walls); the docs tree wins on disagreement.
Status: 2026-11-18, tree master @ 5b23a983. Tags: [live] observed end to end; [wip] partially built; [wall] current blocker; [target] defined success state; [planned] designed, not built.
1. What "real pixels" means
The acceptance target is strict: a stock guest GL or Vulkan application's draw commands are executed by the physical GPU's fixed-function 3D pipeline (vertex fetch, primitive assembly, rasterisation, fragment work, ROP), the render target is readable by the guest, and that image reaches the capture path through the emulated mdev. The pixels must not come from another GPU, a software rasteriser, or a host display round-trip.
2. The path a graphics command takes
guest apps (GL / Vulkan / CUDA) -> guest user space (GLX client + GL core, Vulkan ICD, libcuda) -> guest X server (GLX module + NVIDIA DDX) [OpenGL] -> nvidia.ko: channels, GPFIFO rings, doorbells [all APIs] -> vgsp.ko: capture sections, decode pushes, forward -> physical GPU front-end -> GR engine (3D + compute) / copy engines <- engine-authored releases written into guest memory <- completion relay (MSI-X + wakes) back to the guest ASCII fallback above; the diagram shows the three execution lanes.
3. The three execution lanes
Graphics work reaches the engines today in one of three shapes, in increasing fidelity:
- Verbatim 3D method-stream replay
[live]. The emulation captures the X server's graphics-class (0xC597,TURING_A) section from its channel, relocates the operand addresses into host-built shadow pages the engine can reach, and submits the stream unchanged. The engine retires it: the uploads (LINE_LENGTH_IN/LAUNCH_DMA), the state, program and texture binds, and the release all execute with no MMU fault. This proves the mechanics of 3D execution — object bind, window placement, operand relocation, completion — on real hardware. - Synthesized launch from a captured section
[live]. A compute-shaped launch built from the captured section (operand list, program, a 64-word launch descriptor) reaches the engine and retires realsm_75SASS; the Turing shader-program-header form (V3) is accepted with zero header faults across repeated launches. This proved engine-side dispatch before the verbatim lane existed. The program itself is still a development stand-in at this rung — execution proof, not pixels. - Forwarding the client's own pushes
[wip]. The X DDX channel0x1000014executes its 3D replay (12 launches per cycle), the 2D path is green, and a guest pbufferglClear(red)+glFinish+glReadPixelsprobe returns a real pixel (pixel=ff0000ff): the replay and readback machinery works. The off-screen frame path then produced 500/500 non-black 640x480 animated frames per run and captured videos (45.4 s on 2026-11-11; a 50 s 640x480 h264 capture on 2026-11-12). X and the stock NVIDIA GLX path are fully green (glxinfo -Breturns 0, OpenGL 4.6.0 direct,glxgears~520 FPS), and GZDoom reachesV_Init: allocate screenwith its GL 4.6.0 context whenever the shared nvClipmodeNumis even. The direct-GL ring/VAS anchor and USERD machinery are substantially hardened (verified page-directory discovery, per-rank content scans, eager push pins, client-allocated USERD resolution, foreign-USERD skip, aperture-aware fallback, wrapped-PUT acceptance), and the 11-12/11-13 wave closed the X side of the path: the DDX idle-DMA/ScreenInit wall, the USERD-latch lifetime, the same-pass re-probe thrash, the post-ScreenInit Xorg kernel-mode spin (a display-engine GET-past-PUT on a driver ring wrap) and the flip-event timeout are all fixed, and captured GL sections now execute on the engine (GR LAUNCH submitted/GUEST GR LAUNCH OK) with the data window populated (n_data0 -> 1024). The direct-GL client's submission is now fully decoded: no client push carries a method-grammar draw header — its nine NV906F GPFIFO entries tile one contiguous buffer and its per-frame work is carried as rewritten data-block blobs plus small real state pushes (324/476/728 B, head90110087 80000800) that invoke MME macros (the QMD-carrier hypothesis was tested and refuted: the entry format has no QMD bit, the blob is not a QMD, and no QMD magic exists in the 256 MiB BAR1). Delivery into the lane then landed: a content-gated FB-shadow rescue (e1eac368) and the LOW-band rescue (b7f09616) recover the recycled client pushes, the 324-B draw-state push opens aC597section, is captured and marked for the verbatim 3D lane (the first direct-GL stream3d marks), and with the golden MME overlay satisfying the prelude gate it reaches the engine (GR LAUNCH submitted+ OK, MME-PRELUDE pack 1701 IR words, MME-GOLDEN slot 0 accepted). The MME chain then advanced from the multi-part gate to draw-macro execution: the multi-part keep-window mechanism won multi-frame windows, the part-launch poison was eliminated (the real fault was the client's ownSET_REPORT_SEMAPHORE/SET_NOTIFYwrites to client VAs remapped by the host scratch page-table pool — redirected to a mapped scratch slot; 49 cycles with zero poison and zero MMU faults), the 2799-word pack completes (2799/2799), engine-global completion plus keep-done-across-recycle produced the firstMME-PACK-REARM, the fixed-CB region is aliased, and the released calls run macros through toDRAW_IAB(mac=0x22). Two synthesized-prelude defects were then fixed: the SPH-BIND prelude self-destructed because an auto-dropped run broke its kept/final count (444ae2c1), and the stage block was silently skipped by a double-counted budget; with both fixed the prelude emits 84 words and the DS stage VAs populate (one validated boot carried the full post-REARM chain,mac=0x22andDS 86040624). The DS stage-0/1 image is now authored and live: the module writes a VTG SPH atfamily+0x900(SPH-AUTHOR, first word020a0481), rewrites the window's own later0x2054slot-1 bind to the authored page (SPH-SLOT1-REWRITE), and the DS latch reads the authored image for both vertex slots (DS-IMAGE st0=st1=020a0481 code=ff007321; the DS value fell0x86040626 -> 0x84000420), reproduced on two boots. The release path is now host-deterministic when the pack completes: a saved-window release carrier snapshots the held window atMME-CALL-HOLDand re-submits it with the calls released once the pack is resident (c772:MME-CARRY-SAVE win=240 held=68->MME-CARRY-FIRE mode=release-> syntheticGR LAUNCH push=0x6d6d6500->MME-PACK-REARMgen=5 -> DS0x84000420->MME-CARRY-COMPLETE), and the held-CALL census plus the SA[34] golden fill prove theDRAW_IABcall and its target are present (MME-CALL-TARGET slot=34 method=0x3910 client=0x265 golden=0x265 used=0x265;MME-GOLDEN sa-fill slot=34 entry=0x265). The draw macro now executes end to end. c788 provedDRAW_IAB(mac=0x22) running on the released held window after theMME-DRAW-PLAN/MME-DRAW-MOVEreorder (MME-FAST ... mac=0x22 run=1), and the per-stage SPH disable (TCS off,45dbcdcd) clears the DS latch entirely — the0x84000420was the synthesized TCS bind. The DRAW_IAB body decodes with the public Mesa MME toolchain (mme_tu104_sim): slot 34 (0x265) emits 8 draws of 3 vertices (SET_VERTEX_ARRAY_START0..21,DRAW_VERTEX_ARRAY3). A synthetic full-RT viewport (dab4a02c) and a release chained after any GR launch (3481e62d) complete the replay. The 11-16 wave then proved the host-side chain end to end. The real frame pushes are admitted: the colour-target bind is persisted from an earlier trusted push (RT-PERSIST; the client binds the target once, not per frame), draw markers are accepted inside counted method runs, and the 14.8-thousand-word window is admitted and replayed as 40 chunks with a data-led start snap (WIN-START-SNAP) and a 128-slot candidate ring. The beef draw lane latches a clean DS (DS-FAST2 ... ds_after=80000000, c963) at the live-derived GS attribute map (maps=6), with no SPH18; the draw anchor now moves the call after the first0x3810vertex-stream run and the raster enables are emitted. Capture-less boots get a golden 2799-word MME pack built from the golden library (MME-GOLDEN,MME-PRELUDE), and the chainMME-CALL-HOLD -> MME-CARRY-SAVE -> MME-CARRY-FIRE -> MME-PACK-REARM -> MME-SA-REARMfires; the prelude latch survives the per-fire channel recycle (MME-LATCH-KEEP) and every admitted-window chunk is forwarded in order. The late-11-16 wave crossed the guest submission gap. An offscreen SDL EGL/GBM shim (GZ_EGL) gives the guest a real NVIDIA GL context without Xorg/DDX (GL_RENDERER: NVIDIA GeForce RTX 2080 SUPER/PCIe/SSE2,GL_VERSION: 4.6.0 NVIDIA 570.144— no llvmpipe). The real GZDoom draw window then surfaced: 12068 B at push0x402f9d8(3017 words), carrying no0x3910/0x3914write. Its draw is an IMMD (op 4) CALL to method0x3800(imm=0xd48= 3400) plus CALL slots 44/57/58 (0x3960,0x39c8,0x39d0), 7x0x1b00inline uploads, and state words. The window carries no colour-target bind of its own, so RT-gated admission had refused it (it retired through the compute-QMD lane); recognition now covers the real marker (0x3800op=4 withimm>=0x100, plus the three secondaries;0x3910/0x3914kept), admission happens on the real marker even without a bind, the CALL-bearing chunk is forced first, and every chunk is replayed verbatim. c1025 receipts:GL-FLUSH ... admitted=1,DRAW-WRITE ... m=0x3800 op=4 data=0xd48,3D mark admitted (CALL(0) 0x3800 draw marker),3D stream chunked(4 chunks),3D chunk launch ... draw=1,MME-CALL-ARGS slot=0 data=0xd48,MME-EXEC-CALL slot=0. CALL(0) no longer wedges: eng89t resolves the CALL(0) immediate as an IR address through the client SA[0] (then golden) and elides an op=4 CALL(0) whose body is not resident for this launch to a NOP (MME-CALL-UNMAPPED ... reason=not-resident) so the ladder continues. On c1026/c1027 the real draw's CALL(0) entered its captured macro (macro-status=00000004,mpc0->4) without trapping, and c1027 produced the first DS with real stage data (DS-FAST2 ds_after=83044206 stage=015e0900,015e0a00,015c0400). The trap code0x80001528is decoded as the stickyNV_PGRAPH_TRAPPED_ADDRlatch (bit31 INVALID, subch 0, method0x1528=SET_SHADER_EXCEPTIONS), not a cause/PC; the surviving wedge is the synthetic golden macro body (badf1201 pc=513 mac=0xf1) on a non-CALL(0) launch. Remaining gap (precise): the client's per-draw MME macro body was never captured — the 59580-byte prelude carries only the 12 setup macros (573 code words, pc 0..0x98), the draw push has no0x114/0x11c, and0xd48is a macro length/argument, not an IR entry. The engine has the real draw method stream but not the body to execute. Next: capture the per-draw0x114upload (every beef push plus the X/2D channel) or implement/verify the MME64 body, install it before the draw launch, then checkDS-FAST2 ds_after=8[01],GUEST-WIT va=0x15d,wrote>0,px0!=0. No vGPU surface store or pixel is proven yet (wrote=0, nopx_nonblack). The software-GL GZDoom video (four files, 22 s flight + 18 s orbit, 640x480/1280x960, 30 fps, byte-verified) remains the guaranteed-quality deliverable and is not a vGPU rendering claim; the pack-completion and X-start lotteries still gate run rate.
4. The channel and object picture
- Every submission lives on a channel: a GPFIFO ring plus engine objects, with a USERD the driver advances its put pointer in and a doorbell the host module traps. Channels are typed by engine: a graphics channel carries 3D state and draws; copy-class channels carry memory movements.
- The graphics object class the guest's 3D stream binds is the Turing graphics class,
0xC597. Streams now come from both the X server's channel and the direct GL client's own channels (0xbeef0100GR plus the0xbeef0101/0xbeef0102CE siblings); the 2D present/readback work rides lighter 2D-class and copy-engine shapes. - Display and modeset
[live]. The guest's modeset path is served by an emulated display engine: the display push-buffer channels (core0xc57d, window0xc57e, immediate/window0xc57b) are registered, their push buffers parsed, and the notifier/UPDATEcompletion authored. The arm is class-aware (the window class has no NOTIFY bit; a bound notifier is the arm), and the X DDX's0x8000 -> 0notification completion is authored. This is what lets nvidia-modeset/NvKms register (/dev/dri), X settle and GLX clients obtain a real GL context. The display-capability seam is parameterised in the campaign configuration. - Cells of state: 3D streams are long—hundreds of method words per draw — and mix state binds (viewport, render target, ZS, blend/ROP), program and constant binds, vertex/index streams and draw-issuing methods. The capture machinery recognises the init-shaped operands today; the per-draw state vocabulary is being extended ([G-B in the plan]( ../docs/04-implementation/05-graphics-execution-plan.md)).
- Synchronisation: tracking semaphores, notifications and fence values written by the engine; the guest's swap/present waits sit on top of those.
5. Completion, fences and presents
The acceptance signal is the engine-authored release: a semaphore the engine writes when the work completes. For GL, completion flows through the channel's semaphores/notifications to the X server and the app's swap wait; for Vulkan, the client's fence value is released; for CUDA, the launch's release group wakes the client. The emulation relays engine completions into guest-observable memory (MSI-X plus a poller), and the guest resumes from there.
For the display path, completion is the notifier write and UPDATE -> FINISHED; a completion event deferred by the reply path is force-retried until it posts, so the X server's mode set finishes. For the X DDX's own 2D push buffers, completion also requires the GPU-written engine get word to advance and the notifier to be recycled to 0xffff after a kick; both are host-side levers now, and a diagnostic write of the get word released the DDX's reserve loop. For a windowed GL client the present is a kick; the GSP event-IRQ fix now sets the RISC-V SWGEN0 IRQSTAT/IRQMASK/IRQDEST and latches the CPU-tree leaf, so the guest services the event and glxgears completes swaps, and the GR backend no longer times out (the pair-close/pair-safe replay fixes are default ON; draws retire in 3-2400 ms). The stock GLX path is fully green (glxinfo -B returns 0 with OpenGL 4.6.0 direct rendering; glxgears renders ~520 FPS; the Xorg channel-idle WAIT count is zero), the DDX 3D replay renders and reads back a pbuffer pixel (pixel=ff0000ff), the off-screen frame path produced non-black animated frames and captured videos (45.4 s and 50 s), the RM write-lock holder (Xorg in the DDX vidheap scrub wait) is fixed (df6e71bb), the X DDX/ScreenInit stability walls are closed, and the direct-GL ring/USERD machinery is hardened. The MME pack completes and the draw macro runs, and the authored DS stage image is live for both vertex slots; the released replay executes the DRAW_IAB (mac=0x22) with a synthetic viewport, and the 11-16 wave proved the whole host chain deterministic (admission of the real pushes, clean DS, golden pack, CALL hold, carry fire, SA re-arm). The late-11-16 wave then crossed the guest submission gap: a real NVIDIA EGL context without Xorg/DDX, the real GZDoom op=4 CALL(0) 0x3800 draw admitted and replayed, CALL(0) entering its captured macro without trapping, and the first DS with real stage data. The GL pixel gate closed on 2026-11-18 (b5a68b9a): a stock guest glReadPixels now reads a non-black frame produced by the physical engine through the emulated vGPU (GL_FRAME nonblack=291840 px0=(255,0,0), two consecutive boots; live t/04 green, EXPECT_GL_PIXELS=closed). The remaining public wall is the window/screen present (glxgears/X), X start speed and the boot lottery.
During bring-up the module also carries a diagnostics-only mirror for apps that spin on a shared progress word; it exists so a run can proceed while the natural completion path is being finished. The 60-fps milestone explicitly requires it switched off, along with any external poke.
6. Where the frontier is (ranked walls)
Closed - the GL pixel gate (2026-11-18). The long per-draw-MME-macro investigation ended without that body being needed. The host archives the first accepted window that carries the client clear (0x19d0) or the direct-GL CALL(0) marker and replays it when a later window of the same channel carries neither (f2a4f1be, sema_gl_win_keep; receipt GL-WIN-SELECT keep ... clear=0 call0=1 win=369 alias_gen=1); the engine clear then stores red on the guest surface (OUT-UNCH ... guest=ff0000ff, GUEST-WIT retire ... changed); the CE D2H readback follows the copy's source VA rather than the X-screen guess (b5a68b9a, RB-SURF adopt), with a generation-pinned snapshot (439c52c9) and the low-aperture fence delivered with the copy (7fa7528e, 439c52c9; the driver's measured ~11 s wait fell to 2.3-7.2 ms in the winning boots). Two consecutive boots read GL_FRAME nonblack=291840 px0=(255,0,0); the live acceptance lane is green (t/04, EXPECT_GL_PIXELS=closed); the gate was re-verified in r27e/r28d/r29c/r31b; the proof frame is r23j-artifact/{frame.raw,ppm,png,mp4}. The per-draw macro body remains a research path ([wip]), not a pixel blocker. The boot lottery (an engine store after the guest's read, or no store at all) survives as a hardening item.
- Window/screen present
[wall]. The pbuffer and off-screen frame paths are proven (pixel=ff0000ff, 500/500 non-black frames, captured videos), but a windowed present does not land: glxgears' window is black, the DDX shared-surfacegpuRefCount/lastKickoffRefCountpoll (W1) must be satisfied through a verified surface VA, and a synchronous window draw wedges X. - X screen-init and stability
[wip](was[wall]). The idle-DMA/ ScreenInit class, the USERD-latch lifetime, the same-pass re-probe thrash, the post-ScreenInit Xorg kernel-mode spin (display-engine GET-past-PUT on a driver ring wrap) and the flip-event timeout are fixed, and X has stayed green for >10 minutes in a validated window. What remains is a per-boot first-generation lottery that became the dominant throughput limiter for the graphics A/B runs: only an X started immediately after boot passes the DDX DMA init (3/7 windows in one runoff; long dead-start stretches later, with one green first-start boot, c382), later DMA instances can still fail, and the shared nvClipmodeNummust be even for the GL client's state init (an odd value is guest userspace X-driver state, cleared by one X restart — not a host bug). Wrapped PUTs and the kick-idle marker/GET publication are handled; a guest kernel panic after a wedge is recovered by an offline filesystem check. - Non-black window frames and sustained rate
[wall]/[target]. Once the draw stores, the window/screen present and X screen-init land, the capture must show motion in a window, then 60 fps in one VM with no forcing, then two VMs on two mediated devices with non-black frames in both.
7. What is proven today
| Capability | State |
|---|---|
| X server initialises on the emulated vGPU (driver DMA sanity push, ScreenInit) | [live]
|
Display engine serves the modeset push buffers; notifier plus UPDATE -> FINISHED
|
[live] (campaign configuration)
|
nvidia-modeset/NvKms registers (/dev/dri/card0, renderD128, fb0); nvidia-smi -L enumerates
|
[live]
|
glxinfo reports the emulated GPU with the NVIDIA renderer (OpenGL 4.6.0, direct rendering)
|
[live]
|
X green on attempt 1 in three consecutive cycles (ebf3130f); X + stock GLX fully green on the current stack (glxinfo -B rc 0, OpenGL 4.6.0 direct, glxgears ~520 FPS, Xorg WAIT 0)
|
[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=5-7)
|
[live]
|
GR backend timeouts fixed (backend_timeout=0; draws retire in 3-2400 ms)
|
[live]
|
DDX 3D replay executes (section captured + GR LAUNCH on 0x1000014, 12 launches/cycle)
|
[live]
|
First real GPU readback: pbuffer glClear(red)+glReadPixels -> pixel=ff0000ff
|
[live]
|
First non-black GPU-rendered frames: 500/500 off-screen 640x480 frames per run; 45.4 s video (r1769) and a 50 s capture (2026-11-12)
|
[live]
|
Direct-GL GR ring 0xbeef0100 resolves; releases advance; ring/VAS anchor hardened (verified page-directory discovery, eager push pins, per-rank scans)
|
[live]
|
Client-allocated USERD resolved from the channel's memory objects (hUserdMemory/userdOffset); foreign-USERD adoption skipped; aperture-aware wire fallback
|
[live]
|
Guest adapter init with the all-sysmem instance configuration (RMInstLoc) — the BAR2-verify trap
|
[live]
|
X DDX idle-DMA/ScreenInit, USERD-latch lifetime, re-probe thrash, Xorg kernel-mode spin (GET-past-PUT) and flip-event walls closed; X green for >10 minutes (13a0c5d6, acb51d53, 6ebc7cd4, 770d6b4a, b9213c57, 29690635)
|
[live]
|
Captured GL sections execute on the engine (GR LAUNCH submitted / GUEST GR LAUNCH OK); data window populated (n_data 0 -> 1024)
|
[live]
|
Client push bodies decode as real GR method streams above 10 GiB through the VAS walk (live-PA bound raised to the registered guest-RAM top, 436cbf9d; lookalike gate 7d27df77)
|
[live]
|
| Direct-GL submission fully decoded: nine NV906F entries tile one contiguous buffer; no method-grammar draw header in any push; per-frame work is data-block blobs + real state pushes (324/476/728 B) invoking MME macros; QMD-carrier hypothesis refuted | [live]
|
Recycled direct-GL pushes recovered (content-gated FB-shadow rescue e1eac368, LOW-band rescue b7f09616); client draw-state push opens a C597 section, captures and is marked for the verbatim 3D lane
|
[live]
|
Direct-GL state push reaches the engine with the golden MME overlay (GR LAUNCH submitted + OK; MME-PRELUDE pack 1701 IR words; MME-GOLDEN slot 0 accepted)
|
[live]
|
CODESRC fault-park class prevented: suspect program page relocated to the engine-mapped window-0 shadow (17c7ed7c; validated boot 31 relocations, 51 GR launches, 79 GP_GET advances, 0 FAULT_PDE, 0 WEDGE-REARM, backend_ok=35)
|
[live]
|
RT routing tested and refuted as the store cause: RT0 bind verified 16x with correct target/geometry, still 61/61 wrote=0
|
[live] (negative result)
|
GZDoom passes V_Init: allocate screen with GL 4.6.0 when shared nvClip modeNum is even
|
[live]
|
RM write-lock holder identified (Xorg in the DDX vidheap scrub wait) and fixed (df6e71bb)
|
[live]
|
GL section capture: the X channel's 0xC597 stream decoded
|
[live]
|
| Verbatim 3D method-stream replay retired by the engine (no MMU fault) | [live]
|
Synthesized launch executes real sm_75 SASS; Turing V3 program header accepted
|
[live]
|
| Emulated FB/GART sizing traps fixed (FB info replies in KB; GART default 256 MiB), removing the 4 GiB guest-allocation class | [live]
|
| Multi-part MME keep-window: multi-frame windows admitted; the 2799-word pack completes (2799/2799) | [live]
|
Part-launch poison eliminated: client SET_REPORT_SEMAPHORE/SET_NOTIFY targets redirected to a mapped scratch slot (49 cycles, 0 poison, 0 MMU faults)
|
[live]
|
First MME-PACK-REARM captured (engine-global completion plus keep-done-across-recycle); fixed-CB region aliased; released calls run macros
|
[live]
|
DRAW_IAB (mac=0x22) executes on the released held window after the MME-DRAW-PLAN/MME-DRAW-MOVE reorder (c788: MME-FAST ... mac=0x22 run=1); the body decodes with the public Mesa MME toolchain (mme_tu104_sim: slot 34, 8 draws of 3 vertices)
|
[live]
|
DS stage-0/1 image: a VTG SPH is authored at family+0x900 and the window's own slot-1 bind rewritten to it; the DS latch reads st0=st1=020a0481
|
[live]
|
Saved-window release carrier (held window snapshotted at MME-CALL-HOLD and re-submitted with calls released once the pack is resident, c772); held-CALL census + SA[34] golden fill (client=golden=used=0x265); synthetic full-RT viewport (dab4a02c); release chained after any GR launch (3481e62d)
|
[live]
|
Per-stage SPH disable (TCS off, 45dbcdcd) clears the DS latch (the 0x84000420 was the synthesized TCS bind)
|
[live]
|
Real frame pushes admitted: persisted colour-target bind from an earlier trusted push (RT-PERSIST), draw markers accepted inside counted method runs, 14.8-thousand-word window admitted and replayed as 40 chunks (3D stream chunked ... -> 40 chunk(s)), data-led start snap (WIN-START-SNAP), 128-slot candidate ring
|
[live]
|
Clean DS on the beef draw lane after the full-window chunking (DS-FAST2 ... ds_after=80000000, c963) at the live-derived GS attribute map (maps=6), no SPH18; draw anchor after the first 0x3810 and raster enables emitted
|
[live]
|
Golden 2799-word MME pack on capture-less boots (MME-GOLDEN overlay, MME-PRELUDE pack ir_words=2799); MME-CALL-HOLD -> MME-CARRY-SAVE -> MME-CARRY-FIRE -> MME-PACK-REARM -> MME-SA-REARM fires; prelude latch kept across the per-fire channel recycle (MME-LATCH-KEEP); admitted-window chunks forwarded in order
|
[live]
|
Guest GL submission crossed (late 11-16): offscreen SDL EGL/GBM shim (GZ_EGL) gives GZDoom a real NVIDIA GL context without Xorg/DDX (GL_RENDERER: NVIDIA GeForce RTX 2080 SUPER/PCIe/SSE2, GL_VERSION: 4.6.0 NVIDIA 570.144; no llvmpipe)
|
[live]
|
Real GZDoom draw decoded and admitted: 12068 B window at push 0x402f9d8, op=4 IMMD CALL to method 0x3800 (imm=0xd48) plus slots 44/57/58 (0x3960/0x39c8/0x39d0), no 0x3910/0x3914; marker recognition, bind-free admission, draw-chunk-first, verbatim chunk replay (3D chunk launch ... draw=1)
|
[live]
|
CALL(0) executes without trapping: immediate resolved as an IR address through client SA[0] then golden (MME-CALL-RESOLVE), not-resident calls elided (MME-CALL-UNMAPPED ... reason=not-resident); c1026/c1027 entered the captured macro (macro-status=00000004, mpc 0->4), first DS with real stage data (DS-FAST2 ds_after=83044206 stage=015e0900,015e0a00,015c0400); trap 0x80001528 decoded as a sticky TRAPPED_ADDR latch, not a cause/PC
|
[live]
|
The GL pixel gate, closed 2026-11-18 (b5a68b9a): the first clear/CALL(0)-bearing window is archived and replayed, the engine clear stores red on the guest surface, the readback fence is delivered with the copy (11.03-11.05 s -> 2.3-7.2 ms), and the CE D2H copy's source VA is adopted as the readback surface; two consecutive boots read GL_FRAME nonblack=291840 px0=(255,0,0), live t/04 green; re-verified in r27e/r28d/r29c/r31b
|
[live]
|
Per-draw MME macro body capture (research path, not on the pixel critical path): never captured; the synthetic golden body (badf1201) remains the wedge on a non-CALL(0) launch
|
[wip]
|
| GZDoom video via the guest software GL path (Mesa llvmpipe): four byte-verified files (22 s flight + 18 s orbit, 640x480/1280x960, 30 fps) — a guaranteed-quality deliverable, not a vGPU rendering claim | [live] (software path)
|
| Pack-completion and shallow-boot lotteries gate the deterministic release (throughput limiters) | [wip]
|
| Window/screen present produces non-black window pixels | [wall]
|
X screen-init first-generation lottery (modeNum parity; only an immediately-post-boot X passes DDX DMA init; dominant throughput limiter)
|
[wip]
|
| Non-black window/screen pixels from the emulated vGPU's 3D pipeline | [wall]
|
| Windows/DirectX guests | [planned]
|
8. What is not claimed
- No window/screen pixel has been produced by the emulated vGPU's 3D pipeline yet; every vGPU screen capture so far is black. What is proven is a guest GL readback: a stock
glReadPixelsreads a non-black frame (GL_FRAME nonblack=291840 px0=(255,0,0), two consecutive boots) produced by the physical engine through the emulated vGPU, enforced by the live acceptance lane (EXPECT_GL_PIXELS=closed). The non-black frames and the videos (45.4 s and 50 s) also come from the off-screen pbuffer path (pbuffer -> sysmem -> kvmfr ivshmem -> host reader), not from a windowed X screen capture. - The 2026-11-16 GZDoom video is a software-GL deliverable, not a vGPU result. It was rendered by Mesa llvmpipe inside the guest (
GL_RENDERER: llvmpipe) and captured through the same SDL hook; it exists as a guaranteed-quality demonstration while the GPU-GL pixel path is being worked. It must not be read as the emulated vGPU's 3D pipeline rendering GZDoom. - Display/KMS bring-up (NvKms,
/dev/dri, X, a real GL context) is not a rendered-frame claim. GZDoom reachingV_Init: allocate screenproves the client's GL init, not the game loop or a presented frame. The late-11-16 wave went further — a real NVIDIA GL context without Xorg/DDX, the real op=4 CALL(0) draw admitted and replayed,CALL(0)entering its captured macro without trapping, and a clean DS with real stage data — but the client's per-draw MME macro body was never captured, the surviving wedge is the synthetic golden body, and no surface store or pixel exists yet (wrote=0, nopx_nonblack), so the window stays black. - The real-NVIDIA EGL context is a guest-GL-path result, not a vGPU pixel result: it proves the guest's GL stack now submits through the emulated device, not that the draw's stores reached a render target.
- The engine-zero-write (NOWRITE) campaign is not a rendering result: it and the draw census together proved the submission is macro-driven (no method-grammar draw header exists), that RT routing is not the cause, and that the store wall is macro/front-end execution; they are measurements of the wall, not a 3D-pipeline defect or a pixels claim.
- No frame-rate or latency numbers: the scheduled measurement is defined (60 fps over 60 s, no forcing) but not yet met.
9. Related pages
OpenGL.md— the guest OpenGL path and its status.Vulkan.md— the guest Vulkan path and its status.DirectX.md— Windows guests and the DirectX target.Execution-Frontier.md— the CUDA compute chain, proven end to end.Physical-GPU-Backend.md— the backend the work is forwarded to.Introduction-to-GMMU.md— channels, GPFIFO, engines, and page tables.Host-Module.md— where capture, decode and forwarding live.../docs/04-implementation/05-graphics-execution-plan.md— the canonical plan: gap list, three approaches, and the M-GL1..M-GL6 milestone ladder with gates.