From 68cdd7728a7cc6715bbbff7decfe2b11c3bdf558 Mon Sep 17 00:00:00 2001
From: Open-IOV <dev@open-iov.org>
Date: Wed, 23 Sep 2026 05:44:08 -0400
Subject: 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.
---
 docs/tools/README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docs/tools/README.md

(limited to 'docs/tools/README.md')

diff --git a/docs/tools/README.md b/docs/tools/README.md
new file mode 100644
index 0000000..232fbe5
--- /dev/null
+++ b/docs/tools/README.md
@@ -0,0 +1,80 @@
+# Open-IOV Tools Documentation
+
+## Overview
+This directory contains documentation for userspace tools built on top of the
+Open-IOV vGPU-IO stack. The RM-API tooling reuses behaviour and interfaces
+from the driver components we studied by reverse engineering and decompilation
+(tracked docs describe components and behaviour).
+
+## Tools
+
+### Debugging & Observability (Implemented)
+| Tool | Location | Description |
+|------|----------|-------------|
+| `guest_init_monitor.py` | `tools/` | Correlates host dmesg with guest serial output |
+| `failure_analyzer.py` | `tools/` | Classifies guest init failures with recommendations |
+| `benchmark_infrastructure.sh` | `tools/` | VM vs bare metal benchmark runner |
+| `guest_test_agent.py` | `tools/guest_agent/` | Guest-side test agent (vsock/TCP) |
+| `debug_guest_init.sh` | `scripts/` | One-command debug launch (QEMU + GDB + monitor) |
+| `windows_guest_automation.sh` | `scripts/` | Windows guest automation via WinRM |
+
+### RM API Tooling (Planned)
+| Tool | Documentation | Description |
+|------|---------------|-------------|
+| `rmtool` | [rmtool.md](rmtool.md) | RM API Swiss Army Knife - CLI for state enumeration, engine control, memory ops, NV2080 direct control |
+| `rmtop` | [rmtop.md](rmtop.md) | GPU htop equivalent - ncurses real-time dashboard |
+
+## Code Reuse Sources (component level)
+
+All planned tools reuse the driver components we studied. Tracked
+documentation refers to them by component only:
+
+| Component | Use Case |
+|-----------|----------|
+| NVML / nvidia-smi component | CLI framework, GPU enumeration, NV2080 ioctls |
+| gpumon / perfmon component | Performance sampling, perfmon counters |
+| NV2080 control component | RM control interfaces (classes, methods, events) |
+| Resource server component | Resource Server (resserve) API |
+| CUDA software (CUDASW) component | CUDA internal layer behaviours |
+| Resource manager component | Resman API |
+
+## Build Integration
+Tools will be built under `open-iov/tools/`:
+```
+tools/
+├── rmtool/
+│   ├── src/
+│   ├── lib/
+│   └── Makefile
+├── rmtop/
+│   ├── src/
+│   ├── lib/
+│   └── Makefile
+└── Makefile          # Builds all tools
+```
+
+## Dependencies
+- `libnvidia-rmapi.so` - reused RM API layer (component level)
+- `libgpumon.so` - reused perfmon layer (component level)
+- `libpciaccess` - PCI configuration access
+- `libnuma` - NUMA topology
+- `ncursesw` - rmtop UI (wide character support)
+- `libjson-c` - JSON output formatting
+- `libcurl` - Remote API (future)
+
+## Integration with Open-IOV Stack
+Tools will integrate with the host VFIO driver via:
+- `/dev/nvidia*` character devices (existing nvidia.ko)
+- `open-iov-vfio.ko` debugfs interface (`/sys/kernel/debug/open-iov-vfio/`)
+- VFIO ioctls for guest state introspection
+- GSP-RM telemetry via firmware analyzer / dynamic dispatcher
+
+## Future Tool Ideas
+| Tool | Purpose |
+|------|---------|
+| `rmmigrate` | Live migration coordinator via resserve |
+| `rmprofile` | Workload profiler (CUDA/Video/AI correlation) |
+| `rmpolicy` | Policy engine for automated engine allocation |
+| `rmtelemetry` | Telemetry exporter (Prometheus/OTel/InfluxDB) |
+| `rmguest` | Guest introspection via vGPU VFIO interface |
+| `rmfirmware` | GSP firmware analysis / update utility |
\ No newline at end of file
-- 
cgit v1.2.3