# 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.