Pull Request Lessons

Pull Request Lessons

Reviewed: 2026-11-01 · Source: b7140848 · Availability: current main; stable/main boundaries are stated below.

The original 71 PR-numbered pages extend through #138 (including multiple #71 pages). Subsequent implementation decisions are now indexed in the complete 43-merge register, current mechanisms and research dispositions; no essay per test-only PR is required. Historical lessons below retain their original reviewed heads.

This is the fast-search catalog for engineering lessons captured from every pull request in Mainkill1/xemu. Search for a PR number, source path, subsystem, state, disposition, or lesson. Each detail page separates mutable implementation facts from the durable conclusion that should prevent duplicate work.

Freshness rule

For open/draft work, Reviewed head is the safety boundary. Compare the live GitHub PR head before reusing code or conclusions. If the SHA differs, re-review implementation files, flow, and result qualification before acting; never silently inherit an old PASS.

Current disposition corrections

Historical review	Current state at November 1
#71 hybrid, #85 freshness, #89 private vertex versions	Merged and present; current implementation. The old HOLD rows retain their original reviewed heads.
#81 PTIMER	Historical unmerged experiment; delivered #267/#271 is the current timer story.
#83 descriptor capacity, #87 direct writes, #88 command state	Closed unmerged; #87 direction partly incorporated into merged #89. Retain measured lessons without advertising an active draft.

Historical PR review catalog

