Development

Development

This page separates current architecture from active experiments and closed research.

For the complete searchable PR-by-PR code-impact and lesson catalog, see Pull Request Lessons.

For reviewed overlap with open xemu-project/xemu pull requests, transferable regressions, and prepared upstream handoffs, see Upstream Work.

For upstream ideas that need a fork-specific rework before implementation, see Upstream Work In Need.

Architecture pages describe the code a developer should expect on main. Pull requests appear here when they are useful implementation history, ongoing research, or evidence for a design decision.

Status snapshot: 2026-09-13. Always use the linked PR as the final source of truth for current head and merge state.

The newer September 26, 2026 development status reconciles merged #228 and Shader Browser Stages #237, #238, and #239 with the still-open #241 preview and #242 profiling drafts. The older snapshot below remains a historical record.

Current merged foundations

These changes are part of current main and may be referenced as current behavior in architecture pages.

PR	Area	Current architectural effect	Read next
#70 — persistent Vulkan shader artifacts	Vulkan shaders	Adds bounded persistent SPIR-V reuse for previously encountered exact shader source/configuration	[[Vulkan Renderer
#75 — exact Vulkan adapter selection/reporting	Vulkan device selection	Makes renderer GPU selection/reporting explicit enough to verify the actual physical device	[[Vulkan Renderer
#76 — cross-adapter presentation fallback	Presentation	Adds a bounded host-copy path when Vulkan rendering cannot safely share external memory with the OpenGL presenter	[[Vulkan Renderer
#80 — guarded warm texture reuse	Vulkan textures	Reuses unchanged texture bindings only when effective source/DMA identity and freshness remain compatible	[[NV2A Graphics Architecture

Active Vulkan research

PR #71 — Ubershader & hybrid specialization

State: open draft / HOLD.

PR #71 researches how to hide genuinely unseen fragment specialization behind an already compiled runtime fallback while a specialized shader is prepared in the background.

Key concepts:

• Fail-closed ubershader admission.
• Fixed control ABI for runtime combiner state.
• Background speculative compiler lane.
• Independent required/blocking compiler lane.
• Generation/ticket checks before publishing asynchronous results.
• Fast-path avoidance of redundant route selection.
• Specialized path remains authoritative when ready.

The architecture is implemented on the PR branch, but exact-current-head retail qualification remains incomplete and prior cold-tail regressions remain a HOLD condition. Do not describe the feature as an established performance win.

Read: Ubershader & Hybrid Specialization.

PR #83 — Descriptor-capacity interaction

State: open draft / HOLD.

PR #83 investigates Vulkan descriptor/uniform capacity and the submission/finish behavior caused when the current resource pool is exhausted.

The important result is methodological: removing one local finish reason did not prove a throughput win because the same dependency could move to another later submission/fence boundary.

Read: Vulkan Renderer and Performance Methodology.

PR #85 — Surface / vertex freshness

State: open draft / HOLD.

PR #85 addresses cases where vertex data can overlap GPU-authored surfaces and guest memory may not yet contain the newest bytes.

The correctness question is:

Before CPU-side vertex decoding or upload,
is guest memory definitely authoritative for the exact fetched range?

If not, surface readback/coherency must happen before consuming the data.

Read: NV2A Graphics Architecture and Vertex Uploads & Render-Pass Lifetime.

PR #87 — Fresh-page direct vertex writes

State: open draft / HOLD.

PR #87 researches direct mapped writes into the Vulkan vertex-RAM mirror when the active command buffer has not already recorded a draw that reads those pages.

The safety rule is lifetime-based, not merely “use memcpy instead of staging”:

page unread by all earlier recorded draws in active batch
    → direct mapped write may be safe

page already consumed by an earlier recorded draw
    → preserve ordered staging copy/barriers

Morrowind exposes a meaningful opportunity, while PGR2 can pay bookkeeping cost for very little direct-copy benefit. Current performance qualification remains mixed.

Read: Vertex Uploads & Render-Pass Lifetime.

PR #88 — Graphics command-state reuse

State: open draft / HOLD.

PR #88 investigates reusing graphics command state across render-pass restarts rather than replaying state more broadly after every pass break.

The experiment is useful because it targets CPU command-recording overhead without assuming render-pass GPU time itself is removable. Current results remain adverse/mixed for at least part of the tested Morrowind workload, so it remains research rather than current architecture.

