From 6260daa1eb66094e86a1d02128b97708242074e8 Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Thu, 12 Nov 2026 09:26:28 -0500 Subject: docs: vGPU bring-up size/state traps (FB units, GART, modeNum parity) Record the three independent guest-visible values that broke stock-driver bring-up: FB info kilobyte-vs-byte units (1024x framebuffer over-report), multi-GiB GPU GART allocation, and odd shared nvClip modeNum (clears the GL client's init bits so buffer maps fail). Each has a different diagnostic signature; the note separates allocation-size, userspace mapping-gate, and host VAS-translation failures. Evidence: c15-c26 bring-up, commits 8c7bf295/d1dc85a2/91aa8d91 and handoff-meta-plan.md CONT.435-CONT.441. --- .../02-debugging-and-maintenance-workflows.md | 32 ++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/05-operations/02-debugging-and-maintenance-workflows.md b/docs/05-operations/02-debugging-and-maintenance-workflows.md index cb3ea28..972e9b6 100644 --- a/docs/05-operations/02-debugging-and-maintenance-workflows.md +++ b/docs/05-operations/02-debugging-and-maintenance-workflows.md @@ -422,6 +422,38 @@ anything that is not lowmem; the module rule is recorded in and the shadow mapping is described in [`../03-architecture/06-host-module-and-hybrid-model.md`](../03-architecture/06-host-module-and-hybrid-model.md). +### 5.4 Case study: vGPU guest bring-up — three size/state traps + +Three independent values can make a stock guest driver fail long before the +GPU work starts. They are worth checking in this order. + +1. **FB info size units.** The framebuffer-info ABI documents the RAM, + total/usable/heap, mappable-heap, BAR1 and BAR1-avail size indices in + **kilobytes**; compression and L2-cache sizes are in bytes. Returning + bytes for the kilobyte indices over-reports the emulated framebuffer by + 1024x, which the X driver turns into a huge surface allocation. The + fix is a per-index unit conversion, not a clamp. +2. **GPU GART size.** A multi-gigabyte GART reply makes the guest RM + allocate that much system memory for the GART at GL init. On a 12 GiB + guest a 4 GiB GART is a fatal allocation: it appears as a + `nv_alloc_pages` burst with a page count in the hundreds of thousands. + The emulated GART should be small (hundreds of MiB at most), matched to + the guest RAM budget. +3. **Shared nvClip mode-number parity.** The first X server start after a + guest boot can leave the shared `screens[0].modeNum` odd. The GL client + reads bit 0 as "mode switch in progress" and clears its init bits, so + every buffer allocation/map fails (typically `GL_OUT_OF_MEMORY`) and a + client that trusts a non-NULL map pointer crashes later. A second X + start normally leaves the value even and the same client proceeds. + Treat this as a guest X-driver state issue; do not chase it as a host + VAS/page-table problem. + +Diagnosis pattern: separate *allocation size* problems (values in the +hundreds of MiB/GiB, no host channel activity) from *buffer mapping* +problems (GL errors with no ioctl traffic, i.e. a userspace init gate) from +*host translation* problems (ring/USERD walks failing with `rc=-2`). The +three have different fixes and should not be conflated. + ## 6. Release engineering * Versions are tagged; each tag carries the rung/matrix table and the -- cgit v1.2.3