PR	Area	Disposition at the recorded review	Code impact	Durable lesson	Reviewed head
#92	Snapshot / lifecycle	Closed unmerged · Negative result	hw/xbox/nv2a/nv2a.c, hw/xbox/nv2a/pgraph/pgraph.c	Live renderer reinitialization is coupled to UI/framebuffer ownership: the negative experiment blocked after renderer flush while waiting on a UI-held framebuffer. A future reset path needs an explicit framebuffer relea…	3e658fced881
#89	Vulkan memory / synchronization	Open draft · Negative / HOLD	hw/xbox/nv2a/pgraph/vk/buffer.c, hw/xbox/nv2a/pgraph/vk/draw.c, hw/xbox/nv2a/pgraph/vk/perf.c +8 more	Bounded immutable vertex versions can preserve the bytes seen by earlier recorded draws while later guest writes advance to new storage, but versioning must remain bounded and inherit surface-freshness correctness.	aa260e72c51e
#88	Vulkan memory / synchronization	Open draft · Negative / HOLD	hw/xbox/nv2a/pgraph/vk/buffer.c, hw/xbox/nv2a/pgraph/vk/draw-command-state.h, hw/xbox/nv2a/pgraph/vk/draw.c +6 more	Reducing Vulkan command-state replay after render-pass restarts is only useful if end-to-end guest progress improves; a local CPU command reduction can be offset by changed lifetime or synchronization elsewhere.	dbe0e6b318ce
#87	Vulkan memory / synchronization	Open draft · Negative / HOLD	hw/xbox/nv2a/pgraph/vk/buffer.c, hw/xbox/nv2a/pgraph/vk/draw.c, hw/xbox/nv2a/pgraph/vk/perf.c +3 more	A direct mapped vertex-RAM write is safe during an active Vulkan batch only when no earlier recorded draw has consumed the overwritten page; otherwise preserve ordered staging/barriers. Tracking cost is highly workload-…	1d4524a6df0f
#85	Vulkan memory / synchronization	Open draft · HOLD	hw/xbox/nv2a/pgraph/vk/draw.c, hw/xbox/nv2a/pgraph/vk/renderer.c, hw/xbox/nv2a/pgraph/vk/renderer.h +5 more	Before CPU-side vertex decoding/upload, prove guest memory is authoritative for the exact fetched range when GPU-authored surfaces may overlap it; coherency must precede optimization.	0883fb63009c
#83	Vulkan memory / synchronization	Open draft · Negative / HOLD	hw/xbox/nv2a/pgraph/vk/renderer.h	Removing a descriptor-capacity finish does not prove faster execution when the same completion dependency moves to a later submit/fence boundary.	5717357917ab
#81	Timing	Open draft · HOLD	hw/xbox/nv2a/meson.build, hw/xbox/nv2a/nv2a.c, hw/xbox/nv2a/nv2a_int.h +9 more	Explicit keep/cancel/replace PTIMER deadline ownership can make scheduling easier to reason about, but fewer host timer operations are not a performance result; retail qualification can still regress.	98f1a7a49cb7
#80	Vulkan memory / synchronization	Merged	hw/xbox/nv2a/pgraph/pgraph.c, hw/xbox/nv2a/pgraph/vk/renderer.h, hw/xbox/nv2a/pgraph/vk/surface.c +4 more	A clean texture dirty bit is not sufficient cache identity. Warm texture reuse must also validate effective guest source/DMA identity and freshness.	6bf9e98cdee5
#78	Vulkan shaders / pipelines	Closed unmerged · Historical / not merged	hw/xbox/nv2a/pgraph/vk/ubershader-combiner-oracle.c, hw/xbox/nv2a/pgraph/vk/ubershader-combiner-oracle.h, tests/unit/meson.build +1 more	A CPU-side combiner oracle and focused semantic tests can validate ubershader math before GPU integration; semantic equivalence is a separate gate from enabling runtime selection.	7865142b10cd
#77	Vulkan shaders / pipelines	Closed unmerged · Historical / not merged	hw/xbox/nv2a/pgraph/vk/hybrid-policy.c, hw/xbox/nv2a/pgraph/vk/hybrid-policy.h, hw/xbox/nv2a/pgraph/vk/ubershader-controls.c +6 more	Define hybrid routing policy, control ABI, retry metadata, and fail-closed admission as testable contracts before wiring a runtime fallback into the renderer hot path.	1801ac7dd016
#76	Vulkan renderer / presentation	Merged	hw/xbox/nv2a/pgraph/vk/device-selection.c, hw/xbox/nv2a/pgraph/vk/device-selection.h, hw/xbox/nv2a/pgraph/vk/display.c +3 more	Vulkan rendering and OpenGL presentation can live on incompatible adapters; external-memory sharing needs an explicit compatibility test and a bounded host-copy fallback.	a08c4d929165
#75	Vulkan renderer	Merged	config_spec.yml, hw/xbox/nv2a/pgraph/pgraph.c, hw/xbox/nv2a/pgraph/vk/device-inventory.c +20 more	Renderer benchmarking and compatibility require exact physical-device identity; requested GPU, initialized GPU, capabilities, and reported adapter must agree.	3f5446b572e3
#74	NV2A reports / synchronization	Closed unmerged · Historical / superseded	hw/xbox/nv2a/pgraph/meson.build, hw/xbox/nv2a/pgraph/pgraph.c, hw/xbox/nv2a/pgraph/reports.c +9 more	Report writes need shared bounds validation before backend serialization, and Vulkan report retirement must preserve guest-visible completion ordering; targeted correctness alone is not enough when cross-backend tail be…	e1ec62ede550
#71	Vulkan shaders / pipelines	Open draft · Negative / HOLD	config_spec.yml, hw/xbox/nv2a/pgraph/glsl/meson.build, hw/xbox/nv2a/pgraph/glsl/psh-uber.c +38 more	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/descrip…	e5feb422b5b1
#70	Vulkan shaders / pipelines	Merged	hw/xbox/nv2a/pgraph/vk/glsl.c, hw/xbox/nv2a/pgraph/vk/glsl.h, hw/xbox/nv2a/pgraph/vk/meson.build +10 more	Persist exact compiled SPIR-V artifacts across runs using stable source/compiler identity, but recreate device-owned Vulkan objects per renderer lifetime. Warm artifact reuse solves known shaders, not genuinely unseen s…	982a6cd5eeec
#68	Vulkan shaders / pipelines	Closed unmerged · Historical / not merged	hw/xbox/nv2a/debug.h, hw/xbox/nv2a/pgraph/vk/glsl.c, hw/xbox/nv2a/pgraph/vk/meson.build +7 more	Shader-binding misses, stage-module misses, exact-source misses, glslang calls, and graphics-pipeline misses are different events. The reproduced primary hitch contained genuinely first-seen shader sources, so same-proc…	1ba2c59ee69c
#67	Vulkan texture / layout	Closed unmerged · Historical / not merged	hw/xbox/nv2a/pgraph/texture-layout.h, hw/xbox/nv2a/pgraph/vk/draw.c, hw/xbox/nv2a/pgraph/vk/perf.c +3 more	Cubemap-span diagnostics must separate guest texture-layout/span computation from Vulkan copy/pipeline cost before choosing an optimization.	86a2a9708b91
#64	Testing / performance reporting	Merged	Docs/evidence only	Performance percentages need one reader-facing sign convention: positive means favorable and negative means unfavorable, with the formula selected by whether higher or lower raw values are better.	0fcc09552af8
#63	Testing / benchmarking	Merged	Docs/evidence only	Reference and candidate measurements must start from equivalent cycle/run boundaries; misaligned starts can dominate small deltas without any code change.	9e1b8d51a7db
#62	Testing / benchmarking	Merged	Docs/evidence only	Keep accepted main separate from a frozen benchmark baseline so historical evidence stays reproducible while product development continues.	22008c3035a2
#59	Timing	Closed unmerged · Historical / superseded	hw/xbox/nv2a/nv2a.c, hw/xbox/nv2a/nv2a_int.h, hw/xbox/nv2a/pramdac.c +5 more	PTIMER work must separate guest-visible timer semantics from host scheduling mechanics; masked state, phase-aware deadline conversion, and clock/PLL changes all belong to the correctness contract.	0043629b0bc1
#58	Vulkan memory / synchronization	Closed unmerged · Negative result	hw/xbox/nv2a/pgraph/vk/renderer.h	A larger descriptor batch/capacity is not a performance win by itself; single-pair movements were insufficient and capacity changes can simply move the eventual wait.	3a56adfac81a
#57	Vulkan instrumentation / synchronization	Closed unmerged · Negative result	hw/xbox/nv2a/pgraph/vk/perf.c, hw/xbox/nv2a/pgraph/vk/renderer.c, hw/xbox/nv2a/pgraph/vk/renderer.h +1 more	Deferring telemetry output and exposing full-fence timing can separate instrumentation overhead from the actual synchronization dependency, but diagnostic attribution is not itself removable wait time.	3db2bbfecd51
#55	CPU / TCG	Closed unmerged · Negative result	target/i386/tcg/emit.c.inc, target/i386/tcg/translate.c	Reducing TCG exits around STI is only valid if x86 interrupt-shadow semantics remain exact; fewer dispatcher returns are not automatically a safe CPU optimization.	1a73c5bce07b
#54	CPU / TCG	Closed unmerged · Negative result	accel/tcg/cpu-exec.c, accel/tcg/cputlb.c, accel/tcg/tb-maint.c +4 more	Attribute why TCG returns to the dispatcher before attempting to reduce dispatch cost; a hot dispatcher is a symptom until its exit classes and dirty-TLB work are measured.	504a7e72637f
#53	Snapshot / MCPX APU	Merged	hw/xbox/mcpx/apu/apu.c	Snapshot load must quiesce the APU frame/DSP thread before VMState overwrites DSP state, with lock ordering that avoids a BQL/APU deadlock; resume only after restored state is synchronized.	c17591d59c27
#52	Testing / integration qualification	Closed unmerged · Historical / not merged	.github/workflows/build-tests.yml, .github/workflows/build-xemu-win64-toolchain.yml, .github/workflows/build.yml +87 more	A stacked fork PR set must be requalified on current upstream; output/hash differences are unresolved evidence, not automatic fixes or regressions.	51963c7be5cc
#51	Integration / release management	Closed unmerged · Negative result	accel/tcg/cpu-exec-common.c, accel/tcg/cpu-exec.c, accel/tcg/cputlb.c +99 more	Large integrated release trees are useful for system qualification but poor review units; preserve main and extract independently reviewable fixes/features from the aggregate branch.	dce89f5c1212
#50	Snapshot / lifecycle	Merged	hw/xbox/nv2a/nv2a.c, hw/xbox/nv2a/nv2a.h, hw/xbox/nv2a/nv2a_int.h +2 more	Paused snapshot save must hold FIFO/PGRAPH ownership consistently through serialization and balance pause/lock cleanup on every failure path.	bab07eb38920
#48	Timing	Closed unmerged · Negative result	hw/xbox/nv2a/nv2a.c, hw/xbox/nv2a/nv2a_int.h, hw/xbox/nv2a/pramdac.c +5 more	PTIMER fixes spanning masked alarms, deadline conversion, and PLL transitions need one coherent state model; superseded branches should feed successor requirements instead of being maintained in parallel.	cd5af56967f6
#47	Core utility / cache	Merged	include/qemu/lru.h, tests/unit/meson.build, tests/unit/test-lru-full.c	When LRU bookkeeping already proves the cache is full, skip scanning for a free node; encode that invariant with focused full-cache tests.	ff9625dddb32
#37	UI / performance controls	Merged	config_spec.yml, hw/xbox/nv2a/pgraph/gl/texture.c, hw/xbox/nv2a/pgraph/pgraph.c +16 more	Independent advanced performance toggles are valuable diagnostic controls because one optimization can be disabled without removing unrelated correctness behavior.	37cf6cbcc613
#25	Timing / host waits	Closed unmerged · Negative result	config_spec.yml, include/qemu/timer.h, scripts/performance/export-retail-cpu.ps1 +11 more	Windows CPU-saving waits must be judged on host CPU, guest cadence, tails, and wake correctness together; lower CPU consumption alone is not a performance acceptance result.	a2a444a85f29
#24	Timing / host waits	Closed unmerged · Historical / not merged	include/qemu/timer.h, tests/unit/meson.build, tests/unit/test-xbox-poll-profile-output.py +4 more	Interruptible Windows deadline waits can change scheduler behavior, but small mixed renderer deltas need repeated cross-renderer evidence before adoption.	172c4bd80a2e
#23	Timing / main loop	Closed unmerged · Historical / not merged	include/qemu/timer.h, util/main-loop.c, util/qemu-timer-common.c +1 more	The final event-loop timeout value is insufficient to diagnose short-deadline spinning; instrument which subsystem requested each deadline and against which clock.	e4874c74ccf9
#22	Timing / PTIMER	Closed unmerged · Historical / not merged	hw/xbox/nv2a/ptimer.c, tests/unit/ptimer-test-stubs.c, tests/unit/test-xbox-nv2a-ptimer.c	Porting the PTIMER scheduling repair onto a frozen baseline isolates whether sustained sub-millisecond polling is caused by PTIMER rather than unrelated branch drift.	3ca12096470a
#21	Timing / main loop	Closed unmerged · Historical / not merged	include/qemu/timer.h, util/qemu-timer-common.c, util/qemu-timer.c	Short-deadline spin diagnosis must separate clock-read cost from deadline ownership and poll-loop behavior; a QPC-only change showed only small mixed movement.	466741a87fb3
#18	NV2A texture / layout	Closed unmerged · Negative result	hw/xbox/nv2a/pgraph/texture-layout.h, hw/xbox/nv2a/pgraph/texture.c, tests/unit/test-xbox-nv2a-texture.c	Linear texture source-span calculations need consuming-path tests that fail on the old head and pass on the repair; exact byte spans matter for correctness and later overlap/coherency work.	2e801ab07c4a
#17	Testing / evidence	Closed unmerged · Historical / not merged	Docs/evidence only	Qualification evidence should be compact, sanitized, and separate from emulator code so reviewers can audit results without changing the tested binary.	fa496900e156
#16	NV2A texture / DMA	Closed unmerged · Negative result	hw/xbox/nv2a/pgraph/texture-layout.h, hw/xbox/nv2a/pgraph/texture.c, tests/unit/test-xbox-nv2a-texture.c	Texture DMA validation must include DMA class/target semantics in addition to address bounds; correctness coverage is not a performance acceptance result.	37823ccf1826
#15	Vulkan texture / layout	Closed unmerged · Negative result	hw/xbox/mcpx/apu/apu.c, hw/xbox/nv2a/debug.h, hw/xbox/nv2a/nv2a.c +38 more	A bordered-cubemap mip-copy repair proven only on a historical stacked branch must be extracted and requalified on current main before it can be treated as current architecture.	cb89434e45a5
#14	NV2A texture / layout	Closed unmerged · Historical / not merged	hw/xbox/nv2a/pgraph/gl/texture.c, hw/xbox/nv2a/pgraph/texture-layout.h, hw/xbox/nv2a/pgraph/texture.c +4 more	Compressed cubemap face stride and bordered mip layout require exact shared texture-layout math; correctness fixes should meet a neutral performance gate rather than being justified by speed.	a1645a8612b6
#13	Vulkan presentation	Closed unmerged · Historical / not merged	hw/xbox/nv2a/pgraph/vk/display-reuse.h, hw/xbox/nv2a/pgraph/vk/display.c, hw/xbox/nv2a/pgraph/vk/renderer.h +3 more	Completed Vulkan display output may be reused only while PVIDEO, pending uploads, surface recreation, and execution-mode changes cannot invalidate it; local reuse cost is not enough without cross-backend controls.	971873d94048
#12	Vulkan texture fast path	Closed unmerged · HOLD / historical	hw/xbox/nv2a/pgraph/vk/draw.c	A focused texture/sampler fast path can improve a micro-cell while still failing the GPU-load/power acceptance gate; local CPU savings do not outweigh broader GPU cost.	4190822eb6f4
#11	Vulkan failure handling	Merged	hw/xbox/nv2a/pgraph/vk/blit.c, hw/xbox/nv2a/pgraph/vk/display.c, hw/xbox/nv2a/pgraph/vk/draw.c +12 more	Preparation failures must propagate without clearing the dirty/retry state needed to attempt the resource again; partial surface/texture preparation must fail transactionally.	19944268d97e
#10	NV2A / PGRAPH	Merged	hw/xbox/nv2a/pgraph/inline-elements.h, hw/xbox/nv2a/pgraph/pgraph.c, tests/xbox/pgraph-inline-elements/pgraph-inline-elements-test.c	Validate the complete inline packet capacity before expanding pending draw work or mutating an inline destination; oversized packets must be rejected atomically.	659ad30be048
#9	NV2A / PGRAPH	Closed unmerged · Negative result	hw/xbox/nv2a/pgraph/pgraph.c, hw/xbox/nv2a/pgraph/pgraph.h	A narrower atomic PGRAPH fence read can increase completed guest work while also raising host CPU; throughput and per-unit efficiency must be separated before calling it an optimization.	67178d0af1e9
#8	Vulkan buffer / vertex lifetime	Closed unmerged · Negative result	hw/xbox/nv2a/pgraph/vk/buffer.c, hw/xbox/nv2a/pgraph/vk/draw.c, hw/xbox/nv2a/pgraph/vk/renderer.h	Growing transient Vulkan vertex buffers on demand can fix allocation pressure, but buffer replacement must preserve references/lifetime and focused forced-completion cells only establish allocation correctness.	33151b41fda2
#7	Vulkan vertex uploads	Closed unmerged · Negative result	hw/xbox/nv2a/pgraph/vk/draw.c	Remapped vertex uploads must be bounded to the exact valid guest/source range before performance work; correctness and current-main profiling are separate gates.	2c292414a8ea
#6	Vulkan texture / failure handling	Closed unmerged · Negative result	hw/xbox/nv2a/pgraph/vk/texture-state.h, hw/xbox/nv2a/pgraph/vk/texture.c, tests/unit/meson.build +1 more	Bounding Vulkan texture memory is only safe when preparation can return failure to callers without losing retry state; the error-capable contract is part of the correctness fix.	c1462ad7d88a
#5	Vulkan surface / readback	Closed unmerged · Negative result	hw/xbox/nv2a/pgraph/vk/surface.c	Folding color-download submissions is only safe when readback ordering and guest-visible completion remain intact; historical submission reductions need fresh current-main profiling before reuse.	3f9e6b6fa379
#4	Vulkan buffer / transfer usage	Closed unmerged · Historical / not merged	hw/xbox/nv2a/pgraph/vk/buffer.c	Vulkan scratch resources must declare every transfer role they actually perform; missing usage flags are a correctness/validation defect, but changing allocation usage can alter performance and needs requalification.	f6521c32101e
#3	Vulkan draw / query lifetime	Closed unmerged · Integrated	hw/xbox/nv2a/pgraph/vk/draw.c, hw/xbox/nv2a/pgraph/vk/perf.c, hw/xbox/nv2a/pgraph/vk/renderer.h +2 more	Draw preparation should be transactional: drain query capacity before a draw would overflow it, and preserve dirty/retry state so a failed preparation cannot discard required work.	af750282dead
#2	OpenGL / SDL context ownership	Merged	hw/xbox/nv2a/pgraph/thirdparty/gloffscreen/sdl.c, tests/unit/meson.build, tests/unit/test-xbox-gloffscreen.c	The offscreen SDL GL context and hidden window are owned resources and must be released in the correct teardown path; lifecycle leaks are correctness/resource bugs even without a performance campaign.	b1216d29ba63
#1	NV2A reports / DMA	Closed unmerged · Historical / not merged	hw/xbox/nv2a/dma.c, tests/unit/test-xbox-nv2a-dma.c	Valid IN_MEMORY PCI report destinations must be accepted through the same bounded unified-RAM mapping as NVM; preserve class, address, DMA-limit, RAM-end, and report-size validation rather than rejecting a valid target…	495a645cf934

