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.

1 files changed, 157 insertions, 0 deletions

diff --git a/docs/01-orientation/01-purpose-and-scope.md b/docs/01-orientation/01-purpose-and-scope.md
new file mode 100644
index 0000000..eab63bc
--- /dev/null
+++ b/docs/01-orientation/01-purpose-and-scope.md
@@ -0,0 +1,157 @@
+# Purpose and Scope
+
+> Read this first. It defines what Open-IOV is for, what it is not for, and how
+> we will judge whether we are succeeding.
+
+## 1. Mission
+
+**Make NVIDIA GPUs fully virtualizable, by anyone, for any hypervisor, without
+modifying NVIDIA software, firmware or hardware.**
+
+Concretely, Open-IOV builds an independent, maintained IP block that:
+
+* presents a virtual NVIDIA GPU to a guest operating system,
+* lets the guest run the **stock NVIDIA driver** (Linux and Windows),
+* supports **compute (CUDA)** first, then **3D graphics** and **video**,
+* runs on ordinary NVIDIA GPUs already deployed in the field,
+* isolates guests from each other and from the host,
+* and does not require a license key, a proprietary host service, a patched
+  guest driver, or a specific hypervisor.
+
+## 2. What problem are we solving?
+
+Today there are four ways to use an NVIDIA GPU with virtual machines, and all
+of them have a hard limitation:
+
+| Approach | Limitation |
+|---|---|
+| Discrete device assignment (VFIO passthrough) | One GPU per VM. Complex, fragile for laptops and consumer PCs. No sharing. |
+| NVIDIA proprietary vGPU | Requires a license. Requires a vendor host stack. Driver-version locked. Windows/Linux only where the vendor ships builds. |
+| Software emulation of a GPU (e.g. QEMU's virtual GPUs, virgl) | No real CUDA. No real 3D performance. Not usable for AI. |
+| Cloud-only inference | Needs an external service. Unacceptable for secure edge, offline, or private data. |
+
+Open-IOV occupies the gap: **real GPU acceleration, multiple VMs, stock
+drivers, no license.**
+
+## 3. Scope
+
+### In scope
+
+* **Host-side virtualization of NVIDIA GPUs** for Linux hosts via VFIO/mdev
+  (KVM now; Xen and others later), as a self-contained kernel module plus a
+  small userspace library.
+* **Full guest-visible device emulation**: PCI configuration space, BARs
+  (MMIO register space, VRAM aperture, instance memory), MSI-X, doorbells,
+  power management stubs.
+* **GSP and GSP-RM interface emulation**: firmware boot handshake, message
+  queues, RPC transport, resource-manager controls, object model, event
+  channels, and the pieces of the hosted resource manager the guest depends on.
+* **A memory model** that connects guest GPU address spaces to real GPU memory
+  and to guest system memory, including page tables and fault handling.
+* **Compute forwarding**: taking the work the guest submits (channels, push
+  buffers, runlists, compute commands) and executing it on the physical GPU in
+  a way that is correct, isolated and fast.
+* **Graphics and video forwarding** (later phase, same architecture).
+* **Guest support**: Linux (x86_64 and aarch64) and Windows (x86_64).
+* **Host support**: Linux (x86_64 now, aarch64 later), KVM today, Xen/Argo/
+  OpenXT/Qubes OS Air on the roadmap.
+* **Hardware portability**: Turing (TU104) today; Ampere, Hopper,
+  Grace-Hopper, Grace-Blackwell and GB10 targets; a configuration-driven
+  adaptation layer for new GPUs.
+
+### Out of scope (non-goals)
+
+* **Replacing bare-metal inference serving.** vLLM's continuous batching on
+  bare-metal hosts is how the industry scales multi-tenant inference in
+  datacenters, and it is better at that than any virtualization layer will be.
+  Open-IOV is for the cases where compute must live *inside* a guest.
+* **Forking or patching the NVIDIA driver**, in guest or host.
+* **Forking or patching GPU firmware.**
+* **Forking or patching hypervisors** (QEMU, KVM, Xen, Argo, OpenXT, ...) to
+  make the device work.
+* **Anti-cheat / DRM circumvention**, cloud-gaming-specifically defeating
+  vendor licensing checks for their own products. We interoperate; we do not
+  counterfeit. (We do not need a license for *our* device, because it is our
+  device.)
+* **Emulating GPU instruction execution in software.** Software emulation of
+  CUDA kernels is 100–1000× too slow; work must run on real silicon.
+
+## 4. Value
+
+For **users**: GPU acceleration in VMs on hardware you own, with no per-VM fee,
+on Windows and Linux, across generations of GPUs.
+
+For **integrators and hypervisor projects**: a GPU component that behaves like
+any other virtual device, enabling security models that were previously
+impossible (see HAAEEP in
+[`../08-ecosystem/haaeep-and-collaboration.md`](../08-ecosystem/haaeep-and-collaboration.md)).
+
+For **the wider ecosystem**: an independent, permissively licensed
+implementation of a previously single-vendor interface, with public
+documentation of the protocol, the firmware and the architecture — a public
+good that outlives any one vendor's product decisions.
+
+## 5. Model of multi-tenancy
+
+Open-IOV is built for **multiple independent tenants on one GPU**:
+
+* Each VM gets its own mediated device instance (mdev) and its own
+  guest-visible GPU.
+* Memory is isolated by the platform IOMMU: a tenant's device can only reach
+  *that tenant's* memory.
+* Interrupts are delivered per instance; no shared vectors.
+* The host module holds no tenant-secret state; everything is per-VM.
+* Scheduling between tenants is explicit policy (time-sliced now; MIG-backed
+  partitioning later where hardware supports it).
+* The security posture is *fail closed*: if the isolation assumptions cannot be
+  verified at run time, the device refuses to start.
+
+How this is enforced and audited is documented in
+[`../05-operations/01-performance-correctness-security.md`](../05-operations/01-performance-correctness-security.md).
+
+## 6. How we judge success
+
+We evaluate the project on five axes; each has a dedicated methodology
+document:
+
+1. **Initialization** — the guest driver loads, probes, and initializes to the
+   same point it does on bare metal: `nvidia-smi`, CUDA runtime, `cuInit`,
+   context creation, module load.
+2. **Runtime** — the guest *runs* real work: CUDA kernels with correct results,
+   OpenGL/Vulkan rendering, encode/decode; repeated, sustained, resilient.
+3. **Interoperability** — no changes required anywhere: guest driver builds,
+   host driver builds, firmware, hypervisor, device model software. Both host
+   and guest firmware interfaces are honored.
+4. **Stability** — crash-free under stress: start/stop cycles, VM kill, guest
+   driver reload, host driver reload, suspend/resume, migration.
+5. **Performance and security** — within an agreed factor of native for the
+   supported cases, with isolation that survives adversarial review.
+
+## 7. Where we are, and where we need improvement
+
+* **Working today**: the virtual device, the GSP boot handshake, the RPC
+  transport, the resource-manager emulation surface the guest driver needs to
+  probe and enumerate, guest `nvidia.ko` and `nvidia-smi`, and the early UVM
+  initialization path.
+* **Needs improvement**: GPU work forwarding (the reason CUDA kernels do not
+  yet run), the memory/page-table model, Windows guest support, non-KVM
+  hypervisors, and performance instrumentation. Each of these is tracked with
+  explicit "known-unknowns" in
+  [`../04-implementation/01-known-knowns-and-unknowns.md`](../04-implementation/01-known-knowns-and-unknowns.md).
+
+## 8. Guiding principles
+
+1. **Own the interface, not a snapshot of it.** Every emulated interface is
+   described by a version-agnostic model plus per-version configuration; new
+   versions are added by measurement, not by rewriting.
+2. **Emulate the interface, pass through the work.** Anything that must be fast
+   runs on real hardware; everything the guest can observe is virtual.
+3. **No patches anywhere.** If a change is needed in someone else's software,
+   firmware or hardware, our design is wrong.
+4. **Make the invisible visible.** Instrument everything; keep
+   `dmesg`-readable telemetry for every decision the emulation makes.
+5. **Fail closed, fail loudly.** Isolation failures stop the device; protocol
+   surprises are logged with enough context to reproduce them.
+6. **Document for the next person.** A feature is not done until a newcomer can
+   understand and maintain it from these docs alone.
+7. **Permissive and portable by design** (BSD-3-Clause): adoption is a feature.