1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
# Interfaces and Stability
> **Scope.** The interfaces Open-IOV exposes or consumes, which of them are
> **contracts** (stable, versioned, safe to build on), which are **not**
> (bring-up and debug surfaces, free to change), and *why* the stable set is
> stable. This is the compatibility policy for the project's own software — the
> interfaces of *other people's* software are fixed by the project's rules
> (nothing is patched). Canonical sources:
> [`../docs/eng-ops.md`](../docs/eng-ops.md) (engineering rules),
> [`../docs/06-portability/hardware-software-matrix.md`](../docs/06-portability/hardware-software-matrix.md)
> (version/device profiles) and the headers/schemas named below; the docs tree
> wins on disagreement.
Status: 2026-10-30, tree `master @ b4930168`.
## 1. Why interfaces are the product
Open-IOV's durability comes from a single idea: **own the interface, not a
snapshot of it**, and **never patch anyone**. The interfaces the project
*consumes* — the stock NVIDIA driver's device expectations, the kernel's VFIO/
mdev UAPI, the hypervisor's DMA and interrupt interfaces — are therefore
immutable by construction: if the project changed what the guest driver sees,
the stock driver would break, and the project would have failed its own rule.
The interfaces the project *exposes* are split deliberately into three
classes, and everything below is one of them:
| Class | Promise | Examples |
|---|---|---|
| **Consumer contracts** | stable; versioned; changes are additive or bump a version | the guest-visible device interface, the mdev lifecycle surface, the userspace management library, the configuration schemas, tooling evidence formats |
| **Bring-up and debug surfaces** | *no* promise — names and semantics may change between builds | module parameters, debug filesystem files, internal state shapes |
| **Internal surfaces** | no promise, no consumers outside the module | kernel functions, structs, heuristics |
## 2. Stable interfaces (contracts)
| Interface | Consumers | Why it is stable | Change policy |
|---|---|---|---|
| **The guest-visible device interface**: PCI configuration space, BAR0 register interface, BAR1/BAR3 apertures, MSI-X; the GSP boot protocol; the GSP-RM message-queue transport and RPC functions; RM object/control semantics; events and completions | stock NVIDIA guest drivers (Linux and Windows) | *It is NVIDIA's interface*, fixed by the driver version the profile targets. The no-patch rule means changing it is not an option: any update must keep the unmodified driver working | Never changed by us. New driver/firmware versions enter as **profiles with measured deltas** ([`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md)); the emulation answers the version the driver negotiates |
| **The host/platform surface of `vgsp.ko`**: the VFIO **mdev lifecycle** (mdev type names such as `nvidia-vgpu-turing`, `-1g`, `-2g`; sysfs create/remove; the VFIO region, DMA and IRQ UAPI) | QEMU/libvirt and management tooling; any conforming VFIO consumer | It is the kernel's mdev/VFIO contract plus a small, documented set of type names that tooling (and user scripts) reference by name | Additive by default; renaming or removing a type requires a migration note and a supported overlap window |
| **The userspace management library** (`libvgpu` / `libiov`; header `userspace/include/libvgpu.h`): error codes, memory/type enums, VF, migration and WPR operations; versioned soname | project tooling and integrators writing management workflows | A small C API with a versioned shared-object name; its consumers link rather than copy | Additive changes keep the soname; breaking changes bump it. The surface is small on purpose — it is a management API, not the data path |
| **Configuration profiles** (`config/versions/*.yaml`, `config/hardware/*.yaml`): per-driver and per-device adaptation data | the module's version adaptation and the porting workflows | Data contract: the porting promise is "a new version is a profile plus a measured delta", which only holds if the schema is stable | Additive fields; semantic changes are versioned with the profile |
| **Developer-tooling evidence formats**: the recorded-session format (`greeneye-session/1`), the symbol database, the injection ABI (v1) | recorded evidence, replays and future sessions of the firmware workbench | Evidence must remain interpretable years later, so the formats are declared back-compatibility items even though the tooling itself is development-only | Version bumps with migration notes; additive fields preferred; a breaking change needs a shim or a format-version bump |
| **The documentation canon** | users, integrators, future contributors | The docs tree is the declared source of truth: where a wiki page or summary disagrees with the repository documents, the repository wins | Corrections update the docs tree first, then the derived pages |
## 3. Explicitly not stable (may change)
Nothing in this list is safe to build on; treat it as subject to change
between builds, without notice:
* **Module parameters** (`/sys/module/vgsp/parameters/*`) — bring-up and debug
knobs (targeted probes, forced behaviours, diagnostic mirrors). They exist to
run experiments; names and semantics change as the canonical paths replace
them.
* **Debug filesystem surfaces** (the module's `gsp-phys-*` controls and
counters) — observability only; no format or lifetime promise.
* **`vgsp.ko` internals** — functions, structures, state layouts; there are no
external consumers and no stability promise.
* **Emulation internals** — ring/USERD discovery heuristics, shadow windows,
scratch mappings, scan cadences, and the parameter-gated forwarding and
graphics seams while they are validated. When a seam graduates, it becomes a
documented configuration surface and leaves this list.
* **Scripts, harnesses and test clients** (`scripts/`, `tools/`,
`tools/guest-diag/`) — working material, not products.
* **The firmware workbench's CLI, plugins and probe files**
([`Riscv-GSP-RM-Debugger.md`](Riscv-GSP-RM-Debugger.md)) — development-only
by declaration; interfaces and file formats may change without notice.
(Exception: the *session format* above is versioned precisely so recorded
evidence survives tool change.)
* **This wiki and the site** — a curated, dated documentation view, refreshed
with status changes; it is not an API.
## 4. Why the stable set is stable
Three kinds of reason, and each stable interface has at least one of them:
1. **It is externally specified.** The guest-visible device interface is
NVIDIA's; the mdev lifecycle is the kernel's. Stability is inherited, and
the project's rules forbid "fixing" either side.
2. **It has declared consumers.** The user library, the mdev type names, the
configuration schemas and the evidence formats have real consumers
(tooling, scripts, evidence archives). A contract exists because someone
else depends on it — not because it was convenient to freeze.
3. **The project's own rules make it so.** *No patches* + *profiles, not
rewrites* means the device-facing behaviour must evolve the way NVIDIA's
driver evolves — by version, never by surprise.
**Change discipline, in one sentence:** prefer additive; version what
consumers link against or parse; never break evidence or an unmodified
driver; document the migration when something must move.
## 5. Open items (stability questions we expect to close)
* **Userspace library freeze point.** When the management workflows stabilise,
declare an API freeze (a 1.0 surface) so integrators can rely on it.
* **Graduating debug seams.** The parameter-gated forwarding and graphics
seams will migrate from debug knobs to documented configuration as they are
validated; the graduating list is tracked on
[`Project-Status.md`](Project-Status.md).
* **Schema formality.** The configuration profiles are documented data today;
a formal schema would make the "profile + measured delta" promise checkable
by tooling.
* **Evidence-format externalisation.** If parties outside the project archive
workbench sessions, the session and symbol formats need the same public
versioning treatment as the user library.
## 6. Related pages
* [`Project-Goals.md`](Project-Goals.md) — the goals this compatibility
policy serves.
* [`Host-Module.md`](Host-Module.md) — where the mdev surface and the debug
parameters live.
* [`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md) — how
profiles, versions and devices are handled.
* [`Riscv-GSP-RM-Debugger.md`](Riscv-GSP-RM-Debugger.md) — the development-only
tooling and its versioned session format.
* [`Performance.md`](Performance.md) — why debug surfaces are explicitly not
configuration.
|