Quick indexes

NV2A reports / DMA

• PR #1 — restore bounded PCI report completions for retail games — Closed unmerged · Historical / not merged — Valid IN_MEMORY PCI report destinations must be accepted through the same bounded unified-RAM mapping as NVM; preserve class, address, DMA-limit, RAM-end, and report-size validation rather than rejecting a valid target class.

OpenGL / SDL context ownership

• PR #2 — release owned SDL context and hidden window — Merged — The offscreen SDL GL context and hidden window are owned resources and must be released in the correct teardown path; lifecycle leaks are correctness/resource bugs even without a performance campaign.

Vulkan draw / query lifetime

• PR #3 — ENG-2026-523: drain query budgets and make draw preparation transactional — Closed unmerged · Integrated — Draw preparation should be transactional: drain query capacity before a draw would overflow it, and preserve dirty/retry state so a failed preparation cannot discard required work.

Vulkan buffer / transfer usage

• PR #4 — ENG-2026-523: declare zeta scratch transfer-source usage — Closed unmerged · Historical / not merged — Vulkan scratch resources must declare every transfer role they actually perform; missing usage flags are a correctness/validation defect, but changing allocation usage can alter performance and needs requalification.

Vulkan surface / readback

• PR #5 — ENG-2026-523: Port Vulkan color-download submission folding onto Stable S — Closed unmerged · Negative result — Folding color-download submissions is only safe when readback ordering and guest-visible completion remain intact; historical submission reductions need fresh current-main profiling before reuse.

