site: 2026-10-30 wiki refresh - new Project Goals, Performance and Interfaces and Stability pages; GSP explainer expanded (bare-metal behaviour + the two emulation modes); graphics pages (Graphics Execution, OpenGL, Vulkan, DirectX) with two new diagrams; status refresh across 15 pages; canonical docs updated (README status table, purpose-and-scope, performance contract); published to open-iov.org (67 pages, 0 problems)

1 files changed, 117 insertions, 0 deletions

diff --git a/wiki/Interfaces-and-Stability.md b/wiki/Interfaces-and-Stability.md
new file mode 100644
index 0000000..44cade2
--- /dev/null
+++ b/wiki/Interfaces-and-Stability.md
@@ -0,0 +1,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.