From beb61d90b1bfdb5465c7f6b47dcf78620a6d798a Mon Sep 17 00:00:00 2001 From: Matthew Stanley <1379tech@gmail.com> Date: Fri, 4 Sep 2026 22:59:51 -0700 Subject: [PATCH] docs: record OpenGL performance burndown and acceptance gates --- docs/PERFORMANCE_CAMPAIGN.md | 102 +++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 docs/PERFORMANCE_CAMPAIGN.md diff --git a/docs/PERFORMANCE_CAMPAIGN.md b/docs/PERFORMANCE_CAMPAIGN.md new file mode 100644 index 00000000..1fde7678 --- /dev/null +++ b/docs/PERFORMANCE_CAMPAIGN.md @@ -0,0 +1,102 @@ +# OpenGL performance campaign + +Tracking: central Beads `beads-jod2`, beneath `beads-eio.3` (psxrecomp framework). +Branch: `perf/opengl-burndown-20260904`. +Starting revision: `bf61b1054313e1c80d5c2bf1b14a1e50f2e54b8a`. +This is the audited integration revision, not a claim about a shipped release. + +## Objective and constraints + +Improve sustained guest speed, frame consistency, and resource use at identical +settings and correctness. OpenGL is the primary renderer. Vulkan completeness +is a separate qualification exercise, never a substitute for an OpenGL fix. +Use GPT-5.5 agents for bounded implementation and independent adversarial review +of their code, measurements, and acceptance claims. + +The primary route is Ape Escape, Crabby Beach, approaching and facing the water. +Inspect existing `ApeEscapeRecomp/saves/scph1001` states before choosing one; +preserve originals and record BIOS, state hash, scene, and input sequence. +Add quiet gameplay, facing away, and a transition, plus Tomba 2 and Mega Man X6 +regression routes. Compare guest speed, game-produced frames, and host presents +separately to avoid treating original-game slowdown as host overload. + +Test unrestricted, 50%, and 25% host CPU budgets, with affinity recorded as a +separate variable. Never change guest clocks to simulate hardware. CPU throttling +does not emulate older caches, memory bandwidth, or integrated graphics. Real +acceptance targets are an older 2-core/4-thread integrated-graphics PC and a +Deck-class handheld, with desktop and supported-platform regression coverage. + +## Work packages + +This table defines the approved work, not its live issue status. Beads owns +status and dependencies; experiment results belong in the evidence ledger. + +| ID | Work and candidate experiments | Required evidence | +| --- | --- | --- | +| P0-1 | Repeatable route runner, artifact/config identity, machine-readable A/B reports | Same guest work, reproducible baseline, measured noise | +| P0-2 | Release flags, effective settings, overlay inventory, cache rejection and compiler failures | Clean-install Windows/Linux behavior without development caches | +| P1-1 | Unused audio/GPU histories, memory observers, tracing/logging, diagnostic allocations | Measured saved work; retain functional observers and cheap health counters | +| P1-2 | GL batch breaks, texture/CLUT dependencies, packing, readbacks, uploads, buffer streaming | Identical order, masks, blending, texture feedback, VRAM and enhanced output | +| P1-3 | Swap blocking, pacer ownership, spinning, refresh/focus, interpolation and audio delivery | No speed drift, latency regression or new underruns | +| P1-4 | Overlay discovery, validation, loading, fallback, compilation contention and cache growth | Correct identity across replacement, self-modification, restore and cold installs | +| P2-1 | Generated code, dispatch, continuations, state traffic, interpreter, lookup/linking | Exceptions, delay slots, resumes and invalidation across all execution tiers | +| P2-2 | RAM/MMIO, aliases, observers, cycle publication, deadlines and idle detection | Exact cycle charges, side effects and event ordering | +| P2-3 | GTE/PGXP state copies, inactive hooks and shadow validation | Exact GTE state and unchanged enabled enhancements | +| P2-4 | SPU/resampling, CD/XA, MDEC, DMA, disc/decompression/card I/O; SIMD/batching/prefetch | Audio, IRQs, backpressure, decode output and completion timing | +| P2-5 | Allocation, bandwidth, locality, texture caches, mods/UI, rewind, netplay | Bounded memory, enabled-feature parity and inexpensive inactive paths | +| P2-6 | PGO/LTO, compiler options, code layout, portable SIMD and build costs | Multi-title gains, arithmetic parity and portable release artifacts | +| P3-1 | Threads, helper processes and GPU compute for attributed hotspots | End-to-end constrained-host gains including all transfer/sync costs | +| P3-2 | Software renderer hotspots and separate Vulkan qualification | Explicit coverage gaps; OpenGL acceptance remains mandatory | +| P4-1 | Release integration and recurring performance gates | Clean-install route, correctness and resource checks on shipped artifacts | + +Complete broad attribution before concentrating implementation on the largest +cost. Every area receives a measured disposition, including already optimized, +rejected, or deferred with a concrete missing prerequisite. Do not infer impact +from source size, suggestive names, or another console's bottlenecks. + +## Measurement and acceptance + +Follow [HOST_OPTIMIZATION_CONTRACT.md](HOST_OPTIMIZATION_CONTRACT.md). +Use at least three interleaved A/B pairs with all raw results, minima, medians, +discard reasons, a preregistered primary metric, and the 5% retention gate for +added complexity. Use forced faithful/candidate selectors where practical. + +Separate warm-cache throughput (fixed guest work; no compiler activity) from +first-use and transition campaigns where compilation/loading is the subject. +The latter must be explicitly labeled and must not be represented as satisfying +the quiet-host warm-cache gate. Use 120-second paced windows for stutter. +Record source and artifact hashes, generated code, BIOS, toolchain, effective +settings, overlay contents, power state, pacing owner and instrumentation. + +Attribute CPU samples and thread waits, GL scene/present time, readback/upload +bytes, execution tiers, device work, audio underruns, memory, allocations, page +faults and I/O. Expensive profiling is for attribution; final timing must also +run without it. Missing or reset counters must never become zero-cost evidence. + +Compare deterministic guest state at intermediate checkpoints, including cycles, +deadlines, pending exceptions, device state, RAM/VRAM/SPU RAM and overlay identity. +Add rendered-output/audio comparisons and candidate hit witnesses. Exercise +invalidation, aliases, exceptions, DMA, save/load, rewind and netplay as affected. +Do not claim parity from a fallback that silently avoids the candidate. + +For offload, specify ownership, immutable inputs, publication deadlines, bounded +queues, backpressure, cancellation and restore before coding. Compare inline +against one worker first. No races on guest memory, altered device ordering, or +implicit cross-thread GL context use. Count IPC, copying, driver contention, +memory and synchronization in the gain, especially on low-core-count/iGPU hosts. + +## Initial evidence and completion + +Source inspection found always-on audio PCM history and GP0 history, potential +GL full-VRAM readback, and multiple VRAM copies. These are hypotheses, not +measured causes of Crabby Beach slowdown. Widescreen overhang detection is +functional; its census already has a gate. Vulkan already has a staging cache. +Cycle batching, event deadlines, sparse probes, MDEC SIMD and GPU-direct GL +presentation already exist and must not be proposed as new work without audit. + +Append accepted, rejected and incomplete experiments to an evidence ledger with +raw-data links. Keep issue status in central Beads and record landed commits. +Do not close the campaign until every work package has a disposition and accepted +improvements reach validated title releases. Target sustained real-time execution +at preserved settings on the selected hardware, without new correctness, audio, +or pacing failures. Record hardware limitations rather than hiding them.