Using Hot Path Shortcuts

Using Hot-Path Shortcuts

Purpose: Run controlled optimized-versus-reference experiments without confusing a requested setting with the route xemu actually executed.

Reviewed source: Mainkill1/xemu 322986f4c5502b3fa887a9605ac8cd88e9b2c579 on 2026-09-14.

Status boundary: Current main has several boolean controls. Issues #93 and #94 plan typed requested/effective status, non-persistent CLI overrides, route counters, and machine-readable evidence. Commands and fields marked planned are not claimed to exist in the reviewed binary.

Start with Hot-Path Shortcuts for the catalog, risks, and per-shortcut technical pages. This page is the operator/tester procedure.

---

1. Start With a Causal Question

A shortcut test should answer one narrow question:

Does this symptom or cost change when one already-guarded optimized route is permitted versus when its maintained reference route is used?

Do not begin with “turn every optimization off.” That produces a different emulator and destroys attribution.

Good questions:

• Does the PGR2 stall disappear when hybrid fallback is enabled?
• Does stale output disappear when scanout reuse is forced through a fresh render?
• Does short-wait CPU use fall without worsening wake tails?
• Does texture-binding CPU change when eligible clean stages are deliberately rebound?

Bad questions:

• Is fast mode better?
• Which combination of nine toggles gives the highest average FPS?
• Can a correctness guard be disabled to see whether it is expensive?

---

2. Confirm What Exists in the Tested Build

Before launch, record:

commit
executable SHA-256
build profile
renderer
GPU and driver
shortcut implementation status
control implementation status
counter/evidence implementation status

The underlying route, menu control, planned typed policy, planned CLI, and planned evidence exporter are separate features. A Wiki page can describe all of them without implying they all exist in one binary.

Use the per-shortcut Status section:

• PGRAPH Bulk Packet Processing
• PGRAPH Fast Fence Polling
• Vulkan Hybrid Ubershader
• Vulkan Skip Unchanged Shader Work
• Vulkan Color-Download Folding
• Vulkan Bounded Vertex Uploads
• Vulkan Transient-Buffer Growth
• OpenGL Native S3TC Upload
• Windows Short-Wait Policy
• Vulkan Shader Caching
• Vulkan Clean Texture-Stage Skipping
• Vulkan Unchanged Scanout Reuse
• Windows QPC Clock Conversion

---

3. Requested Is Not Effective

The current boolean framework publishes active bits to workers. The planned #93 framework adds explicit status:

Field	Meaning
Requested	Saved setting or non-persistent CLI intent
Effective	Route policy actually published to this process/renderer
Availability	Whether backend/platform/capability can support the request
Apply state	Active now or waiting for restart/recreation
Reason	Why requested and effective differ

A comparison belongs to the effective route, not the requested label.

Requested: Persistent exact SPIR-V
Effective: Process only
Restart pending: Yes

This is a Process only run. It is not a persistent-cache run.

Requested: Auto
Effective: Disabled
Availability: Unsupported backend

This is not evidence about the optimized route.

---

4. Prove Route Reachability Before Reading Performance

For every run answer:

Did the subsystem execute?
Did the eligibility checks pass?
Did the optimized side take the optimized route?
Did the reference side take the maintained route?
Why were other attempts blocked?

A setting field alone cannot answer these questions.

Examples:

Vulkan-only route + OpenGL workload
    -> requested recorded
    -> effective unavailable
    -> no meaningful attempts

Persistent shader mode + already-live modules/pipelines
    -> shader requests occur
    -> persistent lookup attempts remain zero
    -> persistent layer was not tested

Scanout reuse + scene changes every display update
    -> display path executes
    -> reuse eligibility remains zero
    -> reuse benefit was not tested

Counters must define their unit, owner, and reset boundary. An absent counter is not automatically zero.

---

Experiment Protocols

Different shortcut classes require different run designs. Do not force every control into one generic ABBA procedure.

---

5. Functional Isolation Protocol

Use this for a crash, visual corruption, stale output, incorrect shader, missed wake, or other deterministic defect.

