From 0054d3acbc3017d2a535239f8153d3c99f7abc18 Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Fri, 2 Oct 2026 02:50:38 -0400 Subject: docs: add complete SBOM, ignore local deployment resources, remove stale third-party references --- SBOM.md | 246 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 SBOM.md (limited to 'SBOM.md') diff --git a/SBOM.md b/SBOM.md new file mode 100644 index 0000000..5182376 --- /dev/null +++ b/SBOM.md @@ -0,0 +1,246 @@ +# Open-IOV — Software Bill of Materials (SBOM) + +> **Format:** CycloneDX 1.6 (machine-readable: [`sbom/open-iov-0.1.0.cdx.json`](sbom/open-iov-0.1.0.cdx.json)) + +> this human-readable page. The document follows the NTIA *Minimum Elements for +> a Software Bill of Materials* and is suitable for commercial review, +> procurement, vulnerability management and regulatory submission (see §9). +> SPDX 2.3 can be produced from the CycloneDX document with standard tooling on +> request. + +| Field | Value | +|---|---| +| **SBOM document name** | Open-IOV SBOM | +| **SBOM version** | 1 | +| **SBOM serial (URN)** | `urn:uuid:e626c5a1-9697-4546-bb2b-5b4feb58e922` | +| **Created (UTC)** | 2026-10-02T06:47:39Z | +| **Created by** | The Open-IOV Project (automated inventory audit of the tracked tree) | +| **Primary component** | Open-IOV virtual GSP/vGPU stack | +| **Primary version** | `0.1.0` (`OPEN_IOV_VFIO_VERSION` in `kernel/include/nvidia-vgpu-vfio.h`) | +| **Primary license** | BSD-3-Clause (kernel side: GPL-2.0; see §8) | +| **Repository** | | +| **Scope** | All files tracked in the repository, plus the external components required to build, run and support it | +| **Distribution** | Firmware images, GPU drivers, hypervisors and guest OS images are **not distributed** in this repository (see §2 and §8) | + +--- + +## 1. Primary component + +**Open-IOV** is an open-source virtualization layer for NVIDIA GPUs. It lets an +unmodified NVIDIA guest driver run in a VM by emulating the GPU System +Processor (GSP) and its resource-manager firmware interface (GSP-RM) in a host +kernel module, and by arranging for guest work to execute on the physical GPU. + +* Supplier: The Open-IOV Project +* Version: `0.1.0` — defined by `OPEN_IOV_VFIO_VERSION` in + `kernel/include/nvidia-vgpu-vfio.h` +* Unique ID: `pkg:generic/open-iov@0.1.0` +* License: BSD-3-Clause (see `LICENSE`) +* Source revision: audited from the parent of the commit that adds this + document; the repository history is the authoritative record (`git log`) + +## 2. Scope, conventions and exclusions + +* **Included:** every first-party component and every third-party file tracked + in the repository (including vendored sources, generated analysis data and + prebuilt tools that are tracked). +* **Documented but not distributed:** external build/run dependencies (§6) — + NVIDIA drivers and GSP firmware, the Linux kernel, QEMU/KVM, GNU toolchain, + Python, Ghidra, CUDA toolkit, guest operating systems, and so on. +* **Third-party media in the historical wiki archive** (§5): the `wiki/` tree + is an archived scrape of the project's earlier public wiki. It includes + diagrams and logos whose provenance is third-party; they are historical + documentation, not part of the runnable software. Their licenses are + reported as `NOASSERTION` unless a per-file license exists. +* **Not tracked, not shipped:** `firmware/**/*.bin`, decompiled output, + local source checkouts, VM disk images, SDK headers and local notes are + gitignored and are not part of this SBOM's software payload. +* Components are identified with Package URLs (`pkg:…`) where an ecosystem + identifier exists; tracked files carry SHA-256 hashes in the machine SBOM. + +## 3. First-party components + +All first-party components are © 2026 The Open-IOV Project and licensed +**BSD-3-Clause** unless the per-file `SPDX-License-Identifier` states otherwise. +The kernel module is **GPL-2.0** (see §8). + +| Component | Version | License | Location | Unique ID | Contents / purpose | +|---|---|---|---|---|---| +| `open-iov-vfio` kernel module | 0.1.0 | GPL-2.0 | `kernel/**` | `pkg:generic/open-iov-vfio@0.1.0` | Host VFIO mdev driver + emulated GSP/GSP-RM, semaphore service, memory model, physical-GPU backend, BAR/MSI-X emulation, mdev/VFIO lifecycle | +| `libiov` userspace library | 0.1.0 | BSD-3-Clause | `userspace/lib/**`, `userspace/include/libvgpu.h` | `pkg:generic/libiov@0.1.0` | Management library (`libiov.so`) + `libvgpu.so` compatibility link, RPC emulation helpers, pkg-config metadata | +| `example_vgpu` example | 0.1.0 | BSD-3-Clause | `userspace/examples/**` | `pkg:generic/open-iov-example@0.1.0` | Minimal library usage example and build files | +| Userspace tests | 0.1.0 | BSD-3-Clause | `userspace/tests/**` | `pkg:generic/open-iov-userspace-tests@0.1.0` | Userspace VF management tests | +| Kernel tests | 0.1.0 | GPL-2.0 | `kernel/tests/**` | `pkg:generic/open-iov-kernel-tests@0.1.0` | In-kernel unit/smoke tests | +| Guest diagnostics suite | 0.1.0 | BSD-3-Clause | `tools/guest-diag/**` | `pkg:generic/open-iov-guest-diag@0.1.0` | VM cycle harness, kprobes, pin scanners, CUDA smoke test wrappers, QEMU launch snapshots (internal tooling; may invoke an optional external VM manager) | +| CUDA A/B harness | 0.1.0 | BSD-3-Clause | `tools/cuda-ab/**` | `pkg:generic/open-iov-cuda-ab@0.1.0` | Host-vs-guest `vector_add` comparison harness (`vector_add.cu`, `ab.sh`, tracked prebuilt `run/vector_add`) | +| RM queue / WPR tools | 0.1.0 | BSD-3-Clause | `tools/rmq/**` | `pkg:generic/open-iov-rmq@0.1.0` | RM queue probes, WPR2 reset helper (+ companion kernel module), tracked prebuilt `wpr2_reset` | +| Ghidra analysis tooling | 0.1.0 | BSD-3-Clause | `tools/ghidra/**` | `pkg:generic/open-iov-ghidra-tools@0.1.0` | Scripts for firmware analysis under Ghidra (Ghidra itself is external, §6) | +| Guest test agent | 0.1.0 | BSD-3-Clause | `tools/guest_agent/**` | `pkg:generic/open-iov-guest-agent@0.1.0` | Optional guest-side test agent (may use PyTorch) | +| VM/module/debug tools | 0.1.0 | BSD-3-Clause | `tools/{vm,module_ops,debug,test}/**` | `pkg:generic/open-iov-tools-misc@0.1.0` | VM harness, module operations, debug and test helpers | +| GSP firmware analysis artifacts | 570.144W | BSD-3-Clause | `firmware/57X-GSP/570.144/**` | `pkg:generic/open-iov-gsp-analysis@570.144W` | Python analysis scripts, function/prologue maps, RPC handler maps, reports — the project's own work product; no NVIDIA binaries | +| CUDA userspace driver analysis | 570.144 | BSD-3-Clause | `userspace/cuda/**` | `pkg:generic/open-iov-cuda-analysis@570.144` | Documentation, decompilation tooling wrappers, Ghidra scripts and annotation tables for `libcuda.so.570.144` | +| Automation & build scripts | 0.1.0 | BSD-3-Clause | `scripts/**`, `install.sh`, `validate.sh`, `Makefile` | `pkg:generic/open-iov-scripts@0.1.0` | Install, build, VM harness, stack management and validation automation | +| Portability configuration | 0.1.0 | BSD-3-Clause | `config/**` | `pkg:generic/open-iov-config@0.1.0` | Hardware (Turing/Ampere/Blackwell) and driver-version (550/560/570/580) matrices | +| Documentation | 0.1.0 | BSD-3-Clause | `docs/**`, `README.md`, `STATE-CURRENT.md` | `pkg:generic/open-iov-docs@0.1.0` | Architecture, implementation, operations, portability, ecosystem and reference material | +| Project wiki archive | 2023 (imported) | BSD-3-Clause (third-party media excepted, §5) | `wiki/**` | `pkg:generic/open-iov-wiki-archive@2023` | Markdown wiki pages + archived HTML snapshot of the earlier project wiki | +| CI configuration | 0.1.0 | BSD-3-Clause | `.github/workflows/ci.yml` | `pkg:generic/open-iov-ci@0.1.0` | Build/test matrix (kernels 6.1/6.6/6.8, GCC 11/12/13) | + +### Tracked build artifacts (first-party) + +These prebuilt binaries are tracked in the tree. Their sources are present and +the hashes allow integrity verification. + +| File | SHA-256 | Built from | Toolchain | +|---|---|---|---| +| `tools/cuda-ab/run/vector_add` | `8edc28a8814f108a85b794ca4e636138de03f45f706cb96bd008f420a87e8036` | `tools/cuda-ab/vector_add.cu` | NVIDIA CUDA toolkit (external, §6); links libc only | +| `tools/rmq/wpr2_reset` | `cae6537a41f0e548349617a7c44f411dc5c38f16000ce1879ba49814e82c2361` | `tools/rmq/wpr2_reset.c` | GCC 13 / glibc | + +## 4. Bundled third-party components + +Third-party files tracked in the repository, with upstream project and license. +Hashes are SHA-256. + +| Component | Upstream | License | Files | SHA-256 | +|---|---|---|---|---| +| tomlc99 (TOML parser) | | MIT | `userspace/extern/src/toml.c`, `userspace/extern/inc/toml.h` | `ca70a545ce442d878587bb2767de8c7e6219b43ba832fa87c4b8a8c4f4f8221f`, `0c56ba78add80e49073b12de039835718c29410669d7a526e65bc8212e1dc135` | +| cargs (argument parser) | | MIT | `userspace/extern/src/cargs.c`, `userspace/extern/inc/cargs.h` | `d6c88f89b1d948f4b221c54103f17f6575bd580fcaffb0de3dfbceb2dd6136ab`, `93d3e1cb40d6eb646b7f50051ee9ad3f664ffe21d103164f98e89e9775bb91cb` | +| NVIDIA vGPU/VFIO interface headers | NVIDIA (public headers) | MIT | `kernel/include/nv-hypervisor.h` | `733409c43ab65708bf5563b76e4dea9d1dfbe1d5cfa0d846fbba511a1186f932` | +| NVIDIA vGPU/VFIO interface headers | NVIDIA (public headers) | MIT | `kernel/include/nv-vgpu-vfio-interface.h` | `83908a89a7f6df2631d24bb2518bbb5643c4f1fb270300d20b76a04a0af735b6` | +| NVIDIA vGPU/VFIO interface headers | NVIDIA (public headers) | MIT | `kernel/include/nvstatus.h` | `e8267172a1f7a56420d612c6734b3554b9ff6a3d33fdda21b1371ff4ce4b8675` | +| NVIDIA vGPU/VFIO interface headers | NVIDIA (public headers) | MIT | `kernel/include/nvtypes.h` | `e647e23504fe4b6cc2337836b2155c49918ed174bd9a3d806125e7c12e894f2a` | +| GPL-2.0 license text | FSF | License text (not software) | `userspace/LICENSE` | — | + +No NVIDIA source code, firmware image or binary driver is bundled: only +independently written code and public MIT-licensed interface headers. + +## 5. Archived documentation and media (third-party provenance) + +`wiki/` contains a historical scrape of the project's earlier wiki (year 2023) +plus current project wiki pages. It is documentation, not runnable software. + +* The project's own wiki pages are BSD-3-Clause. +* The archived HTML pages and images include **third-party diagrams, screenshots + and logos** produced by other projects/vendors (for example Intel, Red Hat, + NVIDIA, the Linux kernel community, Looking Glass and QEMU contributors). + These are retained for historical reference; their licenses are + `NOASSERTION` here and are governed by their originating projects. +* If any archived media must be redistributed under a specific license, obtain + it from the originating project; if an artifact is believed to be improperly + included, open an issue (the project would rather over-comply). + +## 6. External dependencies (required to build, run or support the software) + +These components are **not distributed** in this repository. Versions are those +the project develops and tests against; see `config/versions/*.yaml` and +`.github/workflows/ci.yml` for the supported matrix. + +### Runtime — virtualization platform + +| Component | Version | License | Role | +|---|---|---|---| +| Linux kernel | ≥ 6.1 (tested 6.8.0-142; CI 6.1/6.6/6.8) | GPL-2.0-only | Host kernel; VFIO, mdev, IOMMU and DMA interfaces | +| QEMU | distribution version | GPL-2.0 | VM monitor (q35 + `pcie-root-port` + `vfio-pci` mdev) | +| KVM | in-kernel | GPL-2.0 | Hardware virtualization | +| VFIO / mdev / IOMMUFD | in-kernel | GPL-2.0 | Device assignment and mediated devices | +| libvirt | distribution version | LGPL-2.1 | Optional management layer | +| OVMF | distribution version | BSD-2-Clause-Patent | UEFI firmware for guests (optional) | + +### Runtime — NVIDIA (proprietary, user-supplied; not distributed) + +| Component | Version | License | Role | +|---|---|---|---| +| NVIDIA guest driver (`nvidia.ko`, `libcuda.so`) | 570.144 | NVIDIA proprietary EULA | The unmodified guest driver Open-IOV serves | +| NVIDIA GSP firmware (TU102) | 570.144W | NVIDIA proprietary (redistribution restricted) | Fetched by `install.sh` from public NVIDIA `linux-firmware`; pinned MD5 `13ce12a392a31eeb79a2e6ebd3a4a93a`; **never committed** | +| NVIDIA host distribution driver | 570.211.01 | NVIDIA proprietary EULA | Host GPU management (tested configuration) | +| NVIDIA open-gpu-kernel-modules | tag 610.57.04 | MIT / GPL-2.0 dual | Cloned at a pinned tag by `install.sh` for build glue; **not committed** | +| NVIDIA CUDA toolkit | 12.4 | NVIDIA proprietary EULA | Building `tools/cuda-ab` and running CUDA workloads | +| Ubuntu guest OS | 24.04 LTS | Various (GPL and others) | Guest environment | + +### Build, test and analysis tooling + +| Component | Version | License | Role | +|---|---|---|---| +| GCC / binutils / make / bc / flex / bison | distribution | GPL-3.0 / LGPL-2.1 | Kernel and userspace builds | +| Linux kernel headers | matching host kernel | GPL-2.0 | Kernel module builds | +| OpenSSL (`libssl-dev`), libelf | distribution | Apache-2.0, LGPL-2.1/GPL | Build dependencies | +| Python 3 | ≥ 3.10 | PSF-2.0 | All analysis and diagnostic tooling | +| PyTorch | distribution version (optional) | BSD-3-Clause | Optional guest test agent (`tools/guest_agent/`) | +| GDB (+ Python bindings) | distribution | GPL-3.0 | Guest/host debugging and one-shot samplers | +| Ghidra | 11.x | Apache-2.0 | Firmware and CUDA userspace decompilation | +| OpenJDK | 21 | GPL-2.0 with Classpath Exception | Runs Ghidra | +| pkg-config, uuid-runtime, kmod, pciutils, curl, wget, git, ca-certificates | distribution | GPL-2.0/BSD-3-Clause/curl license/MPL-2.0 | Build and diagnostic utilities | +| GitHub Actions (CI service) | hosted | GitHub Terms | CI runner service used by `.github/workflows/ci.yml` | + +## 7. Dependency relationships + +``` +pkg:generic/open-iov@0.1.0 +├── contains open-iov-vfio (kernel module) ── depends on ── Linux kernel (VFIO/mdev/IOMMU/DMA) +├── contains libiov / libvgpu ── depends on ── tomlc99, cargs +├── contains example_vgpu, userspace tests, kernel tests +├── contains tools (guest-diag, cuda-ab, rmq, ghidra, guest_agent, vm/module/debug/test) +│ ├── cuda-ab ── needs ── NVIDIA CUDA toolkit 12.4 +│ ├── ghidra tools ── needs ── Ghidra + OpenJDK +│ └── guest_agent ── optional ── PyTorch +├── contains firmware analysis artifacts (570.144W) and CUDA analysis (570.144) +├── contains scripts, config, docs, wiki archive, CI +└── operates against (external, not distributed) + ├── NVIDIA guest driver 570.144 + libcuda + ├── NVIDIA GSP firmware 570.144W (fetched at install time) + ├── QEMU + KVM + VFIO/mdev (hypervisor platform) + └── Ubuntu 24.04 guest OS +``` + +The machine-readable document encodes these relationships in the CycloneDX +`dependencies` graph. + +## 8. License summary and redistribution + +| License | Applies to | Redistribution | +|---|---|---| +| BSD-3-Clause | Project code outside `kernel/` (`userspace/`, `tools/`, `scripts/`, `config/`, `docs/`, examples, tests, CI) | Permitted, with copyright notice | +| GPL-2.0 | `kernel/**` (kernel module) and in-kernel tests | Permitted under GPL-2.0 terms | +| MIT | tomlc99, cargs, NVIDIA public interface headers | Permitted, with notice | +| NVIDIA proprietary | Guest driver, host driver, GSP firmware, CUDA toolkit | **Not redistributed by this project**; governed by NVIDIA's EULA. Users obtain them directly from NVIDIA/public distribution channels | +| Various / NOASSERTION | Archived third-party media in `wiki/` (§5) | Governed by originating projects; remove if terms cannot be met | + +Notes: + +* `userspace/LICENSE` contains GPL-2.0 license text; the authoritative license + of each file is its `SPDX-License-Identifier` (the userspace libraries are + BSD-3-Clause per `docs/09-reference/legal-and-licensing.md`). +* GSP firmware and drivers may be subject to export-control regulations; + deployers are responsible for compliance. +* Contributions are inbound=outbound (BSD-3 for BSD-3 files, GPL-2.0 for + GPL-2.0 files); see `docs/09-reference/legal-and-licensing.md`. + +## 9. NTIA minimum-elements compliance + +| NTIA minimum element | Where satisfied | +|---|---| +| Supplier name | §1, §3, §4, §6 (per component) | +| Component name | §3, §4, §6 | +| Component version | §3, §4, §6 | +| Other unique identifiers | Package URLs (`pkg:…`) in §1/§3 and the CycloneDX file | +| Dependency relationships | §7 and CycloneDX `dependencies` | +| SBOM author | Document metadata (The Open-IOV Project) | +| Timestamp | Document metadata (`2026-10-02T06:47:39Z`) | +| Hash of component | SHA-256 for bundled files and tracked binaries (§3, §4, CycloneDX `hashes`) | + +## 10. Verification + +* Machine-readable SBOM: [`sbom/open-iov-0.1.0.cdx.json`](sbom/open-iov-0.1.0.cdx.json) + (CycloneDX 1.6, serial `urn:uuid:e626c5a1-9697-4546-bb2b-5b4feb58e922`). +* File hashes in this document and in the CycloneDX file can be verified with + `sha256sum` against a checkout of the same revision. +* To reproduce the inventory: all paths above are relative to the repository + root; `git ls-files` enumerates the tracked payload. +* Vulnerability management: components with known ecosystems (tomlc99, cargs, + NVIDIA headers, Linux kernel, Python, Ghidra) can be matched by purl/CPE by + standard SBOM tooling. The project itself carries no bundled libraries with + third-party transitive dependencies. + +## 11. Generation and revision history + +| Date (UTC) | Version | Change | +|---|---|---| +| 2026-10-02 | 1 | Initial complete SBOM replacing the 2023 wiki survey page. Inventory audited against the tracked tree; tracked binaries hashed; external/optional dependencies enumerated; NTIA checklist added. | -- cgit v1.2.3