Vulkan texture / failure handling

• PR #6 — ENG-2026-425 Correctness: revalidate bound Vulkan texture memory on S — Closed unmerged · Negative result — Bounding Vulkan texture memory is only safe when preparation can return failure to callers without losing retry state; the error-capable contract is part of the correctness fix.

Vulkan vertex uploads

• PR #7 — ENG-2026-430: Bound Vulkan remapped vertex uploads — Closed unmerged · Negative result — Remapped vertex uploads must be bounded to the exact valid guest/source range before performance work; correctness and current-main profiling are separate gates.

Vulkan buffer / vertex lifetime

• PR #8 — ENG-2026-450: Grow Vulkan transient vertex buffers on demand — Closed unmerged · Negative result — Growing transient Vulkan vertex buffers on demand can fix allocation pressure, but buffer replacement must preserve references/lifetime and focused forced-completion cells only establish allocation correctness.

NV2A / PGRAPH

• PR #10 — PGRAPH: reject oversized inline packets atomically — Merged — Validate the complete inline packet capacity before expanding pending draw work or mutating an inline destination; oversized packets must be rejected atomically.
• PR #9 — ENG-2026-432: Narrow atomic PGRAPH fence read — Closed unmerged · Negative result — A narrower atomic PGRAPH fence read can increase completed guest work while also raising host CPU; throughput and per-unit efficiency must be separated before calling it an optimization.

