diff options
Diffstat (limited to 'docs/07-developers')
| -rw-r--r-- | docs/07-developers/onboarding-and-standards.md | 38 |
1 files changed, 38 insertions, 0 deletions
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 |