Skip to content

PR 0071 feature add optional Vulkan ubershader

Jump to bottom
Mainkill1 edited this page Sep 14, 2026 · 3 revisions

PR #71 — optional Vulkan ubershader (current integration record)

Product PR · Merged into main at 322986f4c5502b3fa887a9605ac8cd88e9b2c579 on 2026-09-14 UTC · Tested candidate head 4f0a8797e6fd831f4c53b6bfe8c68f944236a7fa. The candidate-to-merge difference is documentation only; runtime source is unchanged.

Optimized Windows release contains a stripped executable from the merged main commit and separate matching DWARF, symbol map, build identity, and checksums. Its tag names the shared upstream foundation d73326b6 and fork branch ID main@322986f4; newer upstream mirror changes are not implied.

The current route chooses an existing executable only when both its shader binding and exact graphics pipeline are ready. A completely cold draw builds the normal specialized route, then prepares a reusable fallback family for later draws. A compatible ready fallback can issue a draw while a separate compiler lane and bounded pipeline worker prepare the exact specialization; takeover waits for the completed pipeline. The optional Vulkan ubershader switch is under Machine → Settings → Advance Performance → Vulkan, defaults Off, and requires a restart. Skip unchanged shader work is a separate default-Off live shortcut.

The detailed historical proposal and diagnostic event reference were moved out of the product branch into PR #71 historical design and PR #71 cold-trace reference. The retained code-linked setting reference is docs/performance/tweaks.md. Raw per-test and gameplay evidence stays in xemu-perf-tests.

Exact-head evidence Outcome Limit
Full XISO, Hybrid On cold vs previous main +0.446% median per-test duration improvement 153 matching Vulkan PASS tests; one run
Full XISO, Hybrid On warm vs previous main -2.173% One run, adverse signal
PGR2 full start, OpenGL p99 vs fixed baseline +3.039% One capped stationary pair, Hybrid Off
Focused Win64 runtime/compiler/pipeline/PR80 tests 18/18, 9/9, 8/8, 2/2 No retail FPS claim

The complete XISO tables and partial PGR2 pair retain the source, executable, and test identities. Exact-head Vulkan retail and Morrowind runs were stopped at the owner's direction; older e6048469 gameplay data is historical, not a result for 4f0a8797.

Preserved earlier wiki review (historical)

The content below was written for e5feb422 and is retained for review attribution. Its open/draft status, base, code counts, and qualification language do not describe the current head.

PR #71 — feature: add optional Vulkan ubershader

PR #71

Status

  • GitHub state: Open draft
  • Disposition at review: Negative / HOLD
  • Current head at review: e5feb422b5b1798e2bf1194290b8b7fc63900cdb (research/vulkan-ubershader-design)
  • Reviewed head: e5feb422b5b1798e2bf1194290b8b7fc63900cdb
  • Last reviewed: 2026-09-14 UTC
  • Base: main at 5edff26383c6440da35bc92b9fca35f4a404b03b
  • Subsystem: Vulkan shaders / pipelines

Review freshness: current at the reviewed head. Before acting on this open/draft PR, compare the live GitHub head with Reviewed head below. If it differs, treat implementation details, file impact, flow, and result qualification as stale until re-reviewed. The historical lesson remains valid unless newer evidence explicitly overturns it.

At a glance

  • What it changes: feature: add optional Vulkan ubershader
  • Why it was attempted: PR 68 measured first-seen shader work blocking a PGR2 draw: 121 first-seen stage/source identities, 20 different-key/same-source repeats, 463.419 ms aggregate glslang time, and 18.217 ms glslang time in the primary slow frame. PR 70 handles shaders already present in the persistent SPIR-V cache. PR 71 addresses newly encountered admitted fragment-combiner states.
  • Current/final result: Open draft/HOLD: architecture is implemented, but cold-frame tail attribution and exact-head retail qualification remain blockers.
  • Lesson: A first-seen specialization can be hidden behind a fail-closed runtime fallback only when worker work is immutable, publication remains renderer-owned, unsupported state falls back synchronously, and added route/descriptor/GPU costs are qualified against cold tails.

Code impact

