Difference between revisions of "The Host Module (vgsp.ko)"

From Open-IOV
Jump to navigation Jump to search
m (2026-11-15 evening refresh (HEAD 6aeb20c7): release path host-deterministic (c772), slot-34/SA[34] settled (0x265), reorder landed; blocker is call order; eng64 chains the release behind the pack carrier; DS 0x84000420/stores remain)
m (2026-11-20 late status refresh: corrected beef-lane diagnosis (PBDMA fetch proven; host-side forensic spin/no-write retire was the floor); r73 beef election + r75 shadow-VTG; v1.0.0-rc1 retracted; latest acceptance red on known flake/race)
 
(7 intermediate revisions by the same user not shown)
Line 5: Line 5:
<blockquote>'''Scope.''' The host-side kernel module that presents one virtual Turing-class GPU per <code>mdev</code> instance: the virtual device, the emulation engine, the guest-memory model and the work-forwarding design. Canonical source: [https://git.vgpu.io/open-iov.git/tree/docs/03-architecture/06-host-module-and-hybrid-model.md <code>../docs/03-architecture/06-host-module-and-hybrid-model.md</code>]; the docs tree wins on disagreement with this page.</blockquote>
<blockquote>'''Scope.''' The host-side kernel module that presents one virtual Turing-class GPU per <code>mdev</code> instance: the virtual device, the emulation engine, the guest-memory model and the work-forwarding design. Canonical source: [https://git.vgpu.io/open-iov.git/tree/docs/03-architecture/06-host-module-and-hybrid-model.md <code>../docs/03-architecture/06-host-module-and-hybrid-model.md</code>]; the docs tree wins on disagreement with this page.</blockquote>


<blockquote>Status: 2026-11-15, tree <code>master @ 6aeb20c7</code>. Tags: <code>[live]</code> observed with the stock guest driver; <code>[wip]</code> demonstrated live, being productized; <code>[gated]</code> implemented default-off behind supervised gates; <code>[wall]</code> known blocking limit; <code>[target]</code> designed, not built; <code>[planned]</code> roadmap.</blockquote>
<blockquote>Status: 2026-11-20, tree <code>master @ 3f34d58a</code>. Tags: <code>[live]</code> observed with the stock guest driver; <code>[wip]</code> demonstrated live, being productized; <code>[gated]</code> implemented default-off behind supervised gates; <code>[wall]</code> known blocking limit; <code>[target]</code> designed, not built; <code>[planned]</code> roadmap.</blockquote>


== 1. Role and position ==
== 1. Role and position ==
Line 79: Line 79:
Proxying through the distribution host driver has '''no callable entry point from kernel context''', so the module '''owns the device and runs its real GSP firmware as the resource-manager server''', with emulation as the control plane. CE copies, release and fault relay are implemented default-off and verified live [gated]; forwarded guest CUDA launches execute on the engine with engine-authored completions relayed to the guest; the guest's real GL draws now forward and execute on the physical GR engine (<code>work_gr backend_ok=5-7</code>, <code>backend_timeout=0</code>), the DDX 3D replay reads back a real pixel, and graphics method streams execute in three shapes, including the direct GL client's own GR/CE channels ([[The Execution Frontier|<code>Execution-Frontier.md</code>]], [[Graphics Execution|<code>Graphics-Execution.md</code>]]).
Proxying through the distribution host driver has '''no callable entry point from kernel context''', so the module '''owns the device and runs its real GSP firmware as the resource-manager server''', with emulation as the control plane. CE copies, release and fault relay are implemented default-off and verified live [gated]; forwarded guest CUDA launches execute on the engine with engine-authored completions relayed to the guest; the guest's real GL draws now forward and execute on the physical GR engine (<code>work_gr backend_ok=5-7</code>, <code>backend_timeout=0</code>), the DDX 3D replay reads back a real pixel, and graphics method streams execute in three shapes, including the direct GL client's own GR/CE channels ([[The Execution Frontier|<code>Execution-Frontier.md</code>]], [[Graphics Execution|<code>Graphics-Execution.md</code>]]).


The same plane carries the display/modeset path [live in the campaign configuration]: the module serves the guest display engine's push-buffer channels (core <code>0xc57d</code>, window <code>0xc57e</code>, immediate/window <code>0xc57b</code>), authors the notifier/<code>UPDATE</code> completion with a class-aware arm (the window class has no NOTIFY bit; a bound notifier is the arm) and a force-retry for a deferred event, completes the X DDX's <code>0x8000 -&gt; 0</code> notifications, and lets nvidia-modeset/NvKms register (<code>/dev/dri</code>), X settle and GLX clients obtain a real GL context. The display-capability seam is parameterised. For the DDX's own 2D push buffers the remaining host levers are publishing/advancing the GPU-written engine get word and recycling the notifier to <code>0xffff</code> after completion. The DDX 3D replay renders and reads back a pbuffer pixel (<code>pixel=ff0000ff</code>), the off-screen frame path produced 500/500 non-black animated frames per run 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>), X and the stock GLX path are fully green (<code>glxinfo -B</code> rc 0, ~520 FPS <code>glxgears</code>), the X DDX/ScreenInit stability walls are closed (X green &gt;10 minutes), and the direct-GL ring/VAS and USERD machinery is hardened (verified page-directory discovery, eager push pins, client-allocated USERD resolution, foreign-USERD skip). The direct-GL submission is fully decoded (macro-driven; no classic draw header), the recycled pushes are recovered by the content-gated FB-shadow and LOW-band rescues, and the client's draw-state push opens, captures and reaches the engine with the golden MME overlay. The MME chain now completes and executes the draw macro: multi-frame keep-windows land, the 2799-word pack completes, the first <code>MME-PACK-REARM</code> fires, the fixed-CB region is aliased, and <code>DRAW_IAB</code> (<code>mac=0x22</code>) runs with the SPH-BIND prelude intact and the DS stage VAs populated. The DS stage-0/1 image is now authored and live: a VTG SPH at <code>family+0x900</code> (<code>SPH-AUTHOR</code>, first word <code>020a0481</code>) is fetched by both vertex slots, with the window's own slot-1 bind rewritten to it (<code>SPH-SLOT1-REWRITE</code>; DS <code>0x86040626 -&gt; 0x84000420</code>, two boots). The release path is now host-deterministic when the pack completes: the saved-window release carrier snapshots the held window and re-submits it with the calls released once the pack is resident (c772), and the held-CALL census plus the SA[34] golden fill prove the slot-34 <code>DRAW_IAB</code> target (<code>client=golden=used=0x265</code>). The remaining GL gap is call order (the 728-B window places slot-34 after the <code>0x33/0x39</code> setup, so the DS latch pre-empts it; the 324-B window places it first and ran <code>mac=0x22</code>), the reorder <code>a03a68ea</code> (landed, unexercised), the pack-completion lottery, the DS stage type/context bits (SPH5/SPH10/SPH18), the stores, and the window/screen present path, which currently stays black or wedges X.
The same plane carries the display/modeset path [live in the campaign configuration]: the module serves the guest display engine's push-buffer channels (core <code>0xc57d</code>, window <code>0xc57e</code>, immediate/window <code>0xc57b</code>), authors the notifier/<code>UPDATE</code> completion with a class-aware arm (the window class has no NOTIFY bit; a bound notifier is the arm) and a force-retry for a deferred event, completes the X DDX's <code>0x8000 -&gt; 0</code> notifications, and lets nvidia-modeset/NvKms register (<code>/dev/dri</code>), X settle and GLX clients obtain a real GL context. The display-capability seam is parameterised. For the DDX's own 2D push buffers the remaining host levers are publishing/advancing the GPU-written engine get word and recycling the notifier to <code>0xffff</code> after completion. The DDX 3D replay renders and reads back a pbuffer pixel (<code>pixel=ff0000ff</code>), the off-screen frame path produced 500/500 non-black animated frames per run 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>), X and the stock GLX path bring up on a good boot (<code>glxinfo -B</code> returns OpenGL 4.6.0 direct rendering; the current direct-GL stack measures 0.255 FPS in <code>glxgears</code>, r64-r72, not the older ~520 FPS figure), the X DDX/ScreenInit stability walls are closed (X green &gt;10 minutes), and the direct-GL ring/VAS and USERD machinery is hardened (verified page-directory discovery, eager push pins, client-allocated USERD resolution, foreign-USERD skip). The direct-GL submission is fully decoded (macro-driven; no classic draw header), the recycled pushes are recovered by the content-gated FB-shadow and LOW-band rescues, and the client's draw-state push opens, captures and reaches the engine with the golden MME overlay. The 11-16 wave then proved the '''host-side draw chain deterministic end to end''': the real frame pushes are admitted (a persisted colour-target bind carried from an earlier trusted push, draw markers accepted inside counted method runs, the 14.8-thousand-word window replayed as 40 chunks, a data-led start snap 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, capture-less boots get a '''golden 2799-word MME pack''' built from the golden library, and <code>MME-CALL-HOLD -&gt; MME-CARRY-SAVE -&gt; MME-CARRY-FIRE -&gt; MME-PACK-REARM -&gt; MME-SA-REARM</code> fires with the prelude latch kept across the per-fire channel recycle (<code>MME-LATCH-KEEP</code>); admitted-window chunks are forwarded in order. At that point the decisive finding was guest-side: across 36 boots (c990-c1019) the client never submitted a non-null <code>CALL(34)</code> draw macro — every <code>0x3910/0x3914</code> hit is an interior method write with <code>data=0x0</code>, no CALL header exists in the admitted windows, and those cycles logged guest EGL/dri2 failures and OOM kills. The '''late-11-16 wave crossed the guest submission gap''': an offscreen EGL/GBM shim gives GZDoom a real NVIDIA GL context without Xorg/DDX, the real op=4 <code>CALL(0)</code> <code>0x3800</code> draw is admitted and replayed, <code>CALL(0)</code> executes its captured macro without trapping (the immediate resolves through client SA[0] then golden; not-resident calls are elided), and the first DS with real stage data is reached. The '''GL pixel gate then closed on 2026-11-18''' (<code>b5a68b9a</code>) without the per-draw MME macro body: the first clear/CALL(0)-bearing window is archived and replayed, the engine clear stores red on the guest surface, and the CE readback follows the copy's source VA with a generation-pinned snapshot (two consecutive boots <code>GL_FRAME nonblack=291840</code>; live <code>t/04</code> was green on that proof, red on the readback pin/copy race in the latest full run). The current wall is the X/GLX frame rate (0.255 FPS): r72b proved the PBDMA fetch and the engine release, the floor was the debug-only forensic MME spin plus the host no-write retirement wait, r73's beef election cuts the retire wait, and r75 (<code>3f34d58a</code>) mirrors the VTG program image into the win0 shadow; the draw still stores 0 pages and faults <code>Illegal Instruction Encoding</code>. A GZDoom video was separately delivered through the guest's '''software GL''' path (Mesa llvmpipe) as a guaranteed-quality deliverable; it is not a vGPU rendering claim.


== 6. Debug parameters ==
== 6. Debug parameters ==

Latest revision as of 20:42, 20 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.

The Host Module (vgsp.ko)

Scope. The host-side kernel module that presents one virtual Turing-class GPU per mdev instance: the virtual device, the emulation engine, the guest-memory model and the work-forwarding design. Canonical source: ../docs/03-architecture/06-host-module-and-hybrid-model.md; the docs tree wins on disagreement with this page.

Status: 2026-11-20, tree master @ 3f34d58a. Tags: [live] observed with the stock guest driver; [wip] demonstrated live, being productized; [gated] implemented default-off behind supervised gates; [wall] known blocking limit; [target] designed, not built; [planned] roadmap.

1. Role and position

guest VM ── PCIe MMIO / DMA / MSI-X through the hypervisor
   (KVM/QEMU or Xen: VFIO mdev transport, IOMMU)
   │
vgsp.ko: virtual device · emulation core · memory model · work path
   │
physical GPU + GSP firmware, driven by this module (host driver unmodified)

The module registers as an mdev parent on the physical GPU, exposing one device type per supported profile; each mdev is an independent virtual GPU (System-Overview.md, Execution-Plane.md).

2. The virtual device

The guest sees a plausible Turing-class GPU (IDs, class code, BARs, capability list). Some fields exist only for validation: PCIe link capabilities (the hypervisor can rewrite them), MSI-X masking state, and non-SR-IOV VF windows.

BAR Size Backing Contents
BAR0 16 MB host vzalloc shadow boot, doorbells, VF registers, PRAMIN window, VBIOS
BAR1 256 MB host vzalloc vidmem buffer guest-visible VRAM aperture
BAR3 — instance window instance/PRAMIN behaviour

MMIO is served by VFIO region callbacks or directly from the shadow when mapped into the guest. BAR1 is host RAM today — correctness first: the real GPU cannot read it, so forwarding must later migrate objects to real VRAM or expose DMA-mapped system memory [target] (Physical-GPU-Backend.md).

3. The emulation core

A kernel thread drives the device's "firmware" behaviour [live]:

BAR0 doorbell / VF-register write → read msgq element from guest memory
   → dispatch RPC → write reply → inject MSI-X (eventfd → irqfd)

Guest memory is reached via vfio_dma_rw() from kernel-thread context. The RPC philosophy: correct shape first (or the driver walks off into uninitialized memory), plausible values second (values must be self-consistent), never invent input (in/out parameter blocks are echoed; zeroing the GSP_RM_ALLOC reply once faulted libcuda). Handlers cover boot/static-info exchanges, device/FB/BUS/INTR tables, CE and GMMU queries, reserved-PDE contracts, channel/CE allocation and an unknown-control fallback. Push buffers are decoded as method streams and executed in software — memsets, copies, semaphore releases — a correctness bridge, not the data plane [wip]; emulation-mode CUDA is verified end to end (vectorAdd over 1M elements, bad=0) [live]. Physical-GSP boot is default-off [gated]; the firmware analyzer, version tables, HAL tables and dynamic RPC dispatcher are not yet on the live path [target].

4. The guest-memory model

What the client gives us: channel memory descriptors (NV_MEMORY_DESC_PARAMS) with physical addresses (instance memory, method buffer, userd, ramfc, error notifiers) and the page-table contract for server-owned VA ranges (COPY_SERVER_RESERVED_PDES — table-level PAs, page shifts, VA range, empty leaves). It gives us none of its own sysmem maps.

What we derive instead [live] — the module rebuilds the missing mappings from the guest's own bookkeeping, with no cooperation from the guest driver:

  1. VA↔PA pairs live in guest memory: UVM and RM record both the GPU VA and the kernel CPU VA per object (uvm_rm_mem_t.vas[CPU]/vas[GPU] +0x30/+0x38).
  2. CPU VAs are direct-map addresses: PA = cpu_va - page_offset_base, the base recovered from guest memory or /proc/kallsyms during development.
  3. Exception: control-device mmap() pages have no leaf PTEs; verified pairs arrive via sema_map_add until a durable join exists. The page-granular cache is fed by a trusted GMMU walk (Introduction-to-GMMU.md).

Load-bearing copy invariants: (1) a copy runs at most once per GPFIFO entry — replays are suppressed by entry-word identity plus an executed-operation bitmap; (2) a virtual operand translates per 4 KB page (195 of 256 pages were contiguous in one observed 1 MB range); (3) a consumed slot's work never runs later — the per-put-epoch mark is authoritative until a put wrap.

5. The forwarding path (design)

guest push submitted
   → detect (doorbell / GPPUT / push-buffer scan), decode the method stream
   → EMULATE state/notification (release, membar, fence) or
     FORWARD real engine work (GR launch, CE copy, memop)
   → FORWARD: submit equivalent work on a real channel bound to the physical GPU
   → relay completions (semaphore / fault / interrupt) back into guest memory

Proxying through the distribution host driver has no callable entry point from kernel context, so the module owns the device and runs its real GSP firmware as the resource-manager server, with emulation as the control plane. CE copies, release and fault relay are implemented default-off and verified live [gated]; forwarded guest CUDA launches execute on the engine with engine-authored completions relayed to the guest; the guest's real GL draws now forward and execute on the physical GR engine (work_gr backend_ok=5-7, backend_timeout=0), the DDX 3D replay reads back a real pixel, and graphics method streams execute in three shapes, including the direct GL client's own GR/CE channels (Execution-Frontier.md, Graphics-Execution.md).

The same plane carries the display/modeset path [live in the campaign configuration]: the module serves the guest display engine's push-buffer channels (core 0xc57d, window 0xc57e, immediate/window 0xc57b), authors the notifier/UPDATE completion with a class-aware arm (the window class has no NOTIFY bit; a bound notifier is the arm) and a force-retry for a deferred event, completes the X DDX's 0x8000 -> 0 notifications, and lets nvidia-modeset/NvKms register (/dev/dri), X settle and GLX clients obtain a real GL context. The display-capability seam is parameterised. For the DDX's own 2D push buffers the remaining host levers are publishing/advancing the GPU-written engine get word and recycling the notifier to 0xffff after completion. The DDX 3D replay renders and reads back a pbuffer pixel (pixel=ff0000ff), the off-screen frame path produced 500/500 non-black animated frames per run and captured videos (45.4 s and 50 s), the RM write-lock holder (Xorg in the DDX vidheap scrub wait) is fixed (df6e71bb), X and the stock GLX path bring up on a good boot (glxinfo -B returns OpenGL 4.6.0 direct rendering; the current direct-GL stack measures 0.255 FPS in glxgears, r64-r72, not the older ~520 FPS figure), the X DDX/ScreenInit stability walls are closed (X green >10 minutes), and the direct-GL ring/VAS and USERD machinery is hardened (verified page-directory discovery, eager push pins, client-allocated USERD resolution, foreign-USERD skip). The direct-GL submission is fully decoded (macro-driven; no classic draw header), the recycled pushes are recovered by the content-gated FB-shadow and LOW-band rescues, and the client's draw-state push opens, captures and reaches the engine with the golden MME overlay. The 11-16 wave then proved the host-side draw chain deterministic end to end: the real frame pushes are admitted (a persisted colour-target bind carried from an earlier trusted push, draw markers accepted inside counted method runs, the 14.8-thousand-word window replayed as 40 chunks, a data-led 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, capture-less boots get a golden 2799-word MME pack built from the golden library, and MME-CALL-HOLD -> MME-CARRY-SAVE -> MME-CARRY-FIRE -> MME-PACK-REARM -> MME-SA-REARM fires with the prelude latch kept across the per-fire channel recycle (MME-LATCH-KEEP); admitted-window chunks are forwarded in order. At that point the decisive finding was guest-side: across 36 boots (c990-c1019) the client never submitted a non-null CALL(34) draw macro — every 0x3910/0x3914 hit is an interior method write with data=0x0, no CALL header exists in the admitted windows, and those cycles logged guest EGL/dri2 failures and OOM kills. The late-11-16 wave crossed the guest submission gap: an offscreen EGL/GBM shim gives GZDoom a real NVIDIA GL context without Xorg/DDX, the real op=4 CALL(0) 0x3800 draw is admitted and replayed, CALL(0) executes its captured macro without trapping (the immediate resolves through client SA[0] then golden; not-resident calls are elided), and the first DS with real stage data is reached. The GL pixel gate then closed on 2026-11-18 (b5a68b9a) without the per-draw MME macro body: the first clear/CALL(0)-bearing window is archived and replayed, the engine clear stores red on the guest surface, and the CE readback follows the copy's source VA with a generation-pinned snapshot (two consecutive boots GL_FRAME nonblack=291840; live t/04 was green on that proof, red on the readback pin/copy race in the latest full run). The current wall is the X/GLX frame rate (0.255 FPS): r72b proved the PBDMA fetch and the engine release, the floor was the debug-only forensic MME spin plus the host no-write retirement wait, r73's beef election cuts the retire wait, and r75 (3f34d58a) mirrors the VTG program image into the win0 shadow; the draw still stores 0 pages and faults Illegal Instruction Encoding. A GZDoom video was separately delivered through the guest's software GL path (Mesa llvmpipe) as a guaranteed-quality deliverable; it is not a vGPU rendering claim.

6. Debug parameters

/sys/module/vgsp/parameters/* makes guest memory and the emulated device inspectable without rebuilding:

Parameter Purpose
scan_guest_ram=<v> / scan_vidmem=<v> find a 64-bit value in guest RAM (0–8 GB) or the VRAM shadow
scan_seq=<v1,...> / scan_pt=<pa> / scan_masked=<v>,<mask> find a 32-bit sequence, entries pointing at a PA, or (x & mask) == v
dump_vidmem=<off>,<len> / fill_vidmem=<v> dump/scan or fill the VRAM shadow
poke_guest=<gpa>,<v> / poke_fill=<gpa>,<v>,<n> write a 32-bit value / fill a range in guest physical memory
sema_probe=<gpu_va>[,count] / sema_map_add=<va>,<pa> probe a semaphore VA / teach one verified VA→PA pair
dump_guest=<gpa>,<len> dump guest physical memory (capped)

The physical-backend path adds a default-off set of backend controls (documented in the repository; workflows in ../docs/05-operations/02-debugging-and-maintenance-workflows.md).

7. Build and symbol contracts

  • vgsp.ko exports the nvidia_vgpu_vfio_* interface (probe/remove, ops get/set, mdev parent registration) to pair the device with OpenRM host modules.
  • OpenRM modules built from source need KBUILD_EXTRA_SYMBOLS=$(pwd)/kernel/Module.symvers and must build after this module (missing symbols and stale build caches are common otherwise).
  • On single-GPU developer systems the distribution driver owns the physical GPU and the module runs standalone; the OpenRM path is only for native-vGPU management, not QEMU.

8. Implemented vs designed

Area Status
mdev/VFIO device, config space, BARs, MSI-X; BAR0 state machine; boot handshake [live] implemented
Message queues + RPC + init controls (stock 570.144) [live] implemented
Guest sysmem access + VA↔PA discovery [wip] debug-grade, to be productized
Push decoding + semaphore completion [wip] demonstrated live, being productized
Emulation-mode CUDA end-to-end [live] repeatable 1M-element vectorAdd, bad=0
Guest-RAM physical path + server-owned page-table population [gated] default-off; GPA→HPA via shared-file page cache verified live on the CE
GPU work forwarding: CE copy, release and fault relay [gated] default-off, verified live; GR execution live for forwarded CUDA launches
Execution backend (module-owned GPU, direct real-GSP session) [live] boot, static configuration, CE copies and GR execution proven; failed mutating attempts park the device in a locked fail-safe, never auto-retried
Real VRAM backing [target]; Windows, Xen, aarch64 [planned] designed, not implemented

9. Related documentation