1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
# 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: copy-engine-class work forwarding and engine-authored
release + fault relay are implemented but default off, and GR/kernel execution
is still the open frontier (a forwarded guest launch reaches the front-end but
the inline launch-descriptor install has not been observed — see
[`../04-implementation/03-execution-frontier.md`](../04-implementation/03-execution-frontier.md));
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 I run the live hardware cycles?**
Live physical-backend cycles are supervised only — one at a time, never
unattended — and a system is never rebooted without a written reason, a
post-reboot plan and explicit human approval. The operational detail is in the
engineering-operations document, Part II
([`../eng-ops.md`](../eng-ops.md)).
**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.
|
