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

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..f3f71a9
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,274 @@
+# Open-IOV CI/CD Pipeline
+
+name: Open-IOV CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master, develop]
+
+env:
+  KERNEL_VERSION: ${{ matrix.kernel }}
+  GCC_VERSION: ${{ matrix.gcc }}
+  GSP_VERSION: '570.144'
+  FW_RAW_BASE: https://raw.githubusercontent.com/NVIDIA/linux-firmware/2237b99e29d09bebffdb706ae05005d9026fd7e4/nvidia/tu102/gsp
+  FW_MD5: 13ce12a392a31eeb79a2e6ebd3a4a93a
+
+jobs:
+  # ============================================================
+  # Kernel Build & Test Matrix
+  # ============================================================
+  kernel-test:
+    name: Kernel ${{ matrix.kernel }} / GCC ${{ matrix.gcc }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        kernel: ['6.1', '6.6', '6.8']
+        gcc: ['11', '12', '13']
+        include:
+          - kernel: '6.1'
+            gcc: '11'
+            kernel_package: 'linux-headers-6.1.0-18-generic'
+          - kernel: '6.6'
+            gcc: '12'
+            kernel_package: 'linux-headers-6.6.0-14-generic'
+          - kernel: '6.8'
+            gcc: '13'
+            kernel_package: 'linux-headers-6.8.0-48-generic'
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install kernel headers
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ${{ matrix.kernel_package }} build-essential gcc-${{ matrix.gcc }} kunit
+
+      - name: Set GCC
+        run: |
+          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-${{ matrix.gcc }} 100
+          gcc --version
+
+      - name: Fetch GSP firmware (linux-firmware)
+        run: |
+          mkdir -p firmware/57X-GSP/570.144
+          curl -fSL --retry 3 -o firmware/57X-GSP/570.144/gsp-${{ env.GSP_VERSION }}.bin \
+            "${{ env.FW_RAW_BASE }}/gsp-${{ env.GSP_VERSION }}.bin"
+          objcopy -O binary --only-section=.fwimage \
+            firmware/57X-GSP/570.144/gsp-${{ env.GSP_VERSION }}.bin \
+            firmware/57X-GSP/570.144/gsp-${{ env.GSP_VERSION }}.fwimage.bin
+          echo "${{ env.FW_MD5 }}  firmware/57X-GSP/570.144/gsp-${{ env.GSP_VERSION }}.fwimage.bin" | md5sum -c -
+
+      - name: Build host kernel module
+        run: make kernel
+
+      - name: Build legacy guest driver
+        run: make -C driver KDIR=/lib/modules/$(uname -r)/build
+
+      - name: Build kernel tests
+        run: make -C kernel/tests KDIR=/lib/modules/$(uname -r)/build
+
+      - name: Run comprehensive test module
+        run: |
+          cd kernel/tests
+          sudo insmod gsp_vgpu_comprehensive_test.ko
+          sleep 2
+          dmesg -T | tail -50
+          sudo rmmod gsp_vgpu_comprehensive_test
+
+      - name: Run KUnit tests
+        if: matrix.kernel == '6.6' && matrix.gcc == '12'
+        run: |
+          cd kernel/tests
+          sudo insmod gsp_vgpu_kunit_test.ko
+          sleep 2
+          dmesg -T | grep -E "(kunit|KUNIT|PASS|FAIL)" | tail -50
+          sudo rmmod gsp_vgpu_kunit_test
+
+      - name: Run mock tests
+        run: |
+          cd kernel/tests
+          sudo insmod gsp_vgpu_mock_test.ko
+          sleep 2
+          dmesg -T | grep -E "(PASS|FAIL|Test Results)" | tail -50
+          sudo rmmod gsp_vgpu_mock_test
+
+  # ============================================================
+  # Firmware Validation (fetched from linux-firmware.git)
+  # ============================================================
+  firmware-validation:
+    name: Firmware Validation
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Fetch and extract firmware
+        run: |
+          mkdir -p firmware/57X-GSP/570.144
+          curl -fSL --retry 3 -o firmware/57X-GSP/570.144/gsp-${{ env.GSP_VERSION }}.bin \
+            "${{ env.FW_RAW_BASE }}/gsp-${{ env.GSP_VERSION }}.bin"
+          objcopy -O binary --only-section=.fwimage \
+            firmware/57X-GSP/570.144/gsp-${{ env.GSP_VERSION }}.bin \
+            firmware/57X-GSP/570.144/gsp-${{ env.GSP_VERSION }}.fwimage.bin
+
+      - name: Verify firmware MD5
+        run: |
+          cd firmware/57X-GSP/570.144
+          actual=$(md5sum gsp-${{ env.GSP_VERSION }}.fwimage.bin | cut -d' ' -f1)
+          echo "Expected: ${{ env.FW_MD5 }}"
+          echo "Actual:   $actual"
+          [ "$actual" = "${{ env.FW_MD5 }}" ]
+          echo "MD5 verified"
+
+      - name: Verify firmware size
+        run: |
+          cd firmware/57X-GSP/570.144
+          size=$(stat -c%s gsp-${{ env.GSP_VERSION }}.fwimage.bin)
+          echo "Size: $size bytes"
+          if [ "$size" -lt 28000000 ] || [ "$size" -gt 31000000 ]; then
+            echo "Unexpected firmware size!"
+            exit 1
+          fi
+          echo "Size verified"
+
+  # ============================================================
+  # Documentation Validation
+  # ============================================================
+  docs-validation:
+    name: Documentation Validation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check wiki files exist
+        run: |
+          cd wiki
+          required=(
+            "GSP-570.144W-Firmware-Analysis.md"
+            "RPC-Message-Format.md"
+            "BAR-Emulation-Specification.md"
+            "WPR-Management.md"
+            "Migration-Protocol.md"
+            "vGPU-IO-Integration-Guide.md"
+            "Address-Reference.md"
+            "Error-Codes.md"
+            "Glossary.md"
+            "README.md"
+          )
+          for f in "${required[@]}"; do
+            if [ ! -f "$f" ]; then
+              echo "Missing: $f"
+              exit 1
+            fi
+            echo "Found: $f"
+          done
+
+      - name: Validate markdown syntax
+        run: |
+          cd wiki
+          for f in *.md; do
+            if ! head -1 "$f" | grep -q "^#"; then
+              echo "Warning: $f missing H1 header"
+            fi
+          done
+
+      - name: Check cross-references
+        run: |
+          cd wiki
+          for f in *.md; do
+            grep -o '\[.*\](.*\.md)' "$f" | while read link; do
+              target=$(echo "$link" | sed -n 's/.*(\(.*\))/\1/p')
+              if [ ! -f "$target" ]; then
+                echo "Broken link in $f: $target"
+                exit 1
+              fi
+            done
+          done
+
+  # ============================================================
+  # Static Analysis
+  # ============================================================
+  static-analysis:
+    name: Static Analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y linux-headers-$(uname -r) cppcheck
+
+      - name: Run checkpatch on host kernel module
+        run: |
+          cd kernel
+          find . -name "*.c" -o -name "*.h" | xargs /usr/src/linux-headers-$(uname -r)/scripts/checkpatch.pl --no-tree --strict || true
+
+      - name: Run cppcheck
+        run: |
+          cd kernel
+          cppcheck --enable=all --std=c11 --force -I include . 2>&1 | head -100 || true
+
+  # ============================================================
+  # Userspace Test Build
+  # ============================================================
+  userspace-build:
+    name: Userspace Build Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Build userspace
+        run: make userspace examples
+
+      - name: Build userspace tests
+        run: make -C userspace/tests
+
+      - name: Verify binary
+        run: |
+          cd userspace/tests
+          ./test_vgpu_userspace 2>&1 | head -20 || true
+          # Expected to fail without driver, but should run
+
+  # ============================================================
+  # Integration Test (requires hardware - manual trigger)
+  # ============================================================
+  integration-test:
+    name: Integration Test (Manual)
+    runs-on: [self-hosted, gpu, nvidia]
+    if: github.event_name == 'workflow_dispatch'
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Full install
+        run: ./install.sh --no-load
+
+      - name: Run full integration test
+        run: sudo ./tools/test/run_integration_tests.sh all
+
+# ============================================================
+# Workflow Permissions
+# ============================================================
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write