Implementation file Δ Why it matters
config_spec.yml +3/-0 User-facing configuration/toggle schema for the behavior.
hw/xbox/nv2a/pgraph/glsl/meson.build +1/-0 Build registration for new/changed implementation or test units.
hw/xbox/nv2a/pgraph/glsl/psh-uber.c +156/-0 Runtime fragment-combiner interpreter emitted as GLSL for the fallback shader.
hw/xbox/nv2a/pgraph/glsl/psh-uber.h +16/-0 Runtime fragment-combiner interpreter emitted as GLSL for the fallback shader.
hw/xbox/nv2a/pgraph/glsl/psh.c +47/-30 Specialized pixel-shader/combiner generation shared with fallback semantics.
hw/xbox/nv2a/pgraph/glsl/psh.h +4/-0 Specialized pixel-shader/combiner generation shared with fallback semantics.
hw/xbox/nv2a/pgraph/vk/draw.c +867/-107 Vulkan draw preparation/recording and the PR hot-path decision.
hw/xbox/nv2a/pgraph/vk/glsl.c +157/-20 GLSL→SPIR-V compilation/module construction or backend shader integration.
hw/xbox/nv2a/pgraph/vk/hybrid-compiler.c +584/-0 Bounded speculative/required shader compile workers and job ownership.
hw/xbox/nv2a/pgraph/vk/hybrid-compiler.h +117/-0 Bounded speculative/required shader compile workers and job ownership.
hw/xbox/nv2a/pgraph/vk/hybrid-pipeline-builder.c +494/-0 Build/publish pipeline state produced by hybrid specialization work.
hw/xbox/nv2a/pgraph/vk/hybrid-pipeline-builder.h +92/-0 Build/publish pipeline state produced by hybrid specialization work.
hw/xbox/nv2a/pgraph/vk/hybrid-policy.c +235/-0 Pure specialized/fallback/synchronous routing policy, retry, and backoff rules.
hw/xbox/nv2a/pgraph/vk/hybrid-policy.h +137/-0 Pure specialized/fallback/synchronous routing policy, retry, and backoff rules.
hw/xbox/nv2a/pgraph/vk/hybrid-ready.h +113/-0 Readiness/state contract used by the hybrid route fast path.
hw/xbox/nv2a/pgraph/vk/hybrid-trace.c +136/-0 Hybrid-route instrumentation and trace attribution.
hw/xbox/nv2a/pgraph/vk/hybrid-trace.h +54/-0 Hybrid-route instrumentation and trace attribution.
hw/xbox/nv2a/pgraph/vk/meson.build +5/-0 Build registration for new/changed implementation or test units.
hw/xbox/nv2a/pgraph/vk/renderer.c +31/-1 Renderer lifecycle, pending work, synchronization, or teardown ownership.
hw/xbox/nv2a/pgraph/vk/renderer.h +207/-0 Renderer-owned state needed by the implementation.
hw/xbox/nv2a/pgraph/vk/shaders.c +929/-79 Vulkan shader binding/module caches, descriptors, hybrid routing, and publication.
hw/xbox/nv2a/pgraph/vk/ubershader-combiner-oracle.c +465/-0 CPU semantic oracle used to prove admitted runtime combiner behavior.
hw/xbox/nv2a/pgraph/vk/ubershader-combiner-oracle.h +44/-0 CPU semantic oracle used to prove admitted runtime combiner behavior.
hw/xbox/nv2a/pgraph/vk/ubershader-controls.c +228/-0 Stable runtime-control ABI packing, validation, and fail-closed admission.
hw/xbox/nv2a/pgraph/vk/ubershader-controls.h +71/-0 Stable runtime-control ABI packing, validation, and fail-closed admission.
include/qemu/lru.h +35/-0 Generic LRU cache lookup/eviction fast path.
tests/unit/meson.build +54/-0 Focused/regression validation for the implementation contract.
tests/unit/test-lru-active.c +180/-3 Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-hybrid-compiler.c +451/-0 Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-hybrid-pipeline-builder.c +467/-0 Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-hybrid-policy.c +358/-0 Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-hybrid-trace.c +77/-0 Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-ubershader-combiner.c +1241/-0 Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-ubershader-controls.c +333/-0 Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-ubershader-glsl-integration.c +115/-0 Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-ubershader-glsl.c +140/-0 Focused/regression validation for the implementation contract.
tests/unit/test-xbox-vk-ubershader-runtime.c +484/-0 Focused/regression validation for the implementation contract.
tests/unit/test-xemu-tweaks-config.cc +36/-11 Focused/regression validation for the implementation contract.
ui/xemu-tweaks.c +5/-1 User-facing control or presentation integration.
ui/xemu-tweaks.h +3/-1 User-facing control or presentation integration.
ui/xui/main-menu.cc +8/-4 User-facing control or presentation integration.

Flow

flowchart LR
    subgraph Before
        A[Guest draw] --> B[Resolve shader state] --> C[Cache / compile / pipeline dependency] --> D[Draw]
    end
    subgraph PR_71[PR #71]
        E[Guest draw] --> F[PR #71 shader contract] --> G[Reuse / classify / fallback as proven] --> H[Draw]
    end
Loading

What changed

Adds a fixed, aligned 448-byte combiner control ABI and fail-closed admission. - Adds a finite CPU combiner oracle and runtime GLSL emitter inside the existing fragment shell. - Adds route-aware shader and pipeline keys without duplicating vertex or geometry modules. - Adds binding 6 only when the restart-latched option is enabled. - Reuses the current descriptor set for control-only updates. - Adds Vulkan ubershader / Reduce shader stalls. under Machine → Settings → Advance Performance. - Keeps the feature default Off and restart-required. - Adds focused policy, ABI, oracle, GLSL, compiler/reflection, worker queue, runtime-key, LRU, and set…

Result

Open draft/HOLD: architecture is implemented, but cold-frame tail attribution and exact-head retail qualification remain blockers.

Lesson learned

A first-seen specialization can be hidden behind a fail-closed runtime fallback only when worker work is immutable, publication remains renderer-owned, unsupported state falls back synchronously, and added route/descriptor/GPU costs are qualified against cold tails.

Avoid repeating

Do not declare the ubershader a win from reduced compile blocking alone. Re-check exact-head p95/p99/max tails and ensure required compilation cannot queue behind speculative work.

Docs / evidence

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

Related architecture

Related PRs referenced by this PR:

DSP tooling guide and navigation updated November 2, 2026 for experimental PR #384, source 8f51d237. Capture/replay usage and limits.

The earlier wiki-wide review was published November 1, 2026. Emulator source: b7140848. Reviewed wiki content: 1d2b671. Current status · Release availability · Publication process.

xemu wiki

Architecture

Evaluation and development

Contribute upstream

Research and history

Repository · PRs · Issues

Clone this wiki locally