Vulkan failure handling

• PR #11 — Vulkan: propagate preparation failures without losing retry state — Merged — Preparation failures must propagate without clearing the dirty/retry state needed to attempt the resource again; partial surface/texture preparation must fail transactionally.

Vulkan texture fast path

• PR #12 — ENG-2026-523: Hold Vulkan texture pipeline fast path after GPU-load gate — Closed unmerged · HOLD / historical — A focused texture/sampler fast path can improve a micro-cell while still failing the GPU-load/power acceptance gate; local CPU savings do not outweigh broader GPU cost.

Vulkan presentation

• PR #13 — ENG-2026-513: Reuse completed Vulkan display output on cumulative S — Closed unmerged · Historical / not merged — Completed Vulkan display output may be reused only while PVIDEO, pending uploads, surface recreation, and execution-mode changes cannot invalidate it; local reuse cost is not enough without cross-backend controls.

NV2A texture / layout

• PR #18 — ENG-2026-523: Validate linear texture source spans — Closed unmerged · Negative result — Linear texture source-span calculations need consuming-path tests that fail on the old head and pass on the repair; exact byte spans matter for correctness and later overlap/coherency work.
• PR #14 — NV2A: fix compressed cubemap face stride and bordered mips — Closed unmerged · Historical / not merged — Compressed cubemap face stride and bordered mip layout require exact shared texture-layout math; correctness fixes should meet a neutral performance gate rather than being justified by speed.

Vulkan texture / layout