Read: Vulkan Renderer and Vulkan Performance.

PR #89 — Bounded immutable vertex versions

State: open draft.

PR #89 extends the vertex-lifetime work toward bounded immutable versions rather than relying only on rewriting a shared mirror.

The architectural question is whether xemu can let earlier recorded draws retain the bytes they were supposed to consume while later guest writes advance to a new version without forcing the same ordered-copy/pass-break path.

This sits on top of the #85/#87 correctness work and should be read as stacked research.

Read: Vertex Uploads & Render-Pass Lifetime.

Active timing research

PR #81 — Explicit PTIMER deadlines

State: open draft / HOLD.

PR #81 experiments with a more explicit NV2A PTIMER scheduling state machine.

The candidate separates:

• Guest-visible PTIMER state.
• Derived virtual-clock deadline.
• Whether a host QEMUTimer is armed.
• Whether the next operation should keep, cancel, or replace the queued deadline.
• Phase-aware conversion/rounding of future alarm ticks.

This is not current-main PTIMER architecture. Retail qualification remains mixed, including adverse OpenGL Morrowind evidence, so the branch remains HOLD.

Read: Clocks & Timers.

Closed diagnostic / negative research

Closed research still belongs in the Wiki when it established a useful architectural fact.

PR	State	What it established	Read next
#68 — classify Vulkan shader-module misses	Closed, unmerged diagnostic	The primary reproduced PGR2 hitch included genuinely first-seen shader sources; pipeline misses, binding misses and compiler calls must be measured separately	[[Shader Binding & Compilation
#54 — TCG return attribution	Closed diagnostic	Provided evidence for classifying why translated CPU execution returned to the TCG dispatcher	[[CPU & vCPU Execution
#55 — STI interrupt-shadow chaining	Closed, unmerged / HOLD	Tested a CPU-dispatch optimization around x86 STI interrupt-shadow semantics; correctness boundaries prevented treating fewer exits as automatically safe	[[CPU & vCPU Execution
#92 — live renderer reinitialization experiment	Closed, unmerged negative experiment	Showed that live renderer reset is coupled to framebuffer/UI ownership and synchronization; destroying/recreating the renderer is not an isolated settings operation	[[NV2A Graphics Architecture

Track implementation limitations like architecture

Source-level shortcuts and incomplete models should not disappear into code comments when they can change compatibility or profiling conclusions.

Promote a limitation into the relevant architecture page when it is one of:

• a guest-visible no-op or fixed-value register;
• a synchronous shortcut for physically asynchronous hardware;
• a host-backend coupling that changes pacing or completion;
• a device/function stub;
• an assertion that handles guest input more strongly than hardware would;
• a compatibility workaround that future cleanup could accidentally remove;
• a fast path whose safety depends on a non-obvious invariant.

The durable documentation should describe the boundary by subsystem. An issue/PR can then reference that documented boundary when attempting to improve it.

See Hardware Fidelity & Emulation Boundaries.

How development pages should reference PRs

A Wiki page should normally say:

This is how the subsystem works.

Related Development
- PR #NN investigates changing this boundary because ...
- Current status: Draft / Hold / Merged / Closed diagnostic.

Avoid organizing permanent documentation as:

PR 71
PR 81
PR 87

PR numbers are implementation history. The durable subject is the subsystem and its data flow.

Status vocabulary

Label	Meaning in this Wiki
Merged / current	Behavior is present on current main and can be documented as architecture
Draft	Implementation/research exists but is not accepted mainline behavior
HOLD	One or more correctness/performance/qualification blockers remain
Diagnostic	Instrumentation/evidence branch intended to classify behavior, not ship
Historical	Measurement or implementation belongs to an older exact source state
Negative experiment	Useful result showed the proposed route was not beneficial/safe enough to continue in that form

Evidence discipline

When a PR changes rapidly, the PR body and evidence repository should identify:

• Exact tested head.
• Executable/build hash.
• Reference source.
• Workload seed.
• Instrumented versus normal build.
• Correctness gates.
• Performance gates.
• Historical results that no longer qualify the current head.

A new commit does not automatically inherit an earlier PASS. See Performance Methodology.

Architecture index

• System Architecture
• CPU & vCPU Execution
• Clocks & Timers
• NV2A Graphics Architecture
• OpenGL Renderer
• Vulkan Renderer
• OpenGL vs Vulkan