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. --- .../06-host-module-and-hybrid-model.md | 24 +++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) (limited to 'docs/03-architecture/06-host-module-and-hybrid-model.md') diff --git a/docs/03-architecture/06-host-module-and-hybrid-model.md b/docs/03-architecture/06-host-module-and-hybrid-model.md index 4f9efdb..5849071 100644 --- a/docs/03-architecture/06-host-module-and-hybrid-model.md +++ b/docs/03-architecture/06-host-module-and-hybrid-model.md @@ -237,7 +237,29 @@ mismatch. Their workflows are documented in * On typical single-GPU developer systems the distribution's NVIDIA driver manages the physical GPU and the Open-IOV module is used standalone; the OpenRM submodule path is only needed for the native-vGPU-management - workflows. + workflows (RM callbacks) and is unnecessary for the QEMU/emulated path. + +**Build and load order on the OpenRM path:** + +```bash +# 1. Kernel module first - generates kernel/Module.symvers. +make kernel # or: ./scripts/stack_manager.sh build-kernel + +# 2. OpenRM modules with our symbols resolved. +./scripts/build_nvidia_openrm.sh # wraps KBUILD_EXTRA_SYMBOLS=/kernel/Module.symvers +grep -i vgpu kernel/Module.symvers # symbols exported +modinfo .../kernel-open/nvidia.ko | grep -i vgpu # symbols consumed + +# 3. Load order: Open-IOV first (exports and registers the mdev parent), +# then the optional OpenRM modules, then firmware. +``` + +If a distribution driver already owns the physical GPU, skip step 2 and the +OpenRM part of step 3: the emulated QEMU path runs with the distribution +driver. Common failures on this path: `Unknown symbol nvidia_vgpu_vfio_*` +(`KBUILD_EXTRA_SYMBOLS` missing or wrong) and symbols present in +`Module.symvers` but absent from `nvidia.ko` (stale build cache — `make clean` +in `kernel-open` first). ## 8. What is implemented vs. designed -- cgit v1.2.3