From 2302fc09080bad51c73f293294e19fd4db464eb0 Mon Sep 17 00:00:00 2001 From: Open-IOV Date: Wed, 23 Sep 2026 05:44:08 -0400 Subject: Open-IOV: initial public release Open-IOV virtualizes NVIDIA GPUs so that unmodified guest drivers run with real GPU functionality - CUDA first, 3D and video to follow - on unmodified hosts, without a proprietary vGPU license and without patching any driver, firmware or hypervisor. Core principle: emulate the interface, pass through the work. kernel/ open-iov-vfio.ko - host VFIO mdev driver: virtual GPU device (PCI config space, BAR shadows, MSI-X), GSP boot emulation, GSP-RM message-queue/RPC emulation, memory model (GPU-VA to guest-PA discovery) and the semaphore-completion service that advances guest UVM progress. userspace/ libiov.so management API and examples. tools/ guest diagnostics, firmware analysis wrappers, RM probes. scripts/ stack manager, VM harness, build/load/test automation. config/ hardware/version profiles (the portability surface). docs/ documentation tree - start at docs/README.md. wiki/ long-form firmware and protocol deep dives. Status: initialization works end to end for a stock 570.144 Linux guest on Turing (TU104): driver probe, nvidia-smi, the full GSP-RM control battery, object creation and the early CUDA/UVM start-up path. GPU work forwarding - the step that makes CUDA kernels execute on real hardware - is the active work item; see docs/04-implementation/01-known-knowns-and-unknowns.md. License: BSD-3-Clause for the project; GPL-2.0 for kernel modules that link GPL-only kernel interfaces. See LICENSE and docs/09-reference/legal-and-licensing.md. --- docs/09-reference/glossary-and-faq.md | 103 +++++++++++++++++++++++++++++++ docs/09-reference/legal-and-licensing.md | 81 ++++++++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 docs/09-reference/glossary-and-faq.md create mode 100644 docs/09-reference/legal-and-licensing.md (limited to 'docs/09-reference') diff --git a/docs/09-reference/glossary-and-faq.md b/docs/09-reference/glossary-and-faq.md new file mode 100644 index 0000000..255d1a6 --- /dev/null +++ b/docs/09-reference/glossary-and-faq.md @@ -0,0 +1,103 @@ +# 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. | +| **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. | +| **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`, ...). | +| **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. | +| **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. | +| **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 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. + +**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?** +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. + +**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. diff --git a/docs/09-reference/legal-and-licensing.md b/docs/09-reference/legal-and-licensing.md new file mode 100644 index 0000000..74f1363 --- /dev/null +++ b/docs/09-reference/legal-and-licensing.md @@ -0,0 +1,81 @@ +# Legal, Licensing, and Third-Party Material + +> What is licensed how, what we may redistribute, and how we stay clean while +> doing adversarial interoperability. + +## 1. The project's licenses + +| 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. | +| `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. | + +Per-file `SPDX-License-Identifier` headers always govern. + +The split is deliberate: the kernel side gets a clean legal footing; everything +vendor-facing, embeddable and reusable stays permissive. Commercial adoption is +welcome and requires no license fee. + +## 2. How we learn the interfaces + +Open-IOV is built by **reverse engineering and decompilation**: we study the +behaviour of vendor drivers and firmware — in VMs, on hardware, and by +disassembling published firmware images and analysed binaries — and we +reimplement the interfaces we discover. What this project publishes is our +own work: behaviour descriptions, numeric identifiers, layouts, emulation +code, and the evidence behind each observation. + +In this repository you will find: + +* **GSP firmware images** (`firmware/**/*.fwimage.bin`) — fetched from public + distribution channels (e.g. `linux-firmware`); used to understand and + emulate the firmware interface. +* **Decompiled firmware artifacts** (`firmware/**/decompiled/`) — our own + analysis output; kept for study and cited in the wiki. +* **Reformatted interface tables** — IDs, structures and message layouts that + we derived, published in `wiki/` and in this documentation tree. + +**Our rule:** publish *our work product* (facts, layouts, behaviours, code and +evidence). Do not copy third-party source or documentation into this project, +do not point readers at material we cannot redistribute, and do not +redistribute third-party binaries as project content beyond what their terms +allow. + +## 3. Adversarial interoperability and the law + +We implement the *interface contract* so that unmodified NVIDIA software can +talk to our device. We do not: + +* copy NVIDIA driver code into our kernel module, +* patch NVIDIA drivers or firmware, +* defeat licensing for NVIDIA's own products (our device is our device; no + impersonation of a licensed product identity). + +Where interoperability requires knowledge of structures and constants, we +obtain them from publicly distributed headers and from observation of the +unmodified guest in a lab, and we document the evidence. This is the same +discipline used by other interoperable implementations of closed interfaces. + +If you believe a specific artifact in this repository is improperly included, +open an issue: we would rather over-comply than argue. + +## 4. Contributions + +* Inbound = outbound: contributions to BSD-3-Clause files are BSD-3-Clause; + contributions to GPL-2.0 files are GPL-2.0. +* By contributing you confirm you have the right to do so and that the + contribution does not contain third-party material under incompatible terms. +* Write original code. Describe behaviour, cite the evidence, and reimplement + interfaces from observation rather than copying anyone's source. +* Do not commit firmware or ISO images unless they are explicitly permitted and + listed in `.gitattributes`/LFS policy. + +## 5. Export, safety and platform notes + +* GPU firmware and drivers may be subject to export regulations in your + jurisdiction; users are responsible for compliance. +* Security-sensitive deployments should follow the security evaluation doc and + the platform's attestation mechanisms (e.g. TrenchBoot). +* Nothing in this project's licensing changes the licenses of the host + distribution's NVIDIA driver, the guest's driver, or any hypervisor. -- cgit v1.2.3