Interfaces and Stability

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 (engineering rules), ../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); 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) — 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.
• 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 — the goals this compatibility policy serves.
• Host-Module.md — where the mdev surface and the debug parameters live.
• Hardware-Software-Matrix.md — how profiles, versions and devices are handled.
• Riscv-GSP-RM-Debugger.md — the development-only tooling and its versioned session format.
• Performance.md — why debug surfaces are explicitly not configuration.