# Open-IOV

**Open-IOV** is an open source virtualization layer for NVIDIA GPUs. It lets an
**unmodified NVIDIA guest driver** run inside a VM with full GPU functionality —
CUDA first, then 3D and video — without a proprietary vGPU license, without
patching any driver or firmware, and without forking any hypervisor.

> **Emulate the interface. Pass through the work. Never patch anyone.**

## Start here

* **New to the project?** Read the documentation front door:
  **[docs/README.md](docs/README.md)** — it explains what Open-IOV is, why it
  exists, the honest current status, and how to navigate the docs from first
  read to deep developer material.
* **Just want it running?** [Install and first run](docs/02-getting-started/01-install-and-first-run.md).
* **Want to know how it works?** [System overview](docs/03-architecture/01-system-overview.md).
* **Want to help?** [Developer onboarding](docs/07-developers/onboarding-and-standards.md)
  and [known-knowns/known-unknowns](docs/04-implementation/01-known-knowns-and-unknowns.md).

## What is in this repository

| Path | Contents |
|---|---|
| `kernel/` | `open-iov-vfio.ko` — host VFIO mdev driver: virtual GPU device, GSP/GSP-RM emulation, memory model, work forwarding (in progress) |
| `userspace/` | `libiov.so` management library, examples, tests |
| `tools/` | diagnostics, guest-side probes, firmware analysis wrappers |
| `scripts/` | `stack_manager.sh`, VM harness, build/load/test automation |
| `config/` | hardware, driver-version and profile configuration (the portability surface) |
| `firmware/` | versioned GSP firmware analysis artifacts (images fetched by `install.sh`) |
| `docs/` | **the documentation tree** (entry point: `docs/README.md`) |
| `wiki/` | long-form firmware/protocol deep dives |
| `SBOM.md`, `sbom/` | software bill of materials: human-readable page + machine-readable CycloneDX 1.6 |

Not tracked in git by design: GSP firmware blobs, decompiled firmware output,
local analysis material, VM disks/ISOs and Ghidra databases.

## Quick start

```bash
git clone https://git.vgpu.io/open-iov.git
cd open-iov
./install.sh deps nvidia firmware build   # build/runtime deps, NVIDIA modules, firmware, build
./scripts/stack_manager.sh up             # load stack + create a virtual GPU (mdev)
./scripts/stack_manager.sh qemu           # launch the reference guest
```

`stack_manager.sh` enforces the required build and load order; see
[Install and first run](docs/02-getting-started/01-install-and-first-run.md)
for the manual equivalents, the guest driver install, and troubleshooting.

Requirements: Ubuntu 22.04/24.04 x86_64, IOMMU enabled, a supported NVIDIA GPU
(see the [hardware matrix](docs/06-portability/hardware-software-matrix.md)), a
working host NVIDIA driver, kernel headers, QEMU.

## Status

Initialization works end to end for a stock 570.144 Linux guest on 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 actually execute on real hardware — is the active work item.
The honest, detailed state is maintained in
[docs/04-implementation/01-known-knowns-and-unknowns.md](docs/04-implementation/01-known-knowns-and-unknowns.md).

## How this differs from what exists

* **No licenses.** BSD-3-Clause for the reusable project (GPL-2.0 for kernel
  modules that link GPL-only kernel interfaces).
* **No patches** to guest drivers, host drivers, firmware, hypervisors or
  device models — that is the project's rule, not an aspiration.
* **Multi-tenant by design**: several VMs per GPU, IOMMU-isolated, with
  explicit scheduling.
* **Independent IP block**: designed to attach to KVM, Xen, Argo, OpenXT,
  Qubes OS Air and future hypervisors, on x86_64 and aarch64 hosts, Turing
  through Grace-Blackwell/GB10, without changes to the emulation core.

## Ecosystem

Open-IOV is the GPU component of **HAAEEP** — a High Assurance Agent Edge
Environment Platform where agents, model servers and infrastructure VMs each
live in their own VM on one GPU, with local inference and no cloud dependency.
See [HAAEEP and collaboration](docs/08-ecosystem/haaeep-and-collaboration.md).

We explicitly do **not** replace bare-metal vLLM continuous batching for
centralized inference; that remains the right answer at datacenter scale.
Open-IOV serves the cases that need compute *inside* guests: Windows and Linux
CUDA, 3D graphics, and secure edge isolation.

## License

BSD-3-Clause for the project; GPL-2.0 for kernel modules.
See [LICENSE](LICENSE) and
[docs/09-reference/legal-and-licensing.md](docs/09-reference/legal-and-licensing.md).