From fade84f8b5b781d29daad40699d07928dedea550 Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Wed, 23 Sep 2026 13:48:07 -0400 Subject: docs: merge the legacy flat documents, add the CUDA deep-dive and link checks * Merge and remove the pre-reboot flat documents, preserving their still-useful material in the structured tree: debugging workflows and the EPT-livelock case study (05-operations/02), performance microbenchmarks and A/B methodology (05-operations/01), the version-upgrade runbook (05-operations/02 section 4, with corrected host/guest framing), kernel-code pitfalls (07-developers) and the OpenRM build/load order (03-architecture/06 section 7). The remaining legacy files were verified redundant and removed. * docs/README now records where each migrated topic lives. * Portability: the config YAML files are called out as design targets that no code reads yet, with what adding support actually requires today. * Getting started: the OpenRM step is marked optional (native vGPU-management workflows only; the emulated path uses the distro driver). * tools docs: rmtool/rmtop marked as planned, pointing at the implemented tools/rmq subset. * wiki: new CUDA-Userspace-Driver deep-dive page (public-safe, links the canonical userspace/cuda analysis) and index update. * scripts/check-docs-links.py plus a CI step so relative links cannot rot. * STATE.md references to removed documents repointed. --- docs/07-developers/onboarding-and-standards.md | 38 ++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'docs/07-developers') diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md index 3d7ac78..b3ac1c5 100644 --- a/docs/07-developers/onboarding-and-standards.md +++ b/docs/07-developers/onboarding-and-standards.md @@ -85,6 +85,41 @@ open-iov/ interface only. * Error paths: fail closed, log once with context, and give up the device cleanly. +* **Guard every allocation** (`kmalloc`/`vzalloc`/`kzalloc`) and propagate + `-ENOMEM` with clean unwinding (`goto err_...` in reverse init order). + +The following rules each come from a real bug and are enforced in review: + +* **Never `virt_to_phys()` on vmalloc/ioremap memory.** Use + `is_vmalloc_addr() ? vmalloc_to_pfn() : virt_to_phys() >> PAGE_SHIFT` + (see `nv_vgpu_mmap_virt_to_pfn`). A bad PFN in a VFIO mmap puts a garbage + PFN in the guest's EPT and wedges the guest in an EPT-violation livelock — + case study in + [`../05-operations/02-debugging-and-maintenance-workflows.md`](../05-operations/02-debugging-and-maintenance-workflows.md) §5.3. +* **`dma_addr_t` for every DMA address.** Never truncate it into `int`/`u32`: + IOMMU IOVAs can exceed 32 bits. +* **Every `get` needs a `put`**: `pci_dev_get`/`pci_dev_put`, + `eventfd_ctx_fdget`/`eventfd_ctx_put`, `vfio_alloc_device`/`vfio_put_device`, + module references. Unbalanced gets become leaks that block unload. +* **Remove paths must fully unwind init paths** (including `list_del` and + kthread stop); a remove that forgets one leaves the module unloadable. +* **Fail fast in emulation mode**: never `gsp_rpc_submit_raw()` from the + emulation path — it writes into the same mailbox and rings the same + doorbell our own thread polls, a self-triggered RPC livelock. Return + `-ENOTSUPP` with `pr_warn_ratelimited` until a real handler exists. +* **Log through the NULL-tolerant `nv_vgpu_*` wrappers and rate-limit** + anything a guest can spam. +* `open-iov-vfio.ko` is **standalone**: no `MODULE_SOFTDEP`/dependency on + `nvidia` — `nvidia.ko` imports our symbols, not the other way around. +* VM access in tooling goes through `scripts/vgpu_vm.py`; do not invoke + ``/QEMU directly. +* Scripts never reboot or otherwise change system state without explicit + operator action (project hard rule). +* Do not widen an API's hardware assumptions silently: if a function needs + `vgpu->pdev` (or similar), say so in the comment — unit tests cannot call + those paths. +* The guest is stock: **no Open-IOV code in the guest, ever** — no guest + agent, no driver patch, no extra kernel parameters. ### 3.2 Userspace and tools (`userspace/`, `tools/`, `scripts/`) @@ -98,6 +133,9 @@ open-iov/ * Every behaviour change updates the doc that describes it. Docs are part of the definition of done. +* Debugging discoveries go into the failure taxonomy in + [`../05-operations/02-debugging-and-maintenance-workflows.md`](../05-operations/02-debugging-and-maintenance-workflows.md) + so the next person does not rediscover them. * Prefer a table or a decision tree over prose for anything an operator will follow under pressure. * Protocol facts (IDs, offsets, structures) must cite their source (a live -- cgit v1.2.3