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

diff --git a/tools/debug/nv2080_ctrl.sh b/tools/debug/nv2080_ctrl.sh
new file mode 100755
index 0000000..22c7117
--- /dev/null
+++ b/tools/debug/nv2080_ctrl.sh
@@ -0,0 +1,168 @@
+#!/bin/bash
+# NV2080 Control Command Tool
+# Sends NV2080 RM control commands to the NVIDIA kernel module via ioctl
+# Usage: ./nv2080_ctrl.sh <device_fd> <command> [params...]
+
+set -euo pipefail
+
+# NV2080 Control Command Definitions (from ctrl2080unix.h and ctrl2080vgpumgrinternal.h)
+# These are the same commands used by GVM userspace via NV_CTRL_RES ioctl
+
+# NV2080_CTRL_CMD_OS_UNIX_GC6_BLOCKER_REFCNT (0x20803d01)
+# Params: action (INC=1, DEC=2)
+NV2080_CTRL_CMD_OS_UNIX_GC6_BLOCKER_REFCNT=0x20803d01
+NV2080_CTRL_OS_UNIX_GC6_BLOCKER_REFCNT_INC=1
+NV2080_CTRL_OS_UNIX_GC6_BLOCKER_REFCNT_DEC=2
+
+# NV2080_CTRL_CMD_OS_UNIX_ALLOW_DISALLOW_GCOFF (0x20803d02)
+# Params: action (ALLOW=1, DISALLOW=2)
+NV2080_CTRL_CMD_OS_UNIX_ALLOW_DISALLOW_GCOFF=0x20803d02
+NV2080_CTRL_OS_UNIX_ALLOW_DISALLOW_GCOFF_ALLOW=1
+NV2080_CTRL_OS_UNIX_ALLOW_DISALLOW_GCOFF_DISALLOW=2
+
+# NV2080_CTRL_CMD_OS_UNIX_AUDIO_DYNAMIC_POWER (0x20803d03)
+# Params: bEnter (true/false)
+NV2080_CTRL_CMD_OS_UNIX_AUDIO_DYNAMIC_POWER=0x20803d03
+
+# NV2080_CTRL_CMD_OS_UNIX_INSTALL_PROFILER_HOOKS (0x20803d04)
+NV2080_CTRL_CMD_OS_UNIX_INSTALL_PROFILER_HOOKS=0x20803d04
+
+# NV2080_CTRL_CMD_OS_UNIX_FLUSH_SNAPSHOT_BUFFER (0x20803d05)
+NV2080_CTRL_CMD_OS_UNIX_FLUSH_SNAPSHOT_BUFFER=0x20803d05
+
+# NV2080_CTRL_CMD_OS_UNIX_STOP_PROFILER (0x20803d06)
+NV2080_CTRL_CMD_OS_UNIX_STOP_PROFILER=0x20803d06
+
+# NV2080_CTRL_CMD_OS_UNIX_VIDMEM_PERSISTENCE_STATUS (0x20803d07)
+NV2080_CTRL_CMD_OS_UNIX_VIDMEM_PERSISTENCE_STATUS=0x20803d07
+
+# NV2080_CTRL_CMD_OS_UNIX_UPDATE_TGP_STATUS (0x20803d08)
+NV2080_CTRL_CMD_OS_UNIX_UPDATE_TGP_STATUS=0x20803d08
+
+# VGPU Manager Internal Commands
+NV2080_CTRL_CMD_VGPU_MGR_INTERNAL_BOOTLOAD_GSP_VGPU_PLUGIN_TASK=0x20804001
+NV2080_CTRL_CMD_VGPU_MGR_INTERNAL_SHUTDOWN_GSP_VGPU_PLUGIN_TASK=0x20804002
+NV2080_CTRL_CMD_VGPU_MGR_INTERNAL_PGPU_ADD_VGPU_TYPE=0x20804003
+NV2080_CTRL_CMD_VGPU_MGR_INTERNAL_ENUMERATE_VGPU_PER_PGPU=0x20804004
+NV2080_CTRL_CMD_VGPU_MGR_INTERNAL_CLEAR_GUEST_VM_INFO=0x20804005
+NV2080_CTRL_CMD_VGPU_MGR_INTERNAL_GET_VGPU_FB_USAGE=0x20804006
+NV2080_CTRL_CMD_VGPU_MGR_INTERNAL_SET_VGPU_ENCODER_CAPACITY=0x20804007
+NV2080_CTRL_CMD_INTERNAL_VGPU_PLUGIN_CLEANUP=0x20804008
+
+# NV_IOCTL_MAGIC and NV_ESC_RM_CONTROL
+NV_IOCTL_MAGIC=0x46
+NV_ESC_RM_CONTROL=0x54
+
+# NV_CTRL_RES = _IOWR(NV_IOCTL_MAGIC, NV_ESC_RM_CONTROL, NVOS54_PARAMETERS)
+NV_CTRL_RES=$(printf "0x%x" $(( (2 << 30) | (NV_IOCTL_MAGIC << 8) | (NV_ESC_RM_CONTROL) | (128 << 16) )))
+
+# Helper to send ioctl
+send_ioctl() {
+    local fd=$1
+    local cmd=$2
+    local data=$3
+    local size=$4
+    
+    # This would need a C program to actually send the ioctl
+    # For now, we document the commands
+    echo "Command: 0x$(printf "%x" $cmd)"
+    echo "Data size: $size"
+}
+
+# Main command dispatcher
+case "${1:-help}" in
+    gc6-inc)
+        echo "Increment GC6 blocker refcount"
+        echo "ioctl(fd, NV_CTRL_RES, {cmd: $NV2080_CTRL_CMD_OS_UNIX_GC6_BLOCKER_REFCNT, action: $NV2080_CTRL_OS_UNIX_GC6_BLOCKER_REFCNT_INC})"
+        ;;
+    gc6-dec)
+        echo "Decrement GC6 blocker refcount"
+        echo "ioctl(fd, NV_CTRL_RES, {cmd: $NV2080_CTRL_CMD_OS_UNIX_GC6_BLOCKER_REFCNT, action: $NV2080_CTRL_OS_UNIX_GC6_BLOCKER_REFCNT_DEC})"
+        ;;
+    gcoff-allow)
+        echo "Allow GCOFF"
+        echo "ioctl(fd, NV_CTRL_RES, {cmd: $NV2080_CTRL_CMD_OS_UNIX_ALLOW_DISALLOW_GCOFF, action: $NV2080_CTRL_OS_UNIX_ALLOW_DISALLOW_GCOFF_ALLOW})"
+        ;;
+    gcoff-disallow)
+        echo "Disallow GCOFF"
+        echo "ioctl(fd, NV_CTRL_RES, {cmd: $NV2080_CTRL_CMD_OS_UNIX_ALLOW_DISALLOW_GCOFF, action: $NV2080_CTRL_OS_UNIX_ALLOW_DISALLOW_GCOFF_DISALLOW})"
+        ;;
+    audio-power)
+        echo "Audio dynamic power: $2"
+        ;;
+    profiler-install)
+        echo "Install profiler hooks"
+        ;;
+    profiler-flush)
+        echo "Flush snapshot buffer"
+        ;;
+    profiler-stop)
+        echo "Stop profiler"
+        ;;
+    vidmem-persistence)
+        echo "Query vidmem persistence status"
+        ;;
+    tgp-status)
+        echo "Update TGP status: $2"
+        ;;
+    vgpu-bootload)
+        echo "Bootload GSP VGPU plugin task"
+        echo "Params: dbdf, gfid, vgpuType, vmPid, swizzId, numChannels, numPluginChannels, bDisableSmcPartitionRestore, guestFbPhysAddrList, guestFbLengthList, pluginHeapMemoryPhysAddr, pluginHeapMemoryLength, ctrlBuffOffset"
+        ;;
+    vgpu-shutdown)
+        echo "Shutdown GSP VGPU plugin task"
+        echo "Params: gfid"
+        ;;
+    vgpu-add-type)
+        echo "Add vGPU type to pGPU"
+        echo "Params: discardVgpuTypes, vgpuInfo"
+        ;;
+    vgpu-enumerate)
+        echo "Enumerate vGPUs per pGPU"
+        ;;
+    vgpu-clear-guest)
+        echo "Clear guest VM info"
+        echo "Params: gfid"
+        ;;
+    vgpu-fb-usage)
+        echo "Get vGPU FB usage"
+        ;;
+    vgpu-encoder-cap)
+        echo "Set vGPU encoder capacity"
+        echo "Params: gfid, encoderCapacity (0-100)"
+        ;;
+    vgpu-plugin-cleanup)
+        echo "Cleanup VGPU plugin"
+        echo "Params: gfid"
+        ;;
+    list)
+        echo "Available NV2080 Control Commands:"
+        echo "  OS Unix Commands:"
+        echo "    gc6-inc           - Increment GC6 blocker refcount"
+        echo "    gc6-dec           - Decrement GC6 blocker refcount"
+        echo "    gcoff-allow       - Allow GCOFF"
+        echo "    gcoff-disallow    - Disallow GCOFF"
+        echo "    audio-power       - Audio dynamic power (enter/exit)"
+        echo "    profiler-install  - Install profiler hooks (HWPM)"
+        echo "    profiler-flush    - Flush snapshot buffer"
+        echo "    profiler-stop     - Stop profiler"
+        echo "    vidmem-persistence- Query vidmem persistence status"
+        echo "    tgp-status        - Update TGP status"
+        echo ""
+        echo "  VGPU Manager Internal Commands:"
+        echo "    vgpu-bootload     - Bootload GSP VGPU plugin task"
+        echo "    vgpu-shutdown     - Shutdown GSP VGPU plugin task"
+        echo "    vgpu-add-type     - Add vGPU type to pGPU"
+        echo "    vgpu-enumerate    - Enumerate vGPUs per pGPU"
+        echo "    vgpu-clear-guest  - Clear guest VM info"
+        echo "    vgpu-fb-usage     - Get vGPU FB usage"
+        echo "    vgpu-encoder-cap  - Set vGPU encoder capacity"
+        echo "    vgpu-plugin-cleanup - Cleanup VGPU plugin"
+        ;;
+    help|*)
+        echo "NV2080 Control Command Tool"
+        echo "Usage: $0 <command> [args...]"
+        echo ""
+        echo "Run '$0 list' to see all available commands"
+        ;;
+esac
\ No newline at end of file