Performance

Performance

Performance documentation is organized by measurement method and subsystem, not by pull-request number.

Start here

Goal	Page
Run or review a trustworthy performance comparison	[[Performance Methodology
Understand CPU/vCPU hot paths	[[CPU & vCPU Execution
Understand timer/wakeup costs	[[Clocks & Timers
Understand shared graphics work	[[NV2A Graphics Architecture
Investigate Vulkan-specific costs	[[Vulkan Performance
Compare OpenGL and Vulkan behavior	[[OpenGL vs Vulkan

Performance layers

A frame or guest-progress interval can contain work from multiple independent systems:

flowchart LR
    A[vCPU / TCG] --> B[Guest device interaction]
    B --> C[PFIFO / PGRAPH]
    C --> D[Renderer CPU work]
    D --> E[Host GPU work]
    E --> F[Synchronization / completion]
    F --> G[Presentation / guest-visible progress]

Loading

An optimization is only useful if it reduces the total dependency that matters to the workload. Moving a wait from draw_flush to report retirement, or moving shader work from xemu into a driver call, is not automatically a net improvement.

Primary regions to classify

Region	Examples
CPU execution	Generated guest code, TB lookup/dispatch, translation, TLB/memory helpers
Device/timing	MMIO, timer-list work, callbacks, IRQ transitions, host wait precision
Shared NV2A	Pushbuffer parsing, PGRAPH state changes, texture/surface decisions
OpenGL renderer	Program binding, GL state churn, surface readback, glFinish, driver CPU time
Vulkan renderer	Shader compilation, pipeline creation, descriptors, render-pass lifetime, barriers, queue/fence waits
Presentation	GPU selection, shared external memory, host-copy transport, VSync/compositor effects

Measurements are not interchangeable

The following can all be useful, but answer different questions:

• Host CPU samples.
• Host GPU timestamp spans.
• Guest frame intervals.
• NV2A display-write cadence.
• Report/query completion cadence.
• Presented host FPS.
• XISO test duration.

A result must state which one it uses. For example, NV2A display writes are a guest-progress proxy, not proof of host-presented FPS.

Research pages

The current Vulkan research sequence remains documented in depth:

1. Shader Binding & Compilation — classify synchronous shader/module/pipeline work.
2. Ubershader & Hybrid Specialization — research a fallback path for genuinely unseen specialization.
3. Vertex Uploads & Render-Pass Lifetime — reason about buffer freshness, ordered copies, pass splitting, and synchronization.

These are architecture/performance investigations, not a list of automatically accepted optimizations. Current PR state is summarized under Development.