• PR #67 — attribute PR14 cubemap span work — Closed unmerged · Historical / not merged — Cubemap-span diagnostics must separate guest texture-layout/span computation from Vulkan copy/pipeline cost before choosing an optimization.
• PR #15 — ENG-2026-523: Fix Vulkan bordered cubemap mip copy extents — Closed unmerged · Negative result — A bordered-cubemap mip-copy repair proven only on a historical stacked branch must be extracted and requalified on current main before it can be treated as current architecture.

NV2A texture / DMA

• PR #16 — ENG-2026-523: Validate texture DMA class and target — Closed unmerged · Negative result — Texture DMA validation must include DMA class/target semantics in addition to address bounds; correctness coverage is not a performance acceptance result.

Testing / evidence

• PR #17 — ENG-2026-523: Publish repair-series qualification evidence — Closed unmerged · Historical / not merged — Qualification evidence should be compact, sanitized, and separate from emulator code so reviewers can audit results without changing the tested binary.

Timing / main loop

• PR #23 — ENG-2026-523: Attribute PGR2 main-loop deadline owners — Closed unmerged · Historical / not merged — The final event-loop timeout value is insufficient to diagnose short-deadline spinning; instrument which subsystem requested each deadline and against which clock.
• PR #21 — ENG-2026-523: Attribute PGR2 short-deadline poll spinning — Closed unmerged · Historical / not merged — Short-deadline spin diagnosis must separate clock-read cost from deadline ownership and poll-loop behavior; a QPC-only change showed only small mixed movement.

Timing / PTIMER

• PR #22 — ENG-2026-523: Port PTIMER scheduling repair onto frozen baseline — Closed unmerged · Historical / not merged — Porting the PTIMER scheduling repair onto a frozen baseline isolates whether sustained sub-millisecond polling is caused by PTIMER rather than unrelated branch drift.

Timing / host waits

• PR #25 — ENG-2026-523: Qualify optional Windows CPU-saving waits on S — Closed unmerged · Negative result — Windows CPU-saving waits must be judged on host CPU, guest cadence, tails, and wake correctness together; lower CPU consumption alone is not a performance acceptance result.
• PR #24 — ENG-2026-523: Test interruptible Windows deadline waits — Closed unmerged · Historical / not merged — Interruptible Windows deadline waits can change scheduler behavior, but small mixed renderer deltas need repeated cross-renderer evidence before adoption.

UI / performance controls

• PR #37 — Add performance toggles to Settings → Advance — Merged — Independent advanced performance toggles are valuable diagnostic controls because one optimization can be disabled without removing unrelated correctness behavior.

Core utility / cache

• PR #47 — lru: skip free-node scans when the cache is full — Merged — When LRU bookkeeping already proves the cache is full, skip scanning for a free node; encode that invariant with focused full-cache tests.

Timing

• PR #81 — NV2A: replace PTIMER host scheduling with explicit deadlines — Open draft · HOLD — Explicit keep/cancel/replace PTIMER deadline ownership can make scheduling easier to reason about, but fewer host timer operations are not a performance result; retail qualification can still regress.
• PR #59 — nv2a: preserve masked PTIMER state and correct future deadlines — Closed unmerged · Historical / superseded — PTIMER work must separate guest-visible timer semantics from host scheduling mechanics; masked state, phase-aware deadline conversion, and clock/PLL changes all belong to the correctness contract.
• PR #48 — nv2a: correct PTIMER deadlines, masked alarms and PLL transitions — Closed unmerged · Negative result — PTIMER fixes spanning masked alarms, deadline conversion, and PLL transitions need one coherent state model; superseded branches should feed successor requirements instead of being maintained in parallel.

Snapshot / lifecycle

• PR #92 — live snapshot renderer reinit exposes framebuffer wait (negative result) — Closed unmerged · Negative result — Live renderer reinitialization is coupled to UI/framebuffer ownership: the negative experiment blocked after renderer flush while waiting on a UI-held framebuffer. A future reset path needs an explicit framebuffer release contract before teardown.
• PR #50 — NV2A: balance paused snapshot saves and failure cleanup — Merged — Paused snapshot save must hold FIFO/PGRAPH ownership consistently through serialization and balance pause/lock cleanup on every failure path.

Integration / release management

• PR #51 — Prepare the S-based release tree while preserving main history — Closed unmerged · Negative result — Large integrated release trees are useful for system qualification but poor review units; preserve main and extract independently reviewable fixes/features from the aggregate branch.

Testing / integration qualification

• PR #52 — Test the fork PR set on current upstream xemu — Closed unmerged · Historical / not merged — A stacked fork PR set must be requalified on current upstream; output/hash differences are unresolved evidence, not automatic fixes or regressions.

Snapshot / MCPX APU

• PR #53 — APU: quiesce DSP safely before snapshot load on main — Merged — Snapshot load must quiesce the APU frame/DSP thread before VMState overwrites DSP state, with lock ordering that avoids a BQL/APU deadlock; resume only after restored state is synchronized.

CPU / TCG

• PR #55 — TCG: chain STI into its interrupt-shadow block — Closed unmerged · Negative result — Reducing TCG exits around STI is only valid if x86 interrupt-shadow semantics remain exact; fewer dispatcher returns are not automatically a safe CPU optimization.
• PR #54 — Diagnostic: attribute TCG lookups and dirty TLB scans on main — Closed unmerged · Negative result — Attribute why TCG returns to the dispatcher before attempting to reduce dispatch cost; a hot dispatcher is a symptom until its exit classes and dirty-TLB work are measured.

