# Glossary and FAQ

## Glossary

| 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; engine descriptor `0x793ceb0e`, instance 14, client type `0x38`, class pair `0xc9b5`. Its earlier absence from the emulated list was a context-creation blocker; the emulated inventory now includes it (two GRCEs). |
| **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. |
| **GR** | The graphics/compute engine that executes shaders (graphics pipelines and CUDA kernels). |
| **GSP** | GPU System Processor: the embedded RISC-V (RV64IMAC) that runs firmware containing the Resource Manager. |
| **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. |
| **Runlist** | The scheduler's list of channels eligible to run. |
| **SEC2** | Secure copy engine used by UVM for protected operations. |
| **Semaphore / tracker** | Memory location written by the GPU to signal progress; UVM's tracker waits on it. |
| **SRIOV / VF** | Single-root I/O virtualization / virtual functions (hardware partitioning). |
| **TSG** | Time-Slice Group: channels sharing a scheduling slot. |
| **USERD** | Per-channel control block in VRAM: PUT/GET pointers and control state. |
| **UVM** | NVIDIA's unified memory module: VA spaces, page trees, faults, channel manager. |
| **VA / PA / GPA / IOVA** | Virtual address / physical address / guest physical address / I/O virtual address. |
| **vidmem / sysmem / aperture** | GPU local memory / system memory / the way an address is qualified (`ADDR_FBMEM = 2`, `ADDR_SYSMEM = 1`). |
| **VGX version** | The version the guest announces during RPC negotiation; selects message layouts. |
| **vGPU** | Virtual GPU: this project's device. |
| **WPR** | Write-Protected Region: VRAM area reserved for firmware. |

## FAQ

**Is this a replacement for vLLM on bare metal?**
No. Continuous batching on bare-metal hosts is the right answer for centralized
inference. Open-IOV is for compute *inside guests*: Windows/Linux CUDA, 3D,
video, and secure edge isolation. See the orientation docs.

**Does the guest driver need to be patched?**
No, and that is a hard project rule. No guest driver patches, no host driver
patches, no firmware patches, no hypervisor patches.

**Does it work with the distribution's NVIDIA driver on the host?**
Yes — in the standalone configuration the distribution driver owns the physical
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 my CUDA kernel not running?**
The driver-API path works: `cuInit`, device enumeration, `cuCtxCreate` and
the full smoke test (allocation, copies, free and destroy) complete, and a
guest kernel launch is forwarded to the physical engine queue. What has not
been observed yet is *execution*: the engine does not execute the forwarded
launch descriptor and no engine-authored release appears. That is the current
frontier, not a setup problem; the chosen execution backend is documented in
[`../03-architecture/08-physical-gpu-integration.md`](../03-architecture/08-physical-gpu-integration.md).
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
exports); we interoperate with unmodified NVIDIA software rather than
relicensing it. See the legal document.

**Will it support Windows guests?**
Yes, it is a target: same architecture, measured bring-up. See the portability
matrix.

**Can I run several VMs on one GPU?**
Yes — that is a core design goal (per-VM mdev, IOMMU isolation, explicit
scheduling). Multi-tenant maturity depends on the scheduling/isolation work in
the known-unknowns list.

**Does it support Xen / Qubes OS Air / Argo / OpenXT?**
Designed for them; the transport backends are on the roadmap. The emulation
core is hypervisor-independent by construction.

**What about MIG?**
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?**
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
reproduction plus logs is worth more than a description.

**Can my company use this commercially?**
Yes, under BSD-3-Clause (kernel modules GPL-2.0), with no fee. We also welcome
co-development; see the ecosystem document.

**How do I contribute support for my GPU/driver/hypervisor?**
Follow the "adding a new combination" workflows in the portability and
maintenance docs; the deliverable is a profile plus evidence from the
evaluation ladder.