1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
# 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 |
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).
|