Vulkan instrumentation / synchronization

• PR #57 — Diagnostic: defer Vulkan telemetry output and expose full fence timing — Closed unmerged · Negative result — Deferring telemetry output and exposing full-fence timing can separate instrumentation overhead from the actual synchronization dependency, but diagnostic attribution is not itself removable wait time.

Vulkan memory / synchronization

• PR #89 — Vulkan: version bounded vertex draws across ordered updates — Open draft · Negative / HOLD — Bounded immutable vertex versions can preserve the bytes seen by earlier recorded draws while later guest writes advance to new storage, but versioning must remain bounded and inherit surface-freshness correctness.
• PR #88 — Vulkan: reuse graphics command state across pass restarts — Open draft · Negative / HOLD [Issue #86](https://github.com/…** — Reducing Vulkan command-state replay after render-pass restarts is only useful if end-to-end guest progress improves; a local CPU command reduction can be offset by changed lifetime or synchronization elsewhere.
• PR #87 — Vulkan: avoid vertex-copy pass breaks on fresh pages — Open draft · Negative / HOLD Current head `1d4524a6df0fac5822c7c8…** — A direct mapped vertex-RAM write is safe during an active Vulkan batch only when no earlier recorded draw has consumed the overwritten page; otherwise preserve ordered staging/barriers. Tracking cost is highly workload-dependent.
• PR #85 — Vulkan: avoid false surface readbacks for adjacent vertex data — Open draft · HOLD The source addresses the review…** — Before CPU-side vertex decoding/upload, prove guest memory is authoritative for the exact fetched range when GPU-authored surfaces may overlap it; coherency must precede optimization.
• PR #83 — Vulkan: descriptor-capacity interaction after vertex readback fix — Open draft · Negative / HOLD — Removing a descriptor-capacity finish does not prove faster execution when the same completion dependency moves to a later submit/fence boundary.
• PR #80 — Vulkan: skip clean texture stages during warm binds — Merged — A clean texture dirty bit is not sufficient cache identity. Warm texture reuse must also validate effective guest source/DMA identity and freshness.
• PR #58 — Vulkan: test a larger graphics descriptor batch — Closed unmerged · Negative result — A larger descriptor batch/capacity is not a performance win by itself; single-pair movements were insufficient and capacity changes can simply move the eventual wait.

Testing / benchmarking

• PR #63 — Align main and baseline at the same cycle-start commit — Merged — Reference and candidate measurements must start from equivalent cycle/run boundaries; misaligned starts can dominate small deltas without any code change.
• PR #62 — Preserve accepted main and establish the fixed baseline workflow — Merged — Keep accepted main separate from a frozen benchmark baseline so historical evidence stays reproducible while product development continues.

Testing / performance reporting

• PR #64 — make performance percentages positive-good — Merged — Performance percentages need one reader-facing sign convention: positive means favorable and negative means unfavorable, with the formula selected by whether higher or lower raw values are better.

Vulkan shaders / pipelines

• PR #78 — tests: prove Vulkan ubershader combiner semantics — Closed unmerged · Historical / not merged — A CPU-side combiner oracle and focused semantic tests can validate ubershader math before GPU integration; semantic equivalence is a separate gate from enabling runtime selection.
• PR #77 — define Vulkan hybrid ubershader contracts — Closed unmerged · Historical / not merged — Define hybrid routing policy, control ABI, retry metadata, and fail-closed admission as testable contracts before wiring a runtime fallback into the renderer hot path.
• PR #71 — feature: add optional Vulkan ubershader — Open draft · Negative / HOLD — 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…
• PR #70 — Vulkan: reuse validated SPIR-V across warm runs — Merged — Persist exact compiled SPIR-V artifacts across runs using stable source/compiler identity, but recreate device-owned Vulkan objects per renderer lifetime. Warm artifact reuse solves known shaders, not genuinely unseen specialization.
• PR #68 — Vulkan: classify shader-module misses in the binding hot path — Closed unmerged · Historical / not merged — Shader-binding misses, stage-module misses, exact-source misses, glslang calls, and graphics-pipeline misses are different events. The reproduced primary hitch contained genuinely first-seen shader sources, so same-process deduplication alone could not solve…

NV2A reports / synchronization

• PR #74 — NV2A: validate report bounds and retire idle Vulkan reports — Closed unmerged · Historical / superseded — Report writes need shared bounds validation before backend serialization, and Vulkan report retirement must preserve guest-visible completion ordering; targeted correctness alone is not enough when cross-backend tail behavior regresses.

Vulkan renderer

• PR #75 — Vulkan: select and report the host GPU by UUID — Merged — Renderer benchmarking and compatibility require exact physical-device identity; requested GPU, initialized GPU, capabilities, and reported adapter must agree.

Vulkan renderer / presentation

• PR #76 — Vulkan: fall back to host copy across presenter GPUs — Merged — Vulkan rendering and OpenGL presentation can live on incompatible adapters; external-memory sharing needs an explicit compatibility test and a bounded host-copy fallback.

How to review/update a PR

Use the fixed scan order on every detail page: Status → At a glance → Code impact → Flow → What changed → Result → Lesson learned → Avoid repeating → Docs/evidence → Related architecture.

