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.

1 files changed, 32 insertions, 0 deletions

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