flowchart TD
    A[Reproduce symptom on exact Release binary] --> B[Pin workload and input]
    B --> C[Reference route]
    B --> D[Optimized route]
    C --> E[Correctness oracle]
    D --> E
    E --> F{Symptom changes and route evidence is valid?}
    F -->|No| G[Shortcut is not causal or workload is inadequate]
    F -->|Yes| H[Inspect the shortcut's guards, state, and invalidation]

Loading

Required evidence:

• same executable;
• same workload/input;
• route reached on both sides;
• deterministic output/oracle;
• repeated reproduction;
• no unrelated setting changes.

ABBA can improve confidence, but the decisive evidence is route-specific reproduction plus a correctness oracle.

---

6. Normal Live Same-Binary Performance Protocol

Use for live controls whose state does not contaminate later runs.

Minimum balanced sequence:

A1 reference -> B1 optimized -> B2 optimized -> A2 reference

Prefer a reverse group as well:

B3 optimized -> A3 reference -> A4 reference -> B4 optimized

flowchart LR
    A1[A1 reference] --> B1[B1 optimized]
    B1 --> B2[B2 optimized]
    B2 --> A2[A2 reference]
    A2 --> V[Validate identity, effective state, route evidence and correctness]
    V --> S[Compute distributions and resource differences]

Loading

Keep fixed:

• executable hash and commit;
• Release build profile;
• renderer and selected adapter;
• workload, snapshot/seed, and input sequence;
• guest-progress window;
• resolution/display state;
• unrelated settings;
• evidence/capture configuration.

Report p50, p95, p99, maximum, guest progress/fixed work, host CPU/GPU, RAM/VRAM where relevant, and route counters.

---

7. Persistent-Cache Cold/Warm Protocol

Normal ABBA is not sufficient when one run writes artifacts that alter the next run.

For Vulkan Shader Caching:

flowchart TD
    A[Create isolated cache directory] --> B{Cell type}
    B -->|Cold| C[Verify empty cache manifest]
    B -->|Seeded warm| D[Restore exact approved cache snapshot]
    C --> E[Launch one process]
    D --> E
    E --> F[Record lookups, hits, rejections, compiles and publications]
    F --> G[Hash/archive resulting cache separately]
    G --> H[Discard or restore before next cell]

Loading

Each cell needs:

• isolated cache path;
• initial cache hash/manifest;
• final cache hash/manifest;
• exact mode/effective state;
• cold versus warm label;
• persistent lookup and publication counts;
• compiler count/time;
• no cache state silently carried between cells.

Do not pool cold and warm results. Do not claim a persistent-cache benefit when another process-level cache satisfied every request first.

---

8. Restart-Latched Protocol

Use for controls whose hot path must not read mutable configuration, including the current hybrid ubershader and planned QPC diagnostic.

flowchart TD
    A[Set requested mode] --> B[Save without claiming it is active]
    B --> C[Exit process cleanly]
    C --> D[Launch exact same executable]
    D --> E[Verify effective route and restart_pending false]
    E --> F[Run fixed workload]
    F --> G[Exit and repeat next balanced cell]

Loading

A live UI change followed immediately by a benchmark measures the old effective route.

Record startup logs/state because constructor or renderer-creation decisions can precede the normal UI.

---

9. Live-Transition and Invalidation Protocol

Use when a live policy change must invalidate retained state, such as planned scanout-reuse control #96.

sequenceDiagram
    participant UI as UI/control thread
    participant R as Renderer owner
    participant S as Retained state
    UI->>R: Publish policy generation/change
    R->>R: Observe at safe owner boundary
    R->>S: Invalidate pre-change retained key/result
    R->>R: Force next operation through fresh path
    R->>S: Publish new state only after completion
    R-->>UI: Effective generation observed

Loading

Qualification must prove:

• policy changes are observed by the owner thread;
• no old retained object crosses the boundary;
• the first post-change operation takes the required fresh route;
• later reuse occurs only under the new policy and a new valid key;
• teardown/recreation remains correct.

Do not let the UI thread mutate renderer-owned state directly merely to make a setting feel immediate.

---

10. Planned CLI and Evidence Contract

Issue #94 proposes non-persistent overrides so automation does not rewrite a developer's saved configuration.

Planned shape:

xemu.exe \
  -xemu-tweak vk_skip_clean_texture_stages=disabled \
  -xemu-shortcut-evidence C:\evidence\pgr2-A1.json

Required lifecycle:

saved configuration
    -> apply override in memory
    -> resolve requested/effective state
    -> run workload
    -> snapshot owner counters
    -> export evidence
    -> exit without persisting override

Unknown keys, values, unsupported combinations, or unwritable explicitly requested evidence paths must fail loudly. A silently ignored override invalidates the run.

Until #94 is implemented, use the actual controls and capture mechanisms present in the tested binary and state that the planned CLI/evidence contract was unavailable.

---

11. Read Evidence in This Order

1. Executable identity — same expected binary and build?
2. Workload identity — same renderer, adapter, title/test, seed, input, progress window?
3. Requested state — intended setting supplied?
4. Effective state — intended route actually active?
5. Restart/apply state — no pending change?
6. Reachability — subsystem and exact eligibility path exercised?
7. Reference proof — reference side actually entered maintained route?
8. Correctness — same guest-visible oracle and validation outcome?
9. Local work — what was skipped, reused, batched, or moved?
10. End-to-end performance/resources — only after all earlier gates pass.

---

12. Reject Invalid Comparisons

Reject before calculating percentages when:

• executable/commit/build differs unexpectedly;
• renderer, adapter, workload, input, or fixed progress differs;
• requested did not become effective;
• restart is pending;
• optimized side has zero relevant attempts/hits;
• reference side never enters its maintained route;
• cache or retained state was not restored as required;
• required counters or output files are missing;
• accounting identities do not close for a fixed-policy window;
• correctness, hashes, visual oracle, event readiness, or validation output differs;
• instrumentation differs between A and B;
• a setup/launcher/export failure is mixed into the accepted workload.

An invalid run can still reveal a tooling defect. It is not a performance result.

---

13. Separate Local and End-to-End Results

A valid report has both layers.

Local route evidence

Examples:

• packet words handled per dispatch;
• locked versus atomic fence reads;
• specialized versus ubershader draws;
• avoided shader-route recomputation;
• folded versus auxiliary color downloads;
• vertex bytes copied;
• transient growth events/capacity;
• native compressed uploads versus CPU decodes;
• high-resolution waits versus busy-spin fallbacks;
• persistent hits/rejections/compiles;
• clean stages skipped;
• scanout conversions avoided;
• exact multiply versus muldiv64 route.

Whole-workload evidence

guest progress or fixed work
p50 / p95 / p99 / maximum interval
wall duration
host CPU time/utilization
host GPU time/utilization
RAM / VRAM
validation and correctness result
teardown/restart result

A local -80% helper result with unchanged frame tails means the helper was not limiting, its cost was hidden, or work moved elsewhere.

---

14. Evidence Storage and Summary

Detailed artifacts belong under the established evidence hierarchy, including:

evidence/wiki-xiso-per-test/

A PR/Wiki summary should retain:

Identity
Current versus planned feature status
Requested/effective/apply state
Initial cache/retained-state conditions
Route reachability and accounting
Correctness/validation
Local avoided work
End-to-end distributions
CPU/GPU/memory tradeoffs
Known limitations
Decision and next gate

Do not paste raw multi-thousand-row counters into the Wiki. Link the machine-readable evidence and state the decision-quality facts.

---

15. Final Decision Vocabulary

Use one of these conclusions:

Decision	Meaning
Keep Auto/On	Correct and supported; benefit/tradeoff justifies maintained default
Keep selectable	Useful diagnostic or host tradeoff, but no universal default claim
Developer-only	Valuable for causal comparison; inappropriate as ordinary user tuning
HOLD	Promising or necessary, but correctness/performance/lifetime evidence incomplete
Negative result	Tested idea did not improve the intended workload or exposed a blocker
Remove control	Route no longer useful, reference cannot be maintained, or result is redundant

The goal is not more switches. The goal is reproducible isolation without accidentally changing the emulator's contract.

Research candidates without a product control

The prepared-work candidate pages may describe a source-backed opportunity before any Advanced setting, CLI override or evidence exporter exists. In that state:

1. add the smallest diagnostic/test-only route that isolates the transformation;
2. preserve the current path as the maintained reference;
3. prove route reachability with subsystem-owned counters;
4. use the feature-specific correctness oracle before performance statistics;
5. remove the switch after qualification when an exhaustive transformation does not represent a meaningful compatibility choice.

Do not report Auto, Disabled, requested/effective state or command-line syntax for a candidate until those interfaces actually exist in the tested build.