diff options
Diffstat (limited to 'docs/05-operations/02-debugging-and-maintenance-workflows.md')
| -rw-r--r-- | docs/05-operations/02-debugging-and-maintenance-workflows.md | 32 |
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 |