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, 92 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8efbe25
--- /dev/null
+++ b/README.md
@@ -0,0 +1,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).