# Project Goals

> **Scope.** What Open-IOV is for, what it is not for, and the dated status of
> each goal. Condensed from
> [`../docs/01-orientation/01-purpose-and-scope.md`](../docs/01-orientation/01-purpose-and-scope.md)
> (mission, scope and success criteria) and
> [`../docs/README.md`](../docs/README.md) (the project front door); the docs
> tree wins on disagreement. The live milestone ladder is on
> [`Project-Status.md`](Project-Status.md), and the current execution detail on
> [`Execution-Frontier.md`](Execution-Frontier.md) and
> [`Graphics-Execution.md`](Graphics-Execution.md).

Status: 2026-10-30, tree `master @ b4930168`. Tags: `[live]` working with the
stock guest driver; `[wip]` in progress; `[planned]` designed, not built;
`[target]` bring-up ahead; `[non-goal]` explicitly out of scope.

## 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 requires no license key, no proprietary host service, no patched guest
  driver, and no specific hypervisor.

The guiding sentence is: ***Emulate the interface. Pass through the work.
Never patch anyone.***

## 2. The gap it fills

| Approach | Limitation |
|---|---|
| Discrete device assignment (VFIO passthrough) | One GPU per VM; no sharing; fragile on consumer/laptop systems. |
| NVIDIA proprietary vGPU | Requires a license and a vendor host stack; driver-version locked. |
| Software GPU emulation (QEMU virtual GPUs, `virgl`) | No real CUDA; no real 3D performance; not usable for AI. |
| Cloud-only inference | Requires 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. Goals and their status

| Goal | What success looks like | Status (2026-10-30) |
|---|---|---|
| Stock guest driver initialisation | The unmodified driver probes, initialises and enumerates as on bare metal (`nvidia-smi`) | `[live]` — TU104 reference platform |
| Full CUDA driver-API surface | Context creation, allocation, copies, free, destroy complete with correct results | `[live]` — the driver-API smoke prints `ALL OK`; the 64-byte payload round-trips |
| CUDA kernel execution on real hardware | Verified guest kernels execute on the physical GPU, with engine-authored completions waking the guest | `[live]` — vector-add, matrix-multiply and transformer clients green on fresh boots; the staged-transfer class, the every-boot acceptance campaign and per-guest isolation are in progress ([`Execution-Frontier.md`](Execution-Frontier.md)) |
| OpenGL (3D graphics) | Stock guest GL applications render real pixels through the emulated vGPU | `[wip]` — Xorg/GLX run, the engine executes GL method streams (verbatim 3D replay + synthesized launches); rendered pixels are the frontier ([`OpenGL.md`](OpenGL.md)) |
| Vulkan | Stock guest Vulkan applications render real pixels | `[wip]` — the pipeline runs end to end (device → command buffer → fence → readback); frames are black — program delivery and program-VA mapping are the frontier ([`Vulkan.md`](Vulkan.md)) |
| Windows guests (DirectX, CUDA) | A stock WDDM driver and stock D3D/CUDA applications run in Windows guests | `[target]` — not started; same emulation target ([`DirectX.md`](DirectX.md)) |
| Video (NVENC/NVDEC) | Encode/decode through the emulated device | `[planned]` |
| Multi-tenant isolation | Multiple VMs on one GPU, isolated by the IOMMU and the device model, with explicit scheduling | `[wip]` — two mediated devices (different emulated VRAM sizes) and two guests coexist; per-guest execution isolation is in progress ([`GMMU-Multi-Tenant-Protection.md`](GMMU-Multi-Tenant-Protection.md)) |
| Hypervisor portability | The same IP block attaches to KVM, Xen, Argo/OpenXT, Qubes OS Air, ... | `[planned]` — the emulation core is hypervisor-independent by construction; KVM/QEMU with VFIO mdev is the reference transport ([`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md)) |
| Version and hardware portability | New driver, firmware or GPU generations enter by configuration plus measurement | `[wip]` — 570.144/TU104 is the anchor; per-version evidence workflows exist; newer versions are gated work |
| Live migration | A VM migrates with its GPU state | `[planned]` — the protocol analysis is kept for the record ([`Migration-Protocol.md`](Migration-Protocol.md)) |
| Performance | Within an agreed factor of native for the supported cases, with published methodology | `[planned]` — no published numbers yet; the first scheduled measurement is the 60 fps graphics target ([`Graphics-Execution.md`](Graphics-Execution.md)) |
| Security posture | Isolation survives adversarial review; the device fails closed | `[wip]` — fail-closed design and audit practice; per-tenant execution isolation is in progress ([`../docs/05-operations/01-performance-correctness-security.md`](../docs/05-operations/01-performance-correctness-security.md)) |

## 4. How success is judged

The project evaluates itself on five axes, each with a methodology document
in [`../docs/05-operations/01-performance-correctness-security.md`](../docs/05-operations/01-performance-correctness-security.md):

1. **Initialization** — the driver reaches bare-metal parity through boot,
   probe and initialisation.
2. **Runtime** — the guest runs real work: CUDA kernels with correct results,
   OpenGL/Vulkan rendering, encode/decode; repeated, sustained, resilient.
3. **Interoperability** — no changes anywhere: guest driver, host driver,
   firmware, hypervisor.
4. **Stability** — crash-free under stress: start/stop cycles, VM kill, driver
   reload, suspend/resume, migration.
5. **Performance and security** — within an agreed factor of native, with
   isolation that survives adversarial review.

## 5. Non-goals

* **Replacing bare-metal inference serving.** Continuous batching on
  bare-metal hosts remains the right answer for centralised datacenter
  inference; Open-IOV is for compute that must live *inside* guests.
* **Forking or patching** the NVIDIA driver (guest or host), the GPU firmware,
  or hypervisors to make the device work.
* **Anti-cheat / DRM circumvention.** The project interoperates with
  interfaces and implements **its own** device; it does not counterfeit
  vendor licensing.
* **Emulating GPU instruction execution in software.** Software emulation of
  CUDA kernels is orders of magnitude too slow; work must run on real silicon.

## 6. Related pages

* [`Project-Status.md`](Project-Status.md) — the dated milestone ladder.
* [`Execution-Frontier.md`](Execution-Frontier.md) — the compute execution
  frontier.
* [`Graphics-Execution.md`](Graphics-Execution.md) — the 3D execution
  frontier.
* [`HAAEEP-and-Collaboration.md`](HAAEEP-and-Collaboration.md) — the
  agent-edge use case and collaboration models.
* [`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md) — the support
  ladder.
* [`../docs/01-orientation/01-purpose-and-scope.md`](../docs/01-orientation/01-purpose-and-scope.md) —
  the canonical purpose-and-scope document.