When an open PR moves, update the reviewed SHA/date and mutable implementation/result sections. Keep the historical lesson unless newer evidence actually overturns it; if it does, state what superseded the old lesson rather than silently erasing it.

Hot-path shortcut catalog

Hot-Path Shortcuts turns accepted and held PR lessons into a searchable mechanism catalog. Each detail page links back to the relevant PR evidence and explicitly separates historical measurements from reviewed-main behavior.

Issue #106 / PR #119 — surface authority and transition debugging

Reference	Purpose
PGR2 Race-to-Menu Corruption — Lessons Learned	Canonical root-cause, rejected hypotheses, ownership model, and reusable lessons
Graphics Transition Debugging Tools	Deterministic runner, guest/window capture, RenderDoc, stable resource identity, and writer traces
PR #119 implementation history	Files changed, repair shape, and focused validation

The issue established that a texture cache can correctly upload and retain bytes that another stale representation already wrote incorrectly. Review surface/guest-memory authority and consumer-specific dirty clients before adding cache flushes, queue waits, or broad revalidation.

A PR is implementation history. The canonical subject page is the go-to reference for the mechanism and future investigations.

Recent PR lessons — September 16–18, 2026

These entries preserve durable engineering lessons from the recent PR sequence. The PR page is implementation/test history; the linked subject page remains the primary technical reference.

PR	Subject	Durable lesson	Primary reference
#120	Merge upstream through f9b14039 with guarded DXGI presentation	Optional host integrations must have a truly inactive path. Initialization/fallback work can regress performance even when the feature is effectively unused; gate setup on effective use and back off after failure.	Performance-Methodology
#121	PGRAPH: validate complete ZPASS report bounds	Validate the complete memory transaction, not merely its starting address. Model inclusive DMA limits, exclusive backing sizes, and overflow with subtraction-safe arithmetic.	Memory-and-DMA
#122	Vulkan: retire idle queued reports without a command buffer	A shared finish or retirement API can have a CPU-only branch. Instrument the actual operation rather than inferring a GPU wait from a function name, and make ownership timing explicit in oracles.	Performance-Research-G03-Deferred-Report-Completion
#123	PGRAPH: validate array packets before bulk selection	Correctness invariants belong before optimization/reference-route selection. A performance toggle must never disable packet bounds, atomicity, or rejection rules.	Using-Hot-Path-Shortcuts
#124	Vulkan: revalidate texture DMA sources before clean reuse	Stable guest handle identity is not stable source identity. Re-resolve indirect DMA and palette sources before a clean reuse shortcut.	Hot-Path-Vulkan-Clean-Texture-Stages
#125	OpenGL: reconcile GPU surfaces before vertex fetches	Resolve the complete consumed span and newest representation before CPU pointers or decoding. Scope lifecycle must stay submitted once any segment submits.	OpenGL-Renderer
#127	OpenGL: use checked cubemap face stride	Stored compressed layout and sampled LOD are different concepts. Count complete BC blocks and mips, reject overflow before pointer arithmetic, and preserve retry dirtiness on failure.	Memory-and-DMA
#129	Vulkan: retain hybrid fallback family preparation	Shared family availability and per-owner admission are separate state. Retry ownership must survive deferral or failure, and fan-out only updates enrolled owners.	Performance-Research-G07-Hybrid-Ubershader-Specialization
#130	Vulkan: admit fallback combiners without active mux	Admission checks should inspect state actually consumed by active work. A global unsupported mode is irrelevant when no active stage uses it.	Performance-Research-G07-Hybrid-Ubershader-Specialization
#131	Vulkan: remove uniform-only pipeline key permutations	Pipeline identity should exclude values proven runtime-uniform-only. Canonicalize consistently across lookup, fallback, background work, and publication.	Performance-Research-G09-Pipeline-Key-Minimization
#132	PGRAPH: remove PFIFO/PGRAPH inversion from renderer switching	Lock ordering is insufficient when progress depends on another thread acquiring those locks. Use phased handoff, nonblocking acquisition, bounded progress service, and event-driven retry.	Performance-Research-C04-PFIFO-PGRAPH-Dispatch-Handoffs
#133	Vulkan: attribute report queue lifecycle on current main	Lifecycle telemetry should record interpretable aggregate state and do zero accounting when disabled. Wait attribution is not proof of legal deferral.	Performance-Research-G03-Deferred-Report-Completion
#138	NV2A: initialize unused pixel-shader bump uniforms	Any producer whose reflected bytes are compared or copied must initialize those bytes deterministically. Shared correctness prerequisites belong identically beneath both benchmark roles.	Performance-Research-G01-Warm-Shader-Uniform-Work

Open/draft reviewed-head notes

Open PRs can move. These notes are bounded to the reviewed head and are not implementation-status claims.

PR	Reviewed head	Lesson carried into Wiki	Primary reference
#134	4359f048	Descriptor publication obligation survives until actual publication.	G05
#135	071c1d06	Reconcile texture-derived uniforms at the consumer and measure actual writes.	G01
#136	5f2c93ee	Compile-time-disabled text diagnostics should be true no-ops.	Debugging Tools
#137	8311cfd8	Disabled or already-written event logging returns before string work or mutex acquisition.	Debugging Tools