PR 0075 Vulkan select and report the host GPU by UUID

PR #75 — Vulkan: select and report the host GPU by UUID

PR #75

Status

• GitHub state: Merged
• Disposition at review: Merged
• Current head at review: 3f5446b572e310a3dac76d6403513862b299e768 (feature/gpu-adapter-selection)
• Reviewed head: 3f5446b572e310a3dac76d6403513862b299e768
• Last reviewed: 2026-09-14 UTC
• Base: main at 4e505bfb821ae326d3129539d559848a34759500
• Subsystem: Vulkan renderer

Review freshness: this page records the final/known PR head at review time. If the PR is reopened or rewritten, re-review before relying on implementation details.

At a glance

• What it changes: Vulkan: select and report the host GPU by UUID
• Why it was attempted: Observed problem: xemu selected Vulkan devices by display name, silently chose another compatible device when a preference failed, overwrote the saved preference with the observed result, and offered no machine-readable proof of the actual adapter. Profiling evidence: Not applicable. This is deterministic test-control and user-interface work. Suspected cause: Discovery, name-based preference, fallback, and runtime identity were combined in renderer initia…
• Current/final result: Merged: Vulkan adapter selection/reporting is explicit enough to verify the actual initialized physical device.
• Lesson: Renderer benchmarking and compatibility require exact physical-device identity; requested GPU, initialized GPU, capabilities, and reported adapter must agree.

Code impact

Implementation file	Δ	Why it matters
config_spec.yml	+1/-0	User-facing configuration/toggle schema for the behavior.
hw/xbox/nv2a/pgraph/pgraph.c	+32/-4	Shared PGRAPH guest-state/method handling and renderer boundary.
hw/xbox/nv2a/pgraph/vk/device-inventory.c	+92/-0	Vulkan physical-device discovery, identity, selection, or reporting.
hw/xbox/nv2a/pgraph/vk/device-inventory.h	+87/-0	Vulkan physical-device discovery, identity, selection, or reporting.
hw/xbox/nv2a/pgraph/vk/device-selection.c	+189/-0	Vulkan physical-device discovery, identity, selection, or reporting.
hw/xbox/nv2a/pgraph/vk/device-selection.h	+83/-0	Vulkan physical-device discovery, identity, selection, or reporting.
hw/xbox/nv2a/pgraph/vk/display.c	+6/-0	Display output ownership, reuse, or presentation transport.
hw/xbox/nv2a/pgraph/vk/glsl.c	+24/-3	GLSL→SPIR-V compilation/module construction or backend shader integration.
hw/xbox/nv2a/pgraph/vk/instance.c	+212/-61	NV2A guest-visible state or backend translation path.
hw/xbox/nv2a/pgraph/vk/meson.build	+2/-0	Build registration for new/changed implementation or test units.
hw/xbox/nv2a/pgraph/vk/renderer.h	+4/-1	Renderer-owned state needed by the implementation.
tests/unit/meson.build	+15/-0	Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-device-inventory.c	+259/-0	Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-device-selection.c	+183/-0	Focused/regression validation for the implementation contract.
tests/unit/test-xemu-gpu-info.c	+176/-0	Focused/regression validation for the implementation contract.
tests/unit/test-xemu-gpu-launch.c	+158/-0	Focused/regression validation for the implementation contract.
ui/meson.build	+2/-0	Build registration for new/changed implementation or test units.
ui/xemu-gpu-info.c	+517/-0	User-facing control or presentation integration.
ui/xemu-gpu-info.h	+67/-0	User-facing control or presentation integration.
ui/xemu-gpu-launch.c	+157/-0	User-facing control or presentation integration.
ui/xemu-gpu-launch.h	+55/-0	User-facing control or presentation integration.
ui/xemu.c	+90/-2	User-facing control or presentation integration.
ui/xui/main-menu.cc	+78/-0	User-facing control or presentation integration.

Flow

flowchart LR
    subgraph Before
        A[Guest report / DMA request] --> B[Map and validate target] --> C[Queue/write completion] --> D[Guest observes result]
    end
    subgraph PR_75[PR #75]
        E[Guest report / DMA request] --> F[PR #75 bounded rule] --> G[Valid path or explicit reject] --> H[Guest observes result]
    end

Loading

What changed

Add pure UUID parsing, formatting, and deterministic selection policy. - Add checked Vulkan enumeration and unified renderer-capability evaluation. - Add display.vulkan.device uuid without removing legacy name migration. - Add process-local GPU CLI parsing before normal startup side effects. - Add atomic schema-versioned inventory and runtime reports. - Prevent device and renderer substitution in strict mode. - Select glslang SPIR-V output compatible with the selected Vulkan API level. - Report shared presentation only after OpenGL memory import and texture creation succeed. - Add the adapter selector and active adapter readout under Display…

Result

Merged: Vulkan adapter selection/reporting is explicit enough to verify the actual initialized physical device.

Lesson learned

Renderer benchmarking and compatibility require exact physical-device identity; requested GPU, initialized GPU, capabilities, and reported adapter must agree.

Avoid repeating

Do not accept a Vulkan A/B comparison if the candidate may have initialized a different adapter than the reference.

Docs / evidence

Pointers only; the detailed evidence remains in its original location.

• docs/performance/
• docs/superpowers/plans/
• docs/superpowers/specs/

Related architecture

• Vulkan-Renderer
• NV2A Graphics Architecture