WikiBot: 2026-10-30 wiki refresh: goals, GSP, graphics, performance, interfaces

2026-10-30T17:06:17Z

2026-10-30 wiki refresh: goals, GSP, graphics, performance, interfaces

New page

{{About message}}

= Interfaces and Stability =

<blockquote>'''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: [https://git.vgpu.io/open-iov.git/tree/docs/eng-ops.md <code>../docs/eng-ops.md</code>] (engineering rules), [https://git.vgpu.io/open-iov.git/tree/docs/06-portability/hardware-software-matrix.md <code>../docs/06-portability/hardware-software-matrix.md</code>] (version/device profiles) and the headers/schemas named below; the docs tree wins on disagreement.</blockquote>

Status: 2026-10-30, tree <code>master @ b4930168</code>.

== 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="wikitable"
|-
! 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) ==

{| class="wikitable"
|-
! 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 and Software Matrix|<code>Hardware-Software-Matrix.md</code>]]); the emulation answers the version the driver negotiates
|-
| '''The host/platform surface of <code>vgsp.ko</code>''': the VFIO '''mdev lifecycle''' (mdev type names such as <code>nvidia-vgpu-turing</code>, <code>-1g</code>, <code>-2g</code>; 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''' (<code>libvgpu</code> / <code>libiov</code>; header <code>userspace/include/libvgpu.h</code>): 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''' (<code>config/versions/*.yaml</code>, <code>config/hardware/*.yaml</code>): 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 (<code>greeneye-session/1</code>), 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''' (<code>/sys/module/vgsp/parameters/*</code>) — 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 <code>gsp-phys-*</code> controls and counters) — observability only; no format or lifetime promise.
* '''<code>vgsp.ko</code> 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''' (<code>scripts/</code>, <code>tools/</code>, <code>tools/guest-diag/</code>) — working material, not products.
* '''The firmware workbench's CLI, plugins and probe files''' ([[risc-v-gsp-rm-debugger|<code>Riscv-GSP-RM-Debugger.md</code>]]) — 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:

# '''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.
# '''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.
# '''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|<code>Project-Status.md</code>]].
* '''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|<code>Project-Goals.md</code>]] — the goals this compatibility policy serves.
* [[The Host Module (vgsp.ko)|<code>Host-Module.md</code>]] — where the mdev surface and the debug parameters live.
* [[Hardware and Software Matrix|<code>Hardware-Software-Matrix.md</code>]] — how profiles, versions and devices are handled.
* [[risc-v-gsp-rm-debugger|<code>Riscv-GSP-RM-Debugger.md</code>]] — the development-only tooling and its versioned session format.
* [[Performance|<code>Performance.md</code>]] — why debug surfaces are explicitly not configuration.

Interfaces and Stability - Revision history

WikiBot: 2026-10-30 wiki refresh: goals, GSP, graphics, performance, interfaces