diff options
Diffstat (limited to 'docs')
20 files changed, 62 insertions, 62 deletions
diff --git a/docs/02-getting-started/01-install-and-first-run.md b/docs/02-getting-started/01-install-and-first-run.md index 9ae81c2..7bc12bc 100644 --- a/docs/02-getting-started/01-install-and-first-run.md +++ b/docs/02-getting-started/01-install-and-first-run.md @@ -55,7 +55,7 @@ make userspace ``` **Build-order matters.** The NVIDIA modules resolve symbols that -`open-iov-vfio.ko` exports; building them in the wrong order produces +`vgsp.ko` exports; building them in the wrong order produces `Unknown symbol` failures at load time. See [`../03-architecture/06-host-module-and-hybrid-model.md`](../03-architecture/06-host-module-and-hybrid-model.md). @@ -69,7 +69,7 @@ make userspace ``` **The `nvidia` (OpenRM) stage is optional.** It is needed only when the host -must run NVIDIA's OpenRM modules built against the symbols `open-iov-vfio.ko` +must run NVIDIA's OpenRM modules built against the symbols `vgsp.ko` exports — that is, the native vGPU-management/RM-callback workflows. The QEMU/emulated path uses the distribution driver that already manages the physical GPU; `load-stack` skips the OpenRM submodule when a distribution @@ -167,7 +167,7 @@ by hand while a VM holds the mdev. ## 8. Watching the emulation work Every meaningful decision the emulation makes is visible in `dmesg` with the -prefix **`gsp-resman-vfio:`** (module logs) and the per-RPC traces. Handy: +prefix **`vgsp:`** (module logs) and the per-RPC traces. Handy: ```bash sudo dmesg -w | grep -iE 'gsp-resman-vfio|gsp_|rpc' # live @@ -181,7 +181,7 @@ Developer debug knobs (module parameters) are documented in | Symptom | Start here | |---|---| -| Module will not load | `dmesg`, `modinfo open-iov-vfio.ko`, stale module state → `cleanup-crash` | +| Module will not load | `dmesg`, `modinfo vgsp.ko`, stale module state → `cleanup-crash` | | No mdev type for your GPU | [hardware matrix](../06-portability/hardware-software-matrix.md) | | Guest sees wrong PCIe link speed/width | root-port attachment + config-space mirror (debugging doc) | | `nvidia.ko` probe fails in guest | guest dmesg + `lspci -vvv` + [driver lifecycle field guide](../03-architecture/07-driver-lifecycle-field-guide.md) | @@ -192,7 +192,7 @@ Developer debug knobs (module parameters) are documented in ```bash ./scripts/stack_manager.sh unload -sudo rmmod open_iov_vfio nvidia nvidia_modeset nvidia_uvm # if present +sudo rmmod vgsp nvidia nvidia_modeset nvidia_uvm # if present ``` The project never modifies your host driver's files; removing the Open-IOV diff --git a/docs/03-architecture/01-system-overview.md b/docs/03-architecture/01-system-overview.md index fa328ae..8205154 100644 --- a/docs/03-architecture/01-system-overview.md +++ b/docs/03-architecture/01-system-overview.md @@ -56,7 +56,7 @@ GUEST ════════╪════════════════════════════════════════════════════════════════ HYPERVISOR (KVM/Xen/...) VFIO mdev transport + IOMMU isolation │ -HOST MODULE open-iov-vfio.ko +HOST MODULE vgsp.ko ├─ virtual device: config space, BAR0/BAR1/BAR3 windows, MSI-X ├─ emulation core: GSP boot + GSP-RM (RPC msgq, controls, objects, events) ├─ memory model: guest RAM access, VA↔PA maps, VRAM backing @@ -71,7 +71,7 @@ REAL HARDWARE (engines, memory, interrupts) ## 3. Host module architecture -`open-iov-vfio.ko` is a **VFIO mediated-device (mdev) driver**. It registers a +`vgsp.ko` is a **VFIO mediated-device (mdev) driver**. It registers a parent on the physical GPU and exposes virtual GPU types; each `mdev` instance is one virtual GPU for one VM. 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 0dbc89a..7f670d7 100644 --- a/docs/03-architecture/06-host-module-and-hybrid-model.md +++ b/docs/03-architecture/06-host-module-and-hybrid-model.md @@ -1,6 +1,6 @@ # The Host Module and the Hybrid Model -> `open-iov-vfio.ko` in detail: the virtual device, the emulation engine, the +> `vgsp.ko` in detail: the virtual device, the emulation engine, the > memory model, and how work will be forwarded. This is the "where the code > lives" document. @@ -15,7 +15,7 @@ └────┬──────────────────────────────────────────────┘ │ ┌────┴───────────────────────────────────────────────────────────────┐ - │ open-iov-vfio.ko │ + │ vgsp.ko │ │ virtual device ── emulation core ── memory model ── work path │ └────┬─────────────────────────────────────┬─────────────────────────┘ │ module-owned device + real GSP │ (future) vendor-managed @@ -249,7 +249,7 @@ operations stays a development bridge, not the data plane. ## 6. Debug tooling in the module The module exposes debug parameters (writes to -`/sys/module/open_iov_vfio/parameters/*`) that make the guest's memory and the +`/sys/module/vgsp/parameters/*`) that make the guest's memory and the emulated device inspectable without rebuilding: | Parameter | Purpose | @@ -290,7 +290,7 @@ mismatch. Their workflows are documented in ## 7. Build and symbol contracts -* `open-iov-vfio.ko` exports the `nvidia_vgpu_vfio_*` interface +* `vgsp.ko` exports the `nvidia_vgpu_vfio_*` interface (`nvidia_vgpu_vfio_probe/remove`, ops get/set, mdev parent registration) for hosts that want to pair our device with the NVIDIA OpenRM host modules. * When NVIDIA's OpenRM modules are built from source, they must be built with diff --git a/docs/03-architecture/07-driver-lifecycle-field-guide.md b/docs/03-architecture/07-driver-lifecycle-field-guide.md index 73b007e..3a85da6 100644 --- a/docs/03-architecture/07-driver-lifecycle-field-guide.md +++ b/docs/03-architecture/07-driver-lifecycle-field-guide.md @@ -45,7 +45,7 @@ terminate. **Log signature:** ``` -gsp-resman-vfio: GSP-BOOT: ... trigger auto-cleared ... +vgsp: GSP-BOOT: ... trigger auto-cleared ... ``` ## 3. Static configuration @@ -62,7 +62,7 @@ layout, engine list, vGPU-friendly VF values). **Log signature:** ``` -GSPRM: GET_GSP_STATIC_INFO → ... +vgsp-rm: GET_GSP_STATIC_INFO → ... ``` ## 4. Message queues @@ -81,8 +81,8 @@ byte-stream-based**: each message is one element and may span pages. **Log signature:** ``` -gsp-resman-vfio: libos region[i] id8=... pa=... size=... -gsp-resman-vfio: queue args sharedPA=... ptes=... cmdOff=... statOff=... +vgsp: libos region[i] id8=... pa=... size=... +vgsp: queue args sharedPA=... ptes=... cmdOff=... statOff=... ``` ## 5. Resource-manager initialization (the control battery) @@ -113,7 +113,7 @@ fallback). Representative controls: **Log signature:** ``` -GSPRM: GSP_RM_CONTROL cmd=0x... hClient=0x... hObject=0x... paramsSize=... +vgsp-rm: GSP_RM_CONTROL cmd=0x... hClient=0x... hObject=0x... paramsSize=... ``` ## 6. Object creation @@ -150,7 +150,7 @@ tree reconstructible from `dmesg`. **Log signature:** ``` -GSPRM: GSP_RM_ALLOC class=0x... paramsSize=... hClient=... hParent=... hObject=... +vgsp-rm: GSP_RM_ALLOC class=0x... paramsSize=... hClient=... hParent=... hObject=... ``` ## 7. UVM registration (the wall we climbed) diff --git a/docs/03-architecture/08-physical-gpu-integration.md b/docs/03-architecture/08-physical-gpu-integration.md index 532cd77..6e13e7b 100644 --- a/docs/03-architecture/08-physical-gpu-integration.md +++ b/docs/03-architecture/08-physical-gpu-integration.md @@ -367,7 +367,7 @@ per-context scheduling. Tenant policy and fairness are a later layer on top. release the RPC runs once (only when the full boot stage ran) before the existing quiesce/FWSEC teardown; without a full boot the fail-safe behaviour is unchanged. A write-only debugfs trigger - (`open-iov-vfio/gsp-phys-unload-rpc`, write "1") lets a live claimed + (`vgsp/gsp-phys-unload-rpc`, write "1") lets a live claimed session test the shutdown without touching WPR2. All of it is inert unless the full boot stage ran. **Live-verified (2026-10-01):** the unload RPC shuts the server down (GSP-RM processor suspended in ~220 ms, handoff bits @@ -375,7 +375,7 @@ per-context scheduling. Tenant policy and fairness are a later layer on top. reboot on every clean cycle. * **Update (2026-10-01) — rung 4c slice 1 implemented (build-only):** for the next cycle a host resource-manager static-info probe is available: the - write-only debugfs file `open-iov-vfio/gsp-phys-rm-probe` (write "1", only + write-only debugfs file `vgsp/gsp-phys-rm-probe` (write "1", only when GSP-RM init-done was observed) sends `GET_GSP_STATIC_INFO` over the real command queue and decodes the server's static configuration (internal handles, split-VA flag, BAR1/2 PDE bases, framebuffer geometry, engine diff --git a/docs/03-architecture/09-full-system-picture.md b/docs/03-architecture/09-full-system-picture.md index 3c15830..97b4617 100644 --- a/docs/03-architecture/09-full-system-picture.md +++ b/docs/03-architecture/09-full-system-picture.md @@ -38,7 +38,7 @@ flowchart TB IOMMU["IOMMU / IOMMUFD<br/>per-VM DMA address spaces"] end - subgraph MOD["open-iov-vfio.ko - the only host component"] + subgraph MOD["vgsp.ko - the only host component"] VDEV["Virtual device<br/>config space, BAR0/1/3, MSI-X"] EMU["Emulation core<br/>GSP boot + GSP-RM RPC + objects"] MEMM["Memory model<br/>VA to PA, pins, VRAM shadow, page tables"] @@ -207,7 +207,7 @@ flowchart LR VRS["VRAM objects - BAR1 aperture view"] end - subgraph MM["open-iov-vfio.ko memory model"] + subgraph MM["vgsp.ko memory model"] DISC["Discovery<br/>structure walk + content scan + pins"] PMAP["VA to PA map<br/>page-granular, merge rebuilds"] SHAD["BAR1 VRAM shadow"] @@ -362,7 +362,7 @@ flowchart TB T2["VM B - mdev 2"] T3["VM C - mdev N"] end - subgraph MOD["open-iov-vfio.ko"] + subgraph MOD["vgsp.ko"] Q1["Emulation context 1<br/>BARs, queues, counters"] Q2["Emulation context 2"] Q3["Emulation context N"] diff --git a/docs/03-architecture/12-host-vf-acceleration-future-goal.md b/docs/03-architecture/12-host-vf-acceleration-future-goal.md index 298b329..5a331c8 100644 --- a/docs/03-architecture/12-host-vf-acceleration-future-goal.md +++ b/docs/03-architecture/12-host-vf-acceleration-future-goal.md @@ -14,7 +14,7 @@ Give a process **running on the host OS** GPU acceleration through the open-iov device model: bind the host's stock NVIDIA kernel driver to a virtual function -or virtual device presented by `open-iov-vfio.ko`, so that host userspace +or virtual device presented by `vgsp.ko`, so that host userspace (`libcuda`, `nvidia-smi`, CUDA applications) consumes the mediated device the way a guest does, with no VM in between. diff --git a/docs/05-operations/02-debugging-and-maintenance-workflows.md b/docs/05-operations/02-debugging-and-maintenance-workflows.md index b7aab25..cb3ea28 100644 --- a/docs/05-operations/02-debugging-and-maintenance-workflows.md +++ b/docs/05-operations/02-debugging-and-maintenance-workflows.md @@ -12,7 +12,7 @@ Three layers, in order of usefulness: precisely what it expected and what it got (e.g. UVM's "Tracker entry for value N … channel_init()"). Always start here. 2. **Host module trace** — every RPC and every emulation decision is logged - with the `gsp-resman-vfio:` prefix. A full CUDA run produces a few hundred + with the `vgsp:` prefix. A full CUDA run produces a few hundred lines that reconstruct the object tree and the control battery. 3. **Memory observation** — when the problem is in memory state (mappings, semaphores, pushes), the module's debug parameters read and write guest @@ -52,13 +52,13 @@ See the host-module doc for the full list. Canonical examples: ```bash # Find where a value lives in guest RAM (e.g. a semaphore VA): -echo 0x121000000 | sudo tee /sys/module/open_iov_vfio/parameters/scan_guest_ram +echo 0x121000000 | sudo tee /sys/module/vgsp/parameters/scan_guest_ram # Find a decoded method sequence in guest RAM: -echo 0x1,0x21000000,0x1 | sudo tee /sys/module/open_iov_vfio/parameters/scan_seq +echo 0x1,0x21000000,0x1 | sudo tee /sys/module/vgsp/parameters/scan_seq # Write a value to a guest physical address (completing a semaphore release): -echo 0x120299010,0x1 | sudo tee /sys/module/open_iov_vfio/parameters/poke_guest +echo 0x120299010,0x1 | sudo tee /sys/module/vgsp/parameters/poke_guest ``` **Caution:** all guest-RAM operations run in a kernel thread context by design; @@ -282,7 +282,7 @@ addresses into a new configuration — re-derive per firmware. [`../06-portability/hardware-software-matrix.md` §6](../06-portability/hardware-software-matrix.md)). * Add the new entry to the runtime signature database in `kernel/firmware_analyzer.c` (`known_signatures[]`: version string, hashes, - discovered addresses). This is what lets one `open-iov-vfio.ko` identify + discovered addresses). This is what lets one `vgsp.ko` identify multiple firmware versions safely. **5. Validate (same checklist every version).** @@ -380,14 +380,14 @@ ordering; the quickstart and tool chooser are in the | Symptom | Likely cause | First check | |---------|--------------|-------------| -| `insmod open-iov-vfio.ko: Unknown symbol` | missing prerequisite module (`mdev`) | `modprobe mdev vfio vfio_iommu_type1 vfio_pci` | +| `insmod vgsp.ko: Unknown symbol` | missing prerequisite module (`mdev`) | `modprobe mdev vfio vfio_iommu_type1 vfio_pci` | | mdev create `-EUSERS` | `available_instances` = 0 (leak) | `cat .../available_instances` | | Guest: no PCI device | mdev not attached | QEMU command line for `sysfsdev=` | | Guest: sees device, probe hangs instantly | BAR0 mmap PFN bug (fixed) | host `make_spte` WARN | | Guest: probe hangs, no KVM warning | doorbell/RPC never consumed | host dmesg for the emulation thread and doorbell writes | | Guest: RPC processed but driver still waits | MSI-X never delivered | `SET_IRQS wired` line; `irqs[0].trigger` non-NULL | | Guest agent dead, QEMU alive | guest kernel wedge | gdbstub vCPU sampling (§3.7) | -| `rmmod open_iov_vfio` hangs | leaked kthread / open fds | `ps -e \| grep gsp_emu`; mdevs still present? | +| `rmmod vgsp` hangs | leaked kthread / open fds | `ps -e \| grep gsp_emu`; mdevs still present? | | Guest Code 43 / probe fail (Windows) | config space / MSI-X details | config read/write logs | | `pr_warn_ratelimited(... not supported in emulation mode)` | guest used a BAR_TRAP/MIGRATE RPC | expected fail-fast; wire a real handler if hot | diff --git a/docs/05-operations/03-risc-v-gsp-rm-vm.md b/docs/05-operations/03-risc-v-gsp-rm-vm.md index cde0736..a55e3ac 100644 --- a/docs/05-operations/03-risc-v-gsp-rm-vm.md +++ b/docs/05-operations/03-risc-v-gsp-rm-vm.md @@ -29,7 +29,7 @@ its runtime behaviour inspectable with Frida-like primitives: "execute until here" from the decompiler. Its stated purpose is **simulating and inspecting the GSP firmware's runtime -memory for `gsp-rm-vfio` accuracy measurements**: capture how the firmware +memory for `vgsp` accuracy measurements**: capture how the firmware behaves, compare that with the emulation and with the physical backend, and survive GSP version/device/architecture churn with repeatable evidence. diff --git a/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md index c1ecffe..d16da23 100644 --- a/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md +++ b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md @@ -18,7 +18,7 @@ authoritative details live in the tool's own documentation set risc-v-gsp-rm-debugger runs GSP/uproc firmware in a controllable machine, instruments it with Frida-like primitives, records a durable session, changes the machine's inputs (including injected code), and compares runs so that emulation changes -in `open-iov-vfio` land with evidence instead of anecdotes. +in `vgsp` land with evidence instead of anecdotes. | It is | It is not | |---|---| @@ -363,7 +363,7 @@ audited v0.1 surfaces; treat changes to them as reviewed events. gdbstub. * **No guest, no hardware, no product.** Nothing runs in a guest; injected services are prototypes, not shipped code; product changes go through - `open-iov-vfio` with physical confirmation. + `vgsp` with physical confirmation. * **Read by default; writes gated.** MCP `write_mem`/`call_function` need `--allow-write`, injection needs `--allow-inject`, and every write is recorded in the session. diff --git a/docs/06-portability/03-device-validation-and-porting-sequence.md b/docs/06-portability/03-device-validation-and-porting-sequence.md index e4e7be5..2756777 100644 --- a/docs/06-portability/03-device-validation-and-porting-sequence.md +++ b/docs/06-portability/03-device-validation-and-porting-sequence.md @@ -126,7 +126,7 @@ Per driver/firmware version `N`: 5. **Supervised physical cycle** (approved, attended): * boot the guest with the stock driver of version `N` on the device bound to `vfio-pci`; run the CUDA smoke and the ioctl tracer; - * capture host module trace (`gsp-resman-vfio:`), guest dmesg, + * capture host module trace (`vgsp:`), guest dmesg, `nvidia-smi -q`, `lspci -vvv`, and the control/ioctl sequence; * compare the physical captures with the simulator sessions (`./risc-v-gsp-rm-debugger.sh compare`, M1–M6) and resolve every delta as profile, logic or diff --git a/docs/07-developers/02-development-and-analysis-environment.md b/docs/07-developers/02-development-and-analysis-environment.md index f19a4d8..c58ec35 100644 --- a/docs/07-developers/02-development-and-analysis-environment.md +++ b/docs/07-developers/02-development-and-analysis-environment.md @@ -35,7 +35,7 @@ and the tool's own flowchart TB subgraph HOST["Lab host - x86_64 or aarch64"] SM["scripts/stack_manager.sh<br/>build / load / status / test / unload"] - MOD["open-iov-vfio.ko<br/>virtual device + GSP-RM emulation + backend"] + MOD["vgsp.ko<br/>virtual device + GSP-RM emulation + backend"] QEMU["QEMU / KVM<br/>scripts/vgpu_vm.py, launch_qemu_*.sh"] VFIO["VFIO mdev + IOMMU isolation"] RMTOOLS["tools/rmtool, rmtop, rmq<br/>read-only host RM oracle"] @@ -83,14 +83,14 @@ flowchart TB ## 3. Host stack: KVM, QEMU, VFIO and the module -The reference path is KVM + QEMU with the VFIO mdev transport. `open-iov-vfio.ko` +The reference path is KVM + QEMU with the VFIO mdev transport. `vgsp.ko` emulates the device interface and GSP-RM behaviour (or drives the physical backend, per the chosen execution mode); the guest runs stock drivers only. ```bash ./install.sh deps nvidia firmware build # full host setup (stages selectable) make kernel # or: ./scripts/stack_manager.sh build-kernel -./scripts/stack_manager.sh load-open-iov # load open-iov-vfio.ko +./scripts/stack_manager.sh load-open-iov # load vgsp.ko ./scripts/stack_manager.sh mdev-create # create the mediated device ./scripts/vgpu_vm.py start vgpu-linux # guest lifecycle + guest-agent exec/shell ./scripts/stack_manager.sh test # host test suite @@ -246,7 +246,7 @@ the long-term program is | `stack_manager.sh` | build/load/status/test/unload with correct ordering | every host-stack change or bring-up | `scripts/stack_manager.sh` | [`03-architecture/06` §7](../03-architecture/06-host-module-and-hybrid-model.md) | | `vgpu_vm.py` | VM lifecycle + guest-agent exec/shell | booting/inspecting the guest | `scripts/vgpu_vm.py` | [`05-operations/02`](../05-operations/02-debugging-and-maintenance-workflows.md) | | QEMU launch/gdb helpers | direct QEMU launches, QMP/gdbstub access | gdbstub triage, direct QEMU runs | `scripts/launch_qemu_*.sh`, `qemu_*.sh/py` | [`05-operations/02` §3.3/§3.7](../05-operations/02-debugging-and-maintenance-workflows.md) | -| module debug parameters | guest-RAM scan/poke, live trace | memory-state debugging in kernel context | `/sys/module/open_iov_vfio/parameters/` | [`05-operations/02` §3.1–3.2](../05-operations/02-debugging-and-maintenance-workflows.md) | +| module debug parameters | guest-RAM scan/poke, live trace | memory-state debugging in kernel context | `/sys/module/vgsp/parameters/` | [`05-operations/02` §3.1–3.2](../05-operations/02-debugging-and-maintenance-workflows.md) | | `guest-diag` | ioctl trace, engine list, pmap | driver-side oracle for a guest failure | `tools/guest-diag/` | [`05-operations/02` §3.4](../05-operations/02-debugging-and-maintenance-workflows.md) | | `cudatool.py` | CUDA binary info/delta/crash/fdematch | every `libcuda` version bump or crash | `userspace/cuda/tools/` | [`READ-ME-FIRST` §3](../../userspace/cuda/READ-ME-FIRST.md) | | `callwalk.py` | caller/callee/path walks | tracing a crash path through the corpus | `userspace/cuda/tools/` | [`READ-ME-FIRST` §3](../../userspace/cuda/READ-ME-FIRST.md) | @@ -287,7 +287,7 @@ flowchart LR end A2 -->|"symbol DB with bias<br/>(symbols export)"| B1 B3 -->|"export_hits, fault PC,<br/>corpus bucket:line"| A1 - A3 --> C["emulation change in open-iov-vfio"] + A3 --> C["emulation change in vgsp"] B3 --> C C --> D["physical confirmation +<br/>regression with the same stimulus"] ``` diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md index 50f4f93..ef6388e 100644 --- a/docs/07-developers/onboarding-and-standards.md +++ b/docs/07-developers/onboarding-and-standards.md @@ -109,7 +109,7 @@ The following rules each come from a real bug and are enforced in review: `-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 +* `vgsp.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. @@ -158,7 +158,7 @@ The following rules each come from a real bug and are enforced in review: | `tools/firmware_analyzer.py` + Ghidra scripts | firmware analysis pipeline | | module debug parameters | guest-memory scanning/poking, VRAM inspection; physical-backend parameters and debugfs state/control files (see [`../eng-ops.md`](../eng-ops.md) Part II) | | QEMU gdbstub workflow | guest virtual-memory inspection/writing | -| `debug/risc-v-gsp-rm-vm/` (risc-v-gsp-rm-debugger) | implemented, documented and tested ([audit](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); [value demos](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)) — RISC-V GSP/uproc VM runtime inspection, session recording and `gsp-rm-vfio` accuracy measurement (see [`../05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md)) | +| `debug/risc-v-gsp-rm-vm/` (risc-v-gsp-rm-debugger) | implemented, documented and tested ([audit](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); [value demos](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)) — RISC-V GSP/uproc VM runtime inspection, session recording and `vgsp` accuracy measurement (see [`../05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md)) | | `wiki/` documents | protocol and firmware deep dives | ## 5. Landing a change @@ -177,7 +177,7 @@ The following rules each come from a real bug and are enforced in review: ## 6. Makefile targets ```bash -make kernel # open-iov-vfio.ko (first!) +make kernel # vgsp.ko (first!) ./scripts/build_nvidia_openrm.sh # optional OpenRM modules, KBUILD_EXTRA_SYMBOLS from kernel/Module.symvers make userspace # libiov.so, examples make all # in the correct order diff --git a/docs/09-reference/legal-and-licensing.md b/docs/09-reference/legal-and-licensing.md index 87d8002..1d82735 100644 --- a/docs/09-reference/legal-and-licensing.md +++ b/docs/09-reference/legal-and-licensing.md @@ -11,7 +11,7 @@ | Component | License | Rationale | |---|---|---| -| `kernel/**` (e.g. `open-iov-vfio.ko`) | **GPL-2.0** (`MODULE_LICENSE("GPL v2")`) | The Linux kernel exports the interfaces we need (VFIO, mdev, IOMMU, DMA) under `EXPORT_SYMBOL_GPL`. GPL-2.0 is the legally correct choice. | +| `kernel/**` (e.g. `vgsp.ko`) | **GPL-2.0** (`MODULE_LICENSE("GPL v2")`) | The Linux kernel exports the interfaces we need (VFIO, mdev, IOMMU, DMA) under `EXPORT_SYMBOL_GPL`. GPL-2.0 is the legally correct choice. | | `userspace/**`, `tools/**`, `scripts/**`, `config/**`, `docs/**` | **BSD-3-Clause** | Maximizes reuse and adoption — the project's mission. | | Third-party submodules and imported trees | their own licenses | Not relicensed; used under their terms. | diff --git a/docs/10-post-1.0/experimental-host-acceleration.md b/docs/10-post-1.0/experimental-host-acceleration.md index 38b9774..2095a49 100644 --- a/docs/10-post-1.0/experimental-host-acceleration.md +++ b/docs/10-post-1.0/experimental-host-acceleration.md @@ -93,7 +93,7 @@ document may be started. itself* use the GPU at full capability — host desktop (X11/Wayland) on the physical outputs (HDMI/DP), host CUDA/3D through the real stock driver, and guests running concurrently in compartments, with scheduling and -compartmentalization enforced by `open-iov-vfio.ko`. +compartmentalization enforced by `vgsp.ko`. This stretch goal is explicitly **one**: it is attempted only after every baseline goal is met, and it must not jeopardize them. @@ -107,7 +107,7 @@ baseline goal is met, and it must not jeopardize them. | S1 | The host's real, stock `nvidia.ko` provides host CUDA/3D and the host desktop | | S2 | Full display output from the GPU's HDMI/DP, driving the host desktop | | S3 | Guest frame buffers are shown on the host (Looking Glass / KVMFR / IVSHMEM), both sides accelerated | -| S4 | Host and guest work coexist on one GPU under `open-iov-vfio.ko` scheduling and compartmentalization | +| S4 | Host and guest work coexist on one GPU under `vgsp.ko` scheduling and compartmentalization | | S5 | High performance: work-dominated workloads within a few percent of native; launch-bound latency bounded and published | | S6 | No unnecessary memory copies; zero-copy workload path | | S7 | Isolation: a guest can never reach host memory or host interrupts; fail closed | diff --git a/docs/README.md b/docs/README.md index 0873387..05ee0d6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -42,7 +42,7 @@ flowchart TB subgraph HYP["Hypervisor - KVM and QEMU"] D["VFIO mdev transport + IOMMU isolation"] end - subgraph MOD["open-iov-vfio.ko - the only host component"] + subgraph MOD["vgsp.ko - the only host component"] E["Virtual device - BARs, config space, MSI-X"] F["GSP boot + GSP-RM emulation"] G["Memory model + work path"] @@ -226,7 +226,7 @@ The pre-reboot flat documents have been merged into this tree and removed and risc-v-gsp-rm-debugger user guide; additive only. --> * firmware runtime analysis (experimental): running GSP/uproc firmware in a - RISC-V QEMU VM with hooks, watchpoints, memory dumps and `gsp-rm-vfio` + RISC-V QEMU VM with hooks, watchpoints, memory dumps and `vgsp` accuracy measurement — implemented, documented and tested ([audit](../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); [value demos](../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)) → [`05-operations/03-risc-v-gsp-rm-vm.md`](05-operations/03-risc-v-gsp-rm-vm.md) (tooling in [`../debug/risc-v-gsp-rm-vm/`](../debug/risc-v-gsp-rm-vm/README.md)) diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md index c0dd3c8..c0d80d9 100644 --- a/docs/RUNBOOK.md +++ b/docs/RUNBOOK.md @@ -28,7 +28,7 @@ Rules for reading under pressure: 1. Find the symptom in §5 (scenario catalogue) or §9 (one-page decision tree). 2. Follow the **response order** exactly; do not skip the pairing/hash check. -3. Before any action that could change `open-iov-vfio`, complete the evidence +3. Before any action that could change `vgsp`, complete the evidence bundle (§6) and pass the escalation gates (§7). 4. Record the outcome where the scenario says to record it — a finding without a record is lost work. @@ -164,7 +164,7 @@ actor, and it does not justify shortcuts. | **Decide** | 7 | Fill the M1–M6 skeleton with the reference-capture method; list unexplained deltas | Metric table and open list attached | | | 8 | Choose: no change, version-keyed handler, profile data, or fidelity gap | Decision names the evidence that drove it | | | 9 | If the decision changes emulation behaviour, require physical reproduction; if it touches RM 610, stop at the gate | Gate passed or work parked | -| **Act** | 10 | Implement in `open-iov-vfio` with the evidence bundle linked; never in the simulator | PR carries the bundle and the metric table | +| **Act** | 10 | Implement in `vgsp` with the evidence bundle linked; never in the simulator | PR carries the bundle and the metric table | | | 11 | Re-run the identical stimulus; require profiles to improve or stay equal; re-run the guest ladder | No rung regression; CI green | | | 12 | Archive the bundle and update the matrix/version docs only where earned | Recorded and reversible | diff --git a/docs/eng-ops.md b/docs/eng-ops.md index 218b8cd..20985d7 100644 --- a/docs/eng-ops.md +++ b/docs/eng-ops.md @@ -198,7 +198,7 @@ flowchart LR HR["harness/*.py"] end subgraph HOST["Host and guest"] - MOD["open-iov-vfio.ko"] + MOD["vgsp.ko"] VM["stock guest + guest-diag"] RMH["rmtool/rmtop/rmq + rmharness"] end @@ -450,7 +450,7 @@ decision. **Caveat, in every package README: this is a simulation package, not a signed production image.** It is not a firmware patch, must never be flashed or injected into a guest, and is not bootable on silicon. Injected code is development-only ([`docs/12`](../debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md) §1); -productization goes through `open-iov-vfio` + physical confirmation, never +productization goes through `vgsp` + physical confirmation, never through a simulator package. Local-only, budgeted, session-recorded; never touches `/dev`, a module, an @@ -550,7 +550,7 @@ the rules win. **Build order (physical-backend work needs the kernel module only):** -1. Build `open-iov-vfio.ko` first; it generates the `Module.symvers` the +1. Build `vgsp.ko` first; it generates the `Module.symvers` the optional OpenRM modules link against. `scripts/stack_manager.sh build-kernel`. 2. Build the optional OpenRM `nvidia.ko` with @@ -566,7 +566,7 @@ the rules win. 1. Prerequisites: `vfio`, `vfio_iommu_type1`, `vfio_pci`, `mdev` (`scripts/stack_manager.sh load-prereqs`). -2. `open-iov-vfio.ko` with the exact reviewed parameter set +2. `vgsp.ko` with the exact reviewed parameter set (`scripts/stack_manager.sh load-open-iov`). The backend claim is **module-owned** at load with `gsp_phys_gpu=1 gsp_phys_hazard_ack=1`, or **mdev-owned** and deferred to the first mdev create with @@ -602,7 +602,7 @@ authoritative for the literal default. | `gsp_phys_fault_relay` | 0 | On a relay timeout, drain the status queue for the engine fault (`0x1006`, corroborated by `0x1020`), match runlistId/chid and write the guest channel notifier + event. | Requires `gsp_phys_relay=1` and the three parameters above. | | `gsp_phys_fault_inject` | 0 | Debug: write the relayed pair's source PTE as zero to force an engine fault on the next relay submission; only relayed pairs are affected. | Requires the relay path; default 0 programs the real source HPA. | | `gsp_phys_rmcall_engine` | 0 | Ladder engine: 0 = COPY0 (CE copy submission), 1 = GR0 (compute object, BIND engineType 1, GR semaphore release). Snapshotted when stage 3 starts; mid-session changes are ignored. | Requires boot + init-done; CE forwarding paths refuse on a GR ladder. | -| `gsp_phys_rmcall_gr_promote` | 0 (clamp 0..3) | GR context-promote bisection: **0 never sends `PROMOTE_CTX`** (the ladder stops after the geometry queries, context buffer/PT allocation, PDB mapping and channel/compute alloc, before BIND); 1 = single MAIN entry, initialize/no-nonmapped, size raw+subctx; 2 = two-phase PA-only then VA-only; 3 = single entry with the exact raw size. Nonzero enables can assert GSP-RM (`0x52a8b04`) and wedge the device. | GR ladder only; value snapshotted at stage 3; **requires confirmed reboot readiness** before enabling. | +| `gsp_phys_rmcall_gr_promote` | 0 (clamp 0..17) | GR context-promote bisection: **0 never sends `PROMOTE_CTX`** (the ladder stops after the geometry queries, context buffer/PT allocation, PDB mapping and channel/compute alloc, before BIND); 1 = single MAIN entry, initialize/no-nonmapped, size raw+subctx; 2 = two-phase PA-only then VA-only with the same PA/VA/size; 3 = single entry with the exact raw size; 4 = two-phase with the reference client's zero-field VA-only step; 5 = one control with `entryCount=2` (PA-only init + zero-field VA-only); 6 = no-entry `hVirtMemory`: allocate an `NV01_MEMORY_VIRTUAL` (class 0x70) VA-range object on the ladder VAS at the context window, then `PROMOTE_CTX` with `hVirtMemory`/`virtAddress`/`size` and `entryCount=0`; 7 = no-entry bare `(virtAddress, size)` with `entryCount=0` and no `hVirtMemory`; 8 = single MAIN entry like 1 on the KMD-managed channel variant V6 (the V5 channel plus alloc flag `SKIP_CTXBUFFER_ALLOC` bit 31); 9 = same V6 channel with the stock client's zero-field VA-only MAIN entry (`bInitialize=0`); 10 = same V6 channel, `GPU_INITIALIZE_CTX` (`0x2080012d`) installs the physical context memdesc first, then `PROMOTE_CTX` `entryCount=0` bare `(virtAddress, size)`; 11 = mode 10 with the context buffer swapped to a server FBMEM allocation (class 0x40, VIDMEM `physAttr=0x4`, aperture-0 leaf PTEs); 12 = V5 UVM/vGPU-faithful PA-only MAIN entry (`bInitialize=1 bNonmapped=1`, no VA) and continue to BIND/SCHEDULE/submit; 13 = mode 12 plus a PATCH PA-only promote first (size from engine context properties engineId 0x10); 14 = V6 KMD channel + PATCH PA-only then the single-entry MAIN init+VA (the flow that books the context VA and calls the commit); 15 = mode 14 with a server FBMEM MAIN buffer and VIDMEM `physAttr 0x4`; 16 = mode 14 plus a PM ctxsw PA-only promote first (engineId 0x09); 17 = no client promote, paired with `gsp_phys_srv_ctxbuf=1` (pre-boot registry profile with `RMSetClientRMAllocatedCtxBuffer=0`) so the GSP-RM server-manages the context buffers. Live result: modes 1, 2 step 2 and 4 all wedged GSP-RM (`0x52a8b04`, `NV_ERR_OBJECT_NOT_FOUND` 0x57 in the LOGINIT stack) while the PA-only nonmapped step of modes 2/4 is accepted every time - the VA resolve, not the entry fields, is the wall (our external VAS has no server-side VA booking). Mode 6 (hVirtMemory, V5 channel) was refused **cleanly** (`status=0x1f` `NV_ERR_INVALID_ARGUMENT`, no assert, clean release) because the channel was not KMD-managed. Modes 8-11 all completed with **clean releases** (WPR2 down, driver rebound, 5 locks, pstore empty): the V6 channel alloc is accepted (`flags=0x80800000`); modes 8 and 9 (with and without an init entry) both return a clean `status=0x40` `NV_ERR_INVALID_STATE` (mode 9 without the server error log - entry shape irrelevant); mode 10's `GPU_INITIALIZE_CTX` is accepted (`status=0`) but the bare-VA promote still returns `0x40` with the same server log anchor; mode 11 (server FBMEM context buffer) returns `0x40` with a **different** server log anchor, so FBMEM moves the failure to a different structural check. Session 2 (modes 12-17, all clean): mode 12's V5 PA-only MAIN promote is **accepted** (`status=0`) and BIND succeeds, but the GR push faults `CTXNOTVALID` (`sem=0`, `GPGet=1`) - the accepted entry does not set `ENG_CTX_VALID`; mode 13 (PATCH first) and mode 14/15/16 (V6 KMD + PATCH, +PM, FBMEM/VIDMEM) all leave the MAIN promote at the same `0x40` rec-677 site as mode 8, so PATCH/PM/buffer type are not the missing prerequisite; mode 17 (registry `RMSetClientRMAllocatedCtxBuffer=0`, no promote) also faults `CTXNOTVALID`, so even server-managed context buffers leave the channel invalid - the remaining wall is the engine-context commit/RAMFC path, not buffer ownership. Nonzero enables can still assert GSP-RM and wedge the device. | GR ladder only; value snapshotted at stage 3; **requires confirmed reboot readiness** before enabling. | | `gsp_phys_repower` | 0 (latched) | Restore the pre-claim runtime-PM/D3cold policy when releasing the GPU; with 0 the D0 locks and runtime reference are deliberately left held until reboot. | **Never enable** (rule 3); re-arming D3cold after a claim can hard-freeze the host. | The emulation-side `sema_*` parameters (ring discovery, release recovery, @@ -627,7 +627,7 @@ hard signature. **Step 1 — build and identity check.** Rebuild the reviewed source; record the module hash; never run a cycle against a stale or unknown module. -**Step 2 — load.** Prerequisites, then `open-iov-vfio.ko` with the reviewed +**Step 2 — load.** Prerequisites, then `vgsp.ko` with the reviewed parameters. Module-owned: the claim and requested stages run at load. Mdev-owned: load, then create the mdev (the async claim/boot starts) only when no VM is live. @@ -699,7 +699,7 @@ written post-reboot plan - never a second attempt in the same boot. ### 10.4 debugfs inventory All files live under the module's debugfs directory -`/sys/kernel/debug/open-iov-vfio/`. **The directory and every file are +`/sys/kernel/debug/vgsp/`. **The directory and every file are root-only on this system**: existence and read checks must run as root (a permission error can look like an absent file). Every writer is inert unless its gates hold, and every accepted write performs a real RPC or device @@ -760,11 +760,11 @@ bump, device/ISA/ROM change, protected state, matrix/CI) are owned by | Symptom | Exact signal to look for | Decode / likely cause | First diagnostic | Action | |---|---|---|---|---| | Guest GR push faults | `func=0x1006 ... exceptType=0x20 runlistId=0 chid=1 errString="... intr1 80000000"`; NOCAT `recType=4 errorCode=0x20 faultingEngine="GR"` | `0x20` = robust-channel PBDMA error; `intr1` bit 31 = `CTXNOTVALID`; the external-VAS GR engine context was never committed (`ENG_CTX_VALID=0`), so the guest binds via `PROMOTE_CTX` (`0x2080012b`). CE channels are unaffected. | `gsp-phys-status-drain`; `gsp-phys-state` `rm_call`/`rm_call_ctx` | Decode first, no retry. Only a proven promote shape commits the context; keep the client promote path gated by `gsp_phys_rmcall_gr_promote=0` until a variant is proven. | -| `PROMOTE_CTX` wedge | `gsp-nocat: rec seq=N recType=5 errorCode=0x52a8b04 source="ASSERT" faultingEngine=""`, then no fn76 reply (timeout `-110`); status ring stops, server command read pointer advanced | A host/server-RM assert in the promote path - not an engine fault (no `0x1006`). The server consumed the command and wrote no reply. Teardown cannot clear WPR2 (its unlock is fuse-locked on this part). | `gsp-phys-state` (`cmd_tx`/`stat_tx`, `wpr2`), release log | Ladder aborts by design; **do not retry**. Fail-safe holds the device; reboot with written approval (rule 2); bisect exactly one promote variant per cycle after reboot. | +| `PROMOTE_CTX` wedge | `vgsp-nocat: rec seq=N recType=5 errorCode=0x52a8b04 source="ASSERT" faultingEngine=""`, then no fn76 reply (timeout `-110`); status ring stops, server command read pointer advanced | A host/server-RM assert in the promote path - not an engine fault (no `0x1006`). The server consumed the command and wrote no reply. Teardown cannot clear WPR2 (its unlock is fuse-locked on this part). | `gsp-phys-state` (`cmd_tx`/`stat_tx`, `wpr2`), release log | Ladder aborts by design; **do not retry**. Fail-safe holds the device; reboot with written approval (rule 2); bisect exactly one promote variant per cycle after reboot. | | WPR2 / clean-release failure | `teardown did not clear WPR2 (HI=0x...)`; `release: WPR2 still up after teardown ... refusing the hand-back`; `NOT rebinding ... power domain stays LOCKED` | The booter-unload gate bits were never completed by the wedge, or the board stopped answering; the host-side unlock is fuse-locked. | `gsp-phys-state` `wpr2`, `scratch14`, `stage:` | Fail-safe is the designed state: no rebind, locks held, WPR2 up. Leave the device; reboot with approval. | | Module unload hang | `rmmod` does not return; `ps` shows the emulation/relay kthreads or work items; mdev still present | Teardown ordering (kthread/workqueue) or an open mdev/VM; the emulation-side cleanup applies. | `ps -e \| grep gsp_emu`; mdev list; `dmesg` tail | Remove mdev/stop VM first; `scripts/stack_manager.sh cleanup-crash`; reboot with approval if it persists (rule 5). | -| Guest `cuInit` wedge / guest flake | guest `cuInit rc=999`, `rmapiControlCacheSet ... NV_ERR_INVALID_PARAMETER`, or a host `gsp-phys-fwsec: unexpected WPR2 already up`; a one-off guest Oops in `free_swap_cache` cleared on retry | On the emulated path this is a known guest-side flake; the WPR2-up line is the FWSEC refusal on a board already in a bad state. | guest dmesg; host `gsp-phys-state` `wpr2`; retry the guest once | If only the guest flaked, restart the guest once. If `unexpected WPR2 already up` appears, stop the cycle and inspect state; never retry FWSEC (rule 4/5). | -| GSP boot failure | `gsp-phys-fwsec: staging not visible before kick (DMEM0 ... IMEM ...)` then `FWSEC/FRTS execution failed: -5`; historical `GSP_INIT_DONE rpc_result=0x59` | Staging DMA did not land (async mdev-owned FWSEC path) or, historically, the pre-boot handshake/identity payload was wrong (`0x59` = operating-system error). | `gsp-phys-state` `stage:`, `gsp-phys-log-dump` | Use the module-owned claim path (proven); the async FWSEC defect is fail-open and off the critical path. Do not repeat a failed boot in the same boot after a hard signature. | +| Guest `cuInit` wedge / guest flake | guest `cuInit rc=999`, `rmapiControlCacheSet ... NV_ERR_INVALID_PARAMETER`, or a host `vgsp-fwsec: unexpected WPR2 already up`; a one-off guest Oops in `free_swap_cache` cleared on retry | On the emulated path this is a known guest-side flake; the WPR2-up line is the FWSEC refusal on a board already in a bad state. | guest dmesg; host `gsp-phys-state` `wpr2`; retry the guest once | If only the guest flaked, restart the guest once. If `unexpected WPR2 already up` appears, stop the cycle and inspect state; never retry FWSEC (rule 4/5). | +| GSP boot failure | `vgsp-fwsec: staging not visible before kick (DMEM0 ... IMEM ...)` then `FWSEC/FRTS execution failed: -5`; historical `GSP_INIT_DONE rpc_result=0x59` | Staging DMA did not land (async mdev-owned FWSEC path) or, historically, the pre-boot handshake/identity payload was wrong (`0x59` = operating-system error). | `gsp-phys-state` `stage:`, `gsp-phys-log-dump` | Use the module-owned claim path (proven); the async FWSEC defect is fail-open and off the critical path. Do not repeat a failed boot in the same boot after a hard signature. | | MMU/PTE faults and the fetch-line rule | engine copy times out with no semaphore; `GUEST CE COPY FAILED: scratch-PT pool exhausted ... capacity=512`; re-translated GPA yields a different HPA | The GMMU caches PTE fetches in 128-byte lines and there is no invalidate: a runtime PTE write into an already-fetched line is invisible. A guest page's HPA can change between translations. | `rm-call: guest HPA changed: gpa=... was ... now ...`; `work_guest` `pool_exhausted`/`next_line` | Always use a fresh never-reused line per pair; pre-build guest-window slots before engine access; pin translated pages; treat pool exhaustion as end-of-budget, not a bug. | | PBDMA method/class errors | `0x1006` with `intr0` nonzero (a method/class was rejected) versus `intr1` bit 31 (`CTXNOTVALID`); NOCAT `faultingEngine="GR"`; errString `"Channel ID ... intr0 ... intr1 ..."` | Wrong method encoding, class/subchannel or channel state; `intr0 != 0` means the engine rejected the method, so look at the pushed method block, not the context only. | `gsp-phys-status-drain`; compare the method encoding with the engine's class | Fix the method/class encoding; no retry against the same wedged channel; re-run from a fresh ladder. | | Relay symptoms | `GUEST CE RELAY FAILED: semaphore released ... does not match ... (retried after 2 ms)`; `verify_fail`/`verify_transient`/`hold_verify_fail`; `fallback`/`skipped_sw`; `pool_exhausted`; `guest HPA changed` | One persistent data mismatch (shadow-page/concurrent-guest race or decode offset edge) is the open residual; anything else is the designed fail-closed fallback to the software apply. | `work_relay` line; the relay failure log includes sem target/payload/poll, first differing byte, live/snapshot dumps, `src_mutated`, `snap_vs_dst` | Keep default off until the mismatch is triaged. Abort the feature (`gsp_phys_relay=0`, then `gsp_phys_work_forward=0`) if `timeouts>0` or `verify_fail>0` ever appears. | @@ -779,7 +779,7 @@ bump, device/ISA/ROM change, protected state, matrix/CI) are owned by | Failed mutating RPC wedges GSP-RM | One bad mutating operation (channel-flag incident; `PROMOTE_CTX` assert `0x52a8b04`) leaves the server unable to reply or suspend while WPR2 stays up. | One mutating attempt per staged step; never retry a failed mutating RPC; abort the ladder from the first failure; the release fail-safe keeps the locks and refuses the hand-back. | | debugfs write side effects | Every 0200 file performs a real RPC/device action when its gates hold; a "test" write changes device or guest state. | Root-only; read `gsp-phys-state` and record the intended effect before any write; one write per action; no trigger writes outside a supervised cycle. | | `pkill -f qemu-system-x86_64` self-match | The pattern also matches the invoking shell's own command line, killing the agent/session instead of the VM. | Use bracket patterns (`pgrep/pkill -f '[q]emu-system-x86_64'`) or explicit PIDs; stop VMs through `scripts/vgpu_vm.py`. | -| Root-only debugfs | The whole `open-iov-vfio` debugfs directory and its files are root-only; a non-root existence check reports absence. | Run existence/read checks under root; treat "missing" as a permission question first. | +| Root-only debugfs | The whole `vgsp` debugfs directory and its files are root-only; a non-root existence check reports absence. | Run existence/read checks under root; treat "missing" as a permission question first. | | Module reload/unload hazards | Kthread/workqueue teardown can hang; the IOMMU identity-domain property and the guest-RAM file must not outlive the session; unloading with a live mdev/VM corrupts the teardown order. | Remove mdevs and stop VMs first; `gsp_sema_service_work_quiesce()` before staging is freed (release does this); use `scripts/stack_manager.sh unload`/`cleanup-crash`; audit leftovers after every unload. | | pstore/journal persistence | A freeze leaves no oops but usually a persistent pstore record; the journal stops. | Check `/sys/fs/pstore` before and after every cycle; never clear it; capture it before any reboot or retry - it is the only post-freeze evidence. | | Guest-RAM shared-file requirement | The engine can reach guest pages only through the QEMU file-backed shared region; a non-shared or non-preallocated RAM backend has no host page cache to translate. | Start QEMU with `memory-backend-file,share=yes,prealloc=on`; configure the file via `gsp-phys-guest-ram`; one file per module cycle; translation is gated on an open mdev and an active range. | diff --git a/docs/future-eng-ops.md b/docs/future-eng-ops.md index 13a0b73..3191c9f 100644 --- a/docs/future-eng-ops.md +++ b/docs/future-eng-ops.md @@ -11,7 +11,7 @@ Status snapshot: 2026-10-02. Sources are the risc-v-gsp-rm-debugger roadmap, tool docs 16–27, the `harness/` entry points and the tool audit (doc 27). The tool tree -is development-only: never shipped, never a dependency of `open-iov-vfio`, +is development-only: never shipped, never a dependency of `vgsp`, never present in a guest. RM 610 work is gated by human approval ([`docs/21` §3](../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md), [`docs/23`](../debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md)). diff --git a/docs/tools/README.md b/docs/tools/README.md index c5ebb9f..fd805f1 100644 --- a/docs/tools/README.md +++ b/docs/tools/README.md @@ -69,7 +69,7 @@ tools/ ## Integration with Open-IOV Stack Tools will integrate with the host VFIO driver via: - `/dev/nvidia*` character devices (existing nvidia.ko) -- `open-iov-vfio.ko` observability: **there is currently no debugfs interface** — +- `vgsp.ko` observability: **there is currently no debugfs interface** — stats and traces come from `dmesg`, and the module's write-only parameters (`scan_guest_ram`, `scan_vidmem`, `scan_seq`, `sema_probe`, `scan_pt`, `scan_masked`, `fill_vidmem`, `poke_guest`, `poke_fill`, `dump_vidmem`, |