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.

2 files changed, 184 insertions, 0 deletions

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.