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

diff --git a/docs/04-implementation/02-practical-challenges-and-adversarial-interop.md b/docs/04-implementation/02-practical-challenges-and-adversarial-interop.md
new file mode 100644
index 0000000..1deff02
--- /dev/null
+++ b/docs/04-implementation/02-practical-challenges-and-adversarial-interop.md
@@ -0,0 +1,156 @@
+# Practical Challenges and Adversarial Interoperability
+
+> How we intend to implement compute/CUDA support *fast and correctly*, and the
+> discipline that keeps the whole stack unmodified — ours included.
+
+## 1. The central engineering bet
+
+> Emulate the interface. Pass through the work. Never patch anyone.
+
+Everything below follows from taking that seriously. It forces hard choices
+(no "just add a flag to the guest driver"), and it pays for itself by making
+the project portable, maintainable and legally clean.
+
+## 2. Fast and correct: the tension
+
+### 2.1 What "correct" means here
+
+Correctness is not "no crash". It is:
+
+* the guest observes the same **values** (capabilities, handles, table
+  contents) it would on real hardware,
+* the guest observes the same **ordering** (completions happen after the work
+  they signal; faults arrive before replays),
+* the guest observes the same **failure semantics** (errors are surfaced, not
+  swallowed),
+* and the work produces the same **results** (a CUDA kernel's output matches
+  native execution).
+
+### 2.2 What "fast" means here
+
+Two budgets matter, and they are different:
+
+* **Initialization latency** — how long from VM start to CUDA ready. Dominated
+  by RPC round-trips and guest driver's own work. Target: within 2× of physical
+  device initialization in the same guest.
+* **Steady-state throughput/latency** — kernel launch overhead, copy
+  bandwidth, and completion latency. Target: published, stable, and within an
+  agreed factor of native for each supported operation class.
+
+We will publish the methodology and the numbers together; a performance claim
+without a methodology is not accepted in this project.
+
+### 2.3 The fast paths
+
+* **Pure state operations** (semaphores, membar, fences, some memops) are
+  satisfied in the emulation directly — they are microseconds in hardware and
+  would otherwise cost a round trip to the physical GPU and back.
+* **Management operations** (object creation, capability queries, mappings)
+  are answered from cached/derived state where the hardware has no side effects
+  the guest can observe.
+* **Real work** (grid launches, copies) is forwarded. Nothing else is allowed
+  on the hot path.
+
+## 3. Forwarding: the three options and how we choose
+
+```
+   (A) Host RM/GSP proxy
+       guest push → translate → host driver's RM API → real channel → GPU
+       + reuses a mature driver's knowledge
+       − extra hop, depends on host driver interfaces
+
+   (B) Direct engine submission
+       guest push → translate → our own channel/push construction → GPU
+       + lowest latency, no host driver dependency
+       − we must own page tables, scheduling, invalidation, completion
+
+   (C) Hybrid
+       management via (A), hot path via (B)
+```
+
+**Decision procedure:** prototype (A) first to get *correct* execution, with
+measurement harnesses around it. Then measure the overhead. If the overhead
+violates the budgets in §2.2 for the target workloads, implement (B) for the
+hot path and keep (A) for management. The architecture must not preclude
+either, so the work path is abstracted behind an interface from day one.
+
+## 4. Hard problems we must solve, and our stance on each
+
+| Problem | Stance |
+|---|---|
+| **Page tables on both sides** | We populate server-owned ranges using the layout the client hands us and the entry encodings from AMAP/HAL references; a validator compares our tables against what the guest expects before enabling a channel. |
+| **Memory coherence** | Guest sysmem is coherent by construction (same physical pages); VRAM objects must be migrated to real VRAM or DMA-mapped. Phase 2 picks per-object policy with correctness first. |
+| **Scheduling between tenants** | One real GPU, N guest channels — schedule explicitly (time-slice/partition), measure fairness, audit isolation. Never let the guest's own scheduler influence another tenant. |
+| **Fault handling** | Reproduce faults under forwarding, implement replay/cancel on the guest's terms, and make fault latency measurable. |
+| **State explosion** | Drivers create enormous state. We do not model all of it — we model what the guest *observes*, and forward what it *uses*. Anything unobserved stays unmodeled. |
+| **Version drift** | Version-keyed handlers with a configuration-driven profile per (driver, firmware) family; new versions added by measurement, never by guessing. |
+| **Security of the debug tooling** | Debug parameters are development-grade; the productized build keeps only read-only diagnostics and gates destructive ones behind explicit opt-in. |
+
+## 5. Adversarial interoperability
+
+### 5.1 The rule
+
+**No modification is permitted in any component we do not own**: guest driver,
+host driver, GPU firmware, hypervisor, device model, guest OS.
+
+Why so absolute: every permitted exception becomes a maintenance liability that
+scales with the number of versions in the field. A patch to the guest driver
+means maintaining forks for every guest OS and driver version. A patch to the
+hypervisor means every hypervisor project must carry it. A firmware change is
+impossible in practice.
+
+### 5.2 How compliance is verified
+
+* **Contract tests**: CI builds run against *stock* drivers obtained from
+  distribution repositories (or vendor runfiles), and against *unmodified*
+  hypervisor packages.
+* **No-patch checks**: our build must not depend on any patch file for
+  third-party components. Where patches exist in the tree for convenience
+  (e.g. build glue), the contract tests must pass without them; anything that
+  fails this is a bug.
+* **Behavioral equivalence**: where we answer from emulation, we validate the
+  values against traces from real hardware (or from our decompiled study notes) —
+  not against our own previous answers.
+
+### 5.3 What we *can* change
+
+* Our own module, userspace library, tools, scripts and docs.
+* Configuration: device profiles, version profiles, capability tables.
+* Tests and harnesses.
+
+### 5.4 Where the line gets tested
+
+* **Firmware signatures**: the driver verifies firmware. We satisfy the
+  handshake by *emulating the interface*, not by patching the image or the
+  driver.
+* **PCI IDs and VBIOS**: the guest driver decides how to treat the device from
+  what it reads. We present a coherent device; we never rely on the driver
+  skipping checks.
+* **Licensing checks**: our device is our device; we do not impersonate a
+  licensed product. Interoperability is the goal, not circumvention of a
+  vendor's own licensing for their own products.
+
+## 6. Why this approach is durable
+
+Because our artifacts are:
+
+* **Interface definitions** (protocol tables, structures) — survive versions.
+* **Measured contracts** (what the guest observes) — survive reimplementation.
+* **Configuration** (profiles per version/hardware) — survive hardware.
+* **Tests** (contract ladders) — catch drift immediately.
+
+A new driver version or GPU is therefore *data + verification*, not a rewrite —
+the difference between a hobby project and infrastructure.
+
+## 7. The "thrilling" part (for developers)
+
+If you are reading this to decide whether to work on it: this project is one of
+the few places where you can:
+
+* reverse engineer a 28 MB RISC-V firmware and turn it into maintainable C,
+* design a memory model that makes two different address-space owners agree,
+* build a virtualization path for the most commercially important accelerator
+  on Earth, under a permissive license,
+* and have your work outlive the hardware generation you started on.
+
+Start with [`../07-developers/onboarding-and-standards.md`](../07-developers/onboarding-and-standards.md).