From 13f46e60760cc0855484cc69de913ea34f55c24f Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Wed, 23 Sep 2026 12:11:10 -0400 Subject: docs: refresh status, supersede stale material, link the CUDA analysis * Status now matches the live state: guest driver probe and nvidia-smi work; cuInit/device queries work; cuCtxCreate returns 999 because the emulated engine list is missing the async copy engine (COPY14). The userspace libcuda segfault is recorded as solved, with its mechanism (an RM allocation reply must echo request parameters; zeroing them corrupted the caller's saved frame pointer). * Correct the emulation claims: only a subset of RM controls are special-cased; the rest return a success reply with zeroed parameters whose consumed fields are still being corrected; allocation replies are coherent but no server-side object model exists. * Add the eight-point emulation checklist and reply-fidelity ladder as explicit gates, documented in userspace/cuda and linked from the architecture, implementation and operations docs. * Fix operational errors: build/test commands, module load order, mdev type names, LFS references, debugfs claims, in-repo firmware claims, CI claims, portability matrix (guest status, config layout, userspace driver facts). * Mark historical material: one superseded banner per legacy document with a pointer to its replacement; STATE.md marked as a 2026-09-21 snapshot. * Wiki: fix the index, add status banners and in-place factual corrections (msgq transport vs legacy mailbox, BAR definitions, error statuses, migration, glossary), and note the archived 2023 imports. --- docs/09-reference/glossary-and-faq.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) (limited to 'docs/09-reference/glossary-and-faq.md') diff --git a/docs/09-reference/glossary-and-faq.md b/docs/09-reference/glossary-and-faq.md index 255d1a6..2ec4faa 100644 --- a/docs/09-reference/glossary-and-faq.md +++ b/docs/09-reference/glossary-and-faq.md @@ -5,11 +5,15 @@ | Term | Meaning | |---|---| | **AMAPlib** | NVIDIA's shared "address mapping" library: swizzling, bank/channel mapping, aperture rules. Studied for page-table and memory-layout semantics. | +| **Async copy engine (COPY14)** | A copy-engine instance found in the host oracle's engine list but missing from the emulated list — engine descriptor `0x793ceb0e`, instance 14, client type `0x38`, class pair `0xc9b5`. Its absence is the current CUDA context-creation blocker. | | **BAR0 / BAR1 / BAR3** | PCI BAR windows of the GPU: register interface (16 MB), VRAM aperture (256 MB), instance/PRAMIN window. | | **CE** | Copy Engine: DMA engine; also used for UVM's internal work. | +| **Class list (classDB)** | The set of RM classes reported as supported (`GPU_GET_CLASSLIST`); engine queries are filtered against it, so the class list, engine list and caps controls must agree. | | **CUDASW** | The family of NVIDIA user-space software that sits between applications and the driver: `libcuda`, `libcudart`, JIT compiler, fatbinary loader, and friends. | | **Doorbell** | A register/memory location a driver writes to signal "new work is available" for a channel or queue. | | **Engine type** | Numeric identifier for an execution engine (`GR = 0x1`, `COPY0 = 0x9`, ...). | +| **Engine record / engine list** | The per-engine descriptors (kind, instance, class, client type) the driver walks after `GPU_GET_ENGINES`/`GET_ENGINES_V2`; each record must be self-consistent or the driver rewrites the following allocation. | +| **File virtual address (`libcuda+0x...`)** | An address relative to the start of a shared object file (e.g. a `libcuda` offset), as distinct from a runtime mapping or a Ghidra program address; public docs cite these. | | **FWSEC** | Firmware security processor stage of the GSP boot sequence. | | **GNND / GB10** | NVIDIA "Grace-Blackwell" systems-on-chip used in DGX Spark and Surface-class laptops; explicit portability targets. | | **GPFIFO** | GPU FIFO: a ring of entries, each pointing to a push buffer for a channel. | @@ -18,12 +22,15 @@ | **GSP-RM** | The Resource Manager running on the GSP ("self-hosted RM"). | | **GMMU** | GPU Memory Management Unit: page tables, TLB, fault handling. | | **HAL** | Hardware Abstraction Layer: per-generation functions that program registers and formats. | +| **Host oracle / A-B harness** | The same query or deterministic workload run against a bare-metal (host) driver and inside the guest, then diffed — our reference for what the guest should have seen. | | **mdev** | Mediated device: the kernel mechanism that turns a physical device into virtual instances (VFIO). | | **MSGQ** | The GSP message queue transport: shared-memory element rings with a page table, plus doorbells. | | **PBDMA** | Push-buffer DMA engine in the host scheduler that fetches and executes push buffers. | | **PDB** | Page Directory Base: root of a GPU page table. | | **PDE / PTE** | Page-directory entry / page-table entry. | | **Push buffer** | A stream of method calls (engine commands) submitted via a GPFIFO. | +| **QMD** | Queue Meta Data: the per-launch descriptor a GR channel reads to execute a kernel grid. | +| **Reply fidelity** | How completely an emulated reply matches what real hardware returns, as a ladder: status-only → coherent zeroed params → coherent values for consumed fields → exact values. | | **RMCore** | The RM's object system: classes, handles, parents, methods. | | **RM / RM API** | NVIDIA's Resource Manager and the API used to allocate objects and issue controls. | | **resserv / resource server** | The RM component that owns allocation authority, privileges and lifetimes. | @@ -57,10 +64,14 @@ GPU and Open-IOV is an independent module. Building NVIDIA's OpenRM modules from source is only needed for the native-vGPU-management workflows. **Why is `nvidia-smi` working but CUDA not?** -Because CUDA requires *execution*: kernels must run on real hardware. The -current state runs the entire initialization path (including UVM's start-up) -but stops short of executing engine work. See the known-knowns document for -the exact status and plan. +CUDA startup reaches `cuInit` / `cuDeviceGet`, but context creation is blocked: +the emulated engine list lacks the async copy engine (`COPY14`), so +`cuCtxCreate` returns `rc=999` (`CUDA_ERROR_UNKNOWN`) and memory allocation +never runs. (The earlier `libcuda` segfault on this path was fixed by echoing +the request params back in the alloc reply.) Once context creation is green, +CUDA still needs *execution*: kernels must run on real hardware. See the +known-knowns document for the exact status and plan; start at +[`../../userspace/cuda/READ-ME-FIRST.md`](../../userspace/cuda/READ-ME-FIRST.md). **How is this legal / license-clean?** Open-IOV is BSD-3-Clause (GPL-2.0 for kernel modules that link GPL-only kernel @@ -85,9 +96,11 @@ MIG is a hardware partitioning mechanism; Open-IOV's scheduling policy can use it where available. It is part of the multi-tenancy work. **How fast is it?** -Initialization currently completes in the same order of magnitude as native; -execution forwarding is not implemented yet. Performance claims follow the -published methodology in the operations docs. +No published numbers yet: execution forwarding is not implemented, and even +the initialization path has not been measured under the project's methodology. +Any performance claim will come with the methodology and the measurements +together (see +[`../05-operations/01-performance-correctness-security.md`](../05-operations/01-performance-correctness-security.md)). **Where do I report bugs or ask for help?** Open an issue with the standard captures listed in the debugging document. A -- cgit v1.2.3