RingOut · SOULCALIBUR II static recompilation · engineering reference

The RingOut Bench

The two machines, the toolchain, the measuring instruments, and every trap that has cost this project a session. Written so the next person — or the next session — starts from what is already known instead of rediscovering it. Every number here came from a run on this hardware.

The two machines

hardware

Every result in this project belongs to one of these two. They are not interchangeable: the desktop has GPU headroom the Deck does not, and the Deck is the machine where the frame rate is actually tight. A result measured on one transfers to the other only when the bottleneck is the same.

Development desktop

CPU
AMD Ryzen 5 5600X — 6 cores / 12 threads, Zen 3, single CCD. Boost ceiling 4762 MHz; 4573 MHz observed under emulation load.
GPU
NVIDIA GeForce RTX 3050, 8 GB, driver 610.57.04
Memory
31 GiB, plus 63 GiB swap
Displays
Three outputs: DP-3 1024×1280 portrait at x=0 · DP-2 1920×1080 at x=1024 (priority 1) · HDMI-A-1 1920×1080 at x=2944
Role
All builds, all A/B benchmarking, PGO profile training, packaging

Steam Deck

CPU
Zen 2, 4 cores / 8 threads. Effective clock under load 3.275–3.327 GHz measured as cycles ÷ wall.
GPU
RDNA2 integrated, Mesa RADV
OS
SteamOS — /usr read-only, glibc ~2.37
Power
8 W package draw during emulation against a 15 W cap — the workload never approaches the limit
Network
Static address over the dock's ethernet. Undocked it moves to wifi on a different subnet, where netplay cannot reach the desktop at all.
Install path
~/Desktop/steamdeck/ — the only install, and the Steam shortcut target
Role
Target hardware. Frame-rate truth: 45–49 fps before optimization, 56.9 fps after.

OS and toolchain

environment
OS
CachyOS (Arch-family), kernel 7.2.0-rc7-1-cachyos-rc-gcc
Desktop
KDE Plasma on Wayland, KWin 6.7.4. Konsole as terminal, fish as the interactive shell.
Compiler
clang 22.1.8, target x86_64-pc-linux-gnu
Linker
LLD 22.1.8 — required, not preferred: --thinlto-cache-dir is an lld option. It is probed with check_c_source_compiles rather than assumed, because lld ships as a separate package from clang on Arch, Debian and Fedora alike.
Build
CMake 4.4.2, Ninja 1.13.2
Profiles
llvm-profdata 22.1.8 for merging and inspecting PGO data
LLVM backend
Pinned to LLVM 19–20 only — it hard-fails outside that window. Debian 12 ships 14, this host has 22, Arch offers 18, so it lives in .github/containers/llvm19.Containerfile.
Containers
podman (daemonless, rootless) for the Debian 12 build container. Docker is present only for the WinBoat Windows VM.

Compile flags that matter

-march=native -O3 -flto=thin -fvisibility=hidden -fno-semantic-interposition -ffp-contract=off

-march=native is passed by setup.sh as CMAKE_C_FLAGS; -O3 comes from CMAKE_BUILD_TYPE=Release. -ffp-contract=off is not optional — floating point must stay bit-exact for netplay lockstep. There is no -ffast-math anywhere and there must not be.

Adding flags to CMAKE_C_FLAGS cannot raise the optimization level

recurring

CMake emits CMAKE_C_FLAGS before the per-configuration Release flags, so appending -O3 there changes nothing — the later flag wins. Three separate suggestion documents have proposed adding -O3, -march=native, -fomit-frame-pointer or -mmovbe; all four are already in effect, and -fomit-frame-pointer's only observable effect would be breaking perf's frame-pointer unwinding.

Check the actual compile line before adding a flag. Byte-swapping is the clearest case: -march=native already defines __MOVBE__, and the generated code for a big-endian load is a single movbel (%rdi), %eax with no bswap anywhere.

Supporting software

what each is for
perf
Cycle and instruction counts, PMU attribution. perf_event_paranoid is 2 on this host, so only :u (userspace) counters are permitted — every script uses cycles:u,instructions:u.
nvidia-smi
GPU utilization, VRAM, power draw, SM clock. No RADV equivalent — on the Deck use /sys/class/drm/card*/device/gpu_busy_percent and the amdgpu hwmon node instead.
xdotool
Reads the game's window geometry and title. Works because the game is an XWayland window; it cannot see native Wayland windows such as Konsole.
qdbus6
Drives KWin's scripting API over D-Bus — the only way to see and place every window regardless of Wayland or XWayland.
ssh / sshfs
ssh steamdeck (key auth, alias in ~/.ssh/config). The Deck's home is mounted at ~/steamdeck by the steamdeck-share systemd user unit.
coredumpctl
coredumpctl info on the Deck. Needs no reproduction and answers "is this my code?" in one screen.
WinBoat (Docker)
A Windows VM, 2 vCPUs and 4 GB, used for the Windows packaging path. Stop it before benchmarking — docker stop -t 120 WinBoat.

Repository layout

where things live
DolRecomp/src
The recompiler. app/ CLI and pipeline · backend/ the C emitter and dispatcher generator · backend/llvm/ the object backend · cpu/ the runtime header the generated code calls into · ir/, analysis/, frontend/
RecompCore
Module template and the chassis ABI glue — module_export.c is 44 lines and wraps dolrecomp_call.
ModernGekko
The vendored Dolphin fork that hosts the recompiled module
.github/scripts
Every benchmark, determinism and packaging script
dist/RingOut-1.0-dist
The desktop package — no module; the player builds one
dist/RingOut-1.0-deck
The Deck package — ships a prebuilt runtime
work/
Gitignored scratch that survives /tmp cleaning. Experiment artifacts belong here, not in a job scratchpad.

The desktop package has three artifacts that drift, and none updates itself

shipped broken twice

The desktop release ships no module — setup.sh extracts the player's own ISO and recompiles on their machine. So improvements reach desktop users only when all three of these are refreshed:

  • module-src/deps/dolrecomp-src/ — tracked in git, a copy of DolRecomp/src
  • tools/dolrecomp — the prebuilt recompiler, gitignored
  • bin/moderngekko-run — the prebuilt runtime, gitignored

A stale runtime fails loudly at dlopen. A stale recompiler ships old codegen in silence — setup runs, the module builds, the game plays, just slower. Both have happened. Freshness guards now exist for each, but check all three every release.

The general rule this taught: the module is built on the player's machine, so no packaging gate ever sees it. Any property of the player-built module is unguarded by construction — check it in setup.sh or nowhere.

Measuring instruments

which one answers which question

Picking the wrong instrument has cost this project more time than any bug. Each of these answers one question and is misleading outside it.

module-bench.sh — is this module faster?

.github/scripts/module-bench.sh <package-dir> <frames> <input-script> <reps> <tag>=<so> ...

Fixed-work A/B over real gameplay. Drives the determinism harness with .github/input-scripts/arcade-match.txt, a frame-keyed pad script: boot → title → Arcade → Talim → battle 1 on the bridge → stage 2, then a 240-frame attack loop that keeps the fight alive. At 24000 frames, gameplay is ~81% of the run.

Arms alternate and the order reverses on even reps, so a result tracking run order is visible rather than averaged away. Any run whose hash count ≠ frames is discarded — without that check, a module that crashes at frame 300 wins every comparison. Each run gets a fresh user directory seeded from the package.

The metric is cycles, not wall time. The same module over the same 24000 frames took 229 s, 298 s and 352 s in three runs — a 54% spread — because the machine was in use. instructions:u doubles as a checksum that both arms did identical work.

timeline.py — when and why does the frame rate drop?

timeline.py <seconds> <csv>    1 Hz: fps, GPU util, VRAM, power, per-thread CPU

Records continuously so a slowdown can be found after the fact. fps comes from the window title (show_fps_in_title=true in config.ini). Every fps reading carries the GPU and CPU numbers from the same second, so the cause travels with the symptom.

The two signatures are unambiguous, because the guest is a single PowerPC thread: GPU-bound is GPU near 100% with the guest thread below it; CPU-bound is the guest thread pinned at ~100% with the GPU well under.

determinism-check.sh — did this change guest behaviour?

Runs two instances with the same frame-keyed input and compares per-frame RAM hashes. This is the gate every optimization must pass: a codegen change may alter host instructions freely, but identical frame hashes mean a modified module and a stock one remain netplay peers.

Environment variables the runtime reads: RINGOUT_DETERMINISM_FRAMES, RINGOUT_DETERMINISM_INPUT, RINGOUT_DETERMINISM_LOG.

llvm-profdata — what does the PGO profile actually cover?

llvm-profdata show --all-functions --counts <profdata>

"Total functions" and "Total number of blocks" are static counts

one wrong conclusion, published

Every instrumented function has an entry whether or not it ever ran, so those totals are identical across every profile of the same binary and say nothing about coverage. The meaningful figure is the count of non-zero counters.

shipped profile     259,449 of 1,426,365 blocks executed   18.19%
+ full match        302,564                                21.21%
+ attract mode      346,983                                24.33%

Reading the static totals produced the confident and wrong claim that broadening the training set reached no new code. It reached 87,534 more blocks.

Others

Measurement discipline

every rule was paid for

The machine must be idle, and noise looks like data

two false results in one day

With a browser and a 4 GB Windows VM running, per-arm spread was 12–16% and clean builds varied by 25 seconds. That noise had structure: it produced confident, non-overlapping readings twice — "lld is 7% faster to build" and "ld.bfd is 8% cheaper in-game" — in opposite directions, from adjacent run pairs that looked properly controlled. Both evaporated on an idle machine, where the same instrument resolves 0.15%.

Before any timing run: no browser, no VM, nothing streaming, and do not play the game on the machine being measured. The other machine is fine to use.

Isolating one variable can hide the interaction that matters

a full day

Internal resolution was tested at 8×, 3× and 1× and they tied exactly — a correct result, and the card was only 32–36% utilized. MSAA was switched off in all three runs so resolution would be isolated, and its own cost was recorded as "not tested, plausibly also free".

It was not. MSAA multiplies per-sample work on whatever target resolution provides, so the two are not separable that way. With both enabled the final fight runs at 56.2 fps; removing MSAA alone restores a locked 59.9 with 8× resolution still on. When two settings compose multiplicatively, test the combination as well as the parts.

A single sample can invert the answer

one wrong diagnosis

An 8-second sample taken at a menu showed the video thread at 99% of a core and pointed squarely at a host-CPU bottleneck. The moment real geometry appeared, it flipped to GPU-bound at 100% utilization with the guest thread at 66–74%. Record a continuous timeline and locate the slow stretch afterwards.

Check which arm a number came from before building a mechanism on it

a published explanation, wrong

The MSAA saturation was first written up as a low-wattage memory-bandwidth stall, from reading 37 W off the 1× control arm and attributing it to the MSAA arms — which actually drew the most power of any configuration at 89–91 W. There was no subtlety in the mechanism: the card was simply full.

A staging directory is not evidence about what ships

two wrong conclusions in one day

Both packages have a dist/…/userdata/ tree in the working copy that looks exactly like what a player receives. Neither is. package-deck.sh lists userdata as forbidden and hard-fails if it reaches the stage, alongside the disc, the save card and the module — the shipped zip contains bin lib shaders tools RingOut README CREDITS and zero .ini files.

Reading those trees produced two confident and wrong claims on 13 August: that the Deck "ships 7× internal resolution", and that this was costing every Deck player 9.4%. In fact the Deck's live install had been at 1× the whole time and no player ever receives a config at all.

One command settles it either way — unzip -l the actual artifact, or read the file off the machine over ssh. Do that before describing anything as shipped.

Instantaneous clock readings lie

fooled twice

/proc/cpuinfo showed 3204 MHz on powersave against 3499.7 MHz on performance — apparently 8.5% of recovered headroom. Sustained throughput moved 1.4%. Cycles ÷ wall is the honest clock, and it is free when a benchmark already records both. A snapshot catches a boosting core, not what the run averaged.

The pattern behind all of it. Across six suggestion documents and 31 claims, not one headline figure written from reading configuration files survived contact with a counter. The optimizations that paid were the ones nobody could have reasoned their way to — PGO's benefit is spread thinly across the whole instruction stream, with no hot spot to find by reading code. And the two real bugs of the project were found by doing rather than reading: a package that built in four seconds, and a release script with no concept of a binary being older than its sources.

Optimizations that shipped

measured, merged
ChangeMeasuredMechanism
Profile-guided optimization −11.9% cycles
54.5 → 59.6 fps
−9.9% retired instructions plus 2.4% IPC. Needs -mllvm -runtime-counter-relocation, the flag for instrumented shared libraries. PGO was recorded as dead here; that was true of GCC only.
ThinLTO cache + probed lld edit loop 61.5s → 1.31s ThinLTO codegen runs inside the linker, so editing one generated chunk re-optimized all 132 modules. The cache reuses the 131 unchanged. Cache at ~/.cache/ringout/thinlto, 2 GB cap, 7-day prune.
Lazy FPRF −2.45% cycles FPRF measured 100% dead — 3.073 G writes against 15,885 reads. Every FP op sets it unconditionally by architecture. Hash-identical.
Dispatcher single lookup −1.23% instructions FastDispatchableAt called GetAddressLookupIndex twice per dispatch and discarded one result. Four FMV env flags were also declared inside the loop, each paying a static-init guard per dispatch.
Dual-core netplay 41 → 46 fps on the Deck Netplay had forced single-core for determinism. Dolphin's actual answer is a deterministic GPU thread — which requires dual-core, so forcing single-core disabled the mechanism built for the problem.
fmod symbol version pin desktop modules now load on a Deck See the glibc floor trap below.
Stale-artifact guards silent staleness now caught Both packagers refuse to ship a binary older than its sources.

Optimizations rejected

do not revisit without new information

Each of these was built or measured, not reasoned about. The numbers are why they are closed.

IdeaResultWhy it fails here
BOLT post-link layout−8.1%A flat profile is BOLT's worst case, not its best. It had more information about the binary than the compiler did and still lost.
Leaders-only case labels
--leader-cases
82.4M interpreter steps
vs 0.48M
Module 19.5% smaller, and 81% of execution leaves the recompiled code — block leaders do not cover indirect-branch targets. Flag exists, off by default.
Broadened PGO training set+2.18% cyclesAdding attract mode pulls weights toward the intro FMV — the game's software MPEG decoder, which the project deliberately bypasses.
XER[CA] elimination~1% ceiling98.4% of carry writes are dead, but RECOMP_NO_CA hangs the game outright: the 20.2 M reads are load-bearing. Needs a backward liveness pass for ~1%.
Fastmem / mmap + SIGSEGVbounded at 8.54%That is the entire memory and paired-single budget, and fastmem does not empty it. It also silences the write journal that the determinism tooling and rollback run on.
Guest CPU underclockrejected on riskChanges emulated timing, so frame hashes change and two peers desync immediately.
Governor and TDP on the Deck1.4% / nothingPackage power is 8 W against a 15 W cap. The workload never approaches the limit.
Context-sensitive PGOno change, twiceProduced an identical binary.
Hand-inlined memory fast paths+6.1% CPUThinLTO already inlines them.
Hot/cold block splitting
-fsplit-machine-functions
+0.07%
t = 0.31
The cleanest test of layout yet — it had the exact instrumented profile, so it avoided BOLT's misclassification, and still did nothing. IPC did not move (2.551 → 2.549) despite 141 cold parts extracted.
PGO retrained on the final fight−0.10%
(noise)
Coverage did rise, 18.19% → 22.29% of blocks, and it bought nothing: the full route moved −0.10% while the early stages got 1.26% worse. The Deck's missing 18% is not a profile-coverage problem, and cold layout of boss-fight code was the most plausible remaining mechanism.
LLVM object backend
--backend llvm
+77.2%
cycles
Emits 75% more host instructions for the same work, at the same IPC as the shipped module (2.47 vs 2.51) and with its 43% dispatch advantage already counted in. PGO cannot apply to it at all, and it is 724 MB against 38.8 MB.

Layout is closed. Three interventions have now tested instruction locality from different angles — BOLT −8.1%, -O2 −9.1% with 12.5% less code, and machine-function splitting +0.07%. The reason they all fail is one counter: ic_stall_dq_empty is 2.4% of cycles, so that is the entire budget any of them could win, and each traded back-end efficiency to chase it.

This is worth knowing because the profile looks perfect for the technique: 99.4% of execution comes from 3.5% of the blocks, scattered through 37.9 MB of .text. A peaked profile is a necessary condition for layout work, not a sufficient one — the front end also has to be the limiter, and here the back end is saturated.

The LLVM object backend is closed. It was the last structural item open, on the thesis that its 43% fewer dispatches (13.7 M vs 23.9 M) would convert into the ~15% the dispatcher was thought to be worth. Measured over 2900 frames of fixed work, 3 reps, order reversed:

armmean Gcycmean GinsnIPCvs shipped C
C backend, shipped (PGO)61.53154.482.51—
C backend, pre-PGO70.37157.362.24+14.4%
LLVM backend109.04269.822.47+77.2%

Its IPC matches the shipped module's and it still loses by 77%. That rules out stalls, layout and the dispatcher as explanations: the backend emits 75% more host instructions for the same emulated work. The dispatch advantage is already counted inside that number, so the thesis is tested and refuted rather than untried.

Check what the A/B partner actually is before quoting a margin

a 55% gap that was really 77%

The first run of this comparison used dist/RingOut-1.0-deck/bin/gGRSEAF_recomp.c.so as the C arm because it sits next to the LLVM module and is obviously the A/B partner. It is dated 9 August; PGO landed on the 12th. So the margin was quoted against a module 12.6% slower than the one that ships, and the third row above is the number that matters.

The tell was available without re-running anything: the arm's IPC was 2.24 where the shipped module's is 2.51. Date the artifact against the commit that changed it — the same discipline as reading the zip rather than the staging tree.

The deficit is also larger than it looks. PGO is structurally unavailable to this path — it emits 526 .o objects and one .c, so -fprofile-use has nothing to act on — and PGO is worth −11.9% on the C side, putting the real gap near 67%. Measurement was on boot and menus, which carry ~0.1% of a session's paired-single traffic; since the LLVM path calls out to cpu_llvm_abi.c for every float and paired op where the C emitter inlines them, gameplay would widen the gap, not close it. And at 724 MB against 38.8 MB, with 91 minutes to generate on 12 desktop cores while setup.sh recompiles on the player's machine, it was never shippable in this form.

One thing worth keeping came out of it. Getting far enough to measure meant fixing a real miscompile in the shared IR: it wrote paired-single lane 1 on every FP load and on the ps0-only moves, where emitter.c writes it only for lfs. Games use lfd as a fast 8-byte move, so lane 1 ended up holding two packed f32s. Dolphin's lockstep verifier put it beyond argument — 585 ps1 divergences before the fix, 3 after, against the C module's 0.

Graphics settings

measured on the Arcade final fight

Reported from play: the final fight slowed down. Five configurations of the same fight, sampled once a second. The guest CPU thread sat between 66% and 80% of a core in every arm, so no codegen change could have moved this.

Configurationnfpsmin<58 fpsGPUPower
everything off — 1× res, no CRT52359.9058.00%41%37 W
8× res + 8× MSAA + CRT29256.2345.360%95%89 W
8× res + 8× MSAA, no CRT44257.2850.156%96%91 W
8× res, no MSAA, no CRT18659.9059.90%62%65 W
8× res, no MSAA, CRT on53459.9059.90%63%65 W

8× MSAA is the entire cost. The CRT post-processing shader costs about 1 fps when the card is already saturated and is free once MSAA is gone — 59.90 either way.

Recommended configuration

userdata/Config/GFX.ini
  InternalResolution   = 8         MSAA = 0x00000001   (1 sample = off)
  PostProcessingShader = crt        SSAA = False
  wideScreenHack       = True       AspectRatio = 1

userdata/config.ini
  resolution = 5120x4224            # must agree with InternalResolution

The two files feed the same setting and must agree — config.ini's resolution maps to a Dolphin EFB scale, where any exact 640·N × 528·N string resolves to scale N.

The Deck wants different settings, and the desktop result does not transfer

Internal resolution is free on the RTX 3050 — 8×, 3× and 1× tied exactly. That held only because the card was never the constraint. On the Deck it plainly is. Fixed 12000 frames of the input script, windowed so the GPU is in the loop, three reps with the order reversed, identical frame hashes throughout:

ScalePixelsMean wallSpreadEmulated fpsvs 1×
1×0.3 M150.3 s0.53%79.86—
4×5.4 M152.0 s0.46%78.93+1.18%
7×16.6 M164.4 s2.13%72.98+9.43%

7× costs the Deck 9.4%, far outside the spreads. 4× costs 1.18% for eighteen times the pixels of native — and the Deck's panel is 1280×800, so even 2× already supersamples it. 4× is the sensible setting there; 7× is not. The Deck has no headroom to give, running 56.9 fps in real play.

Note the metric changes with the question. This used wall time over a fixed frame count, not cycles: the run is unthrottled at ~80 emulated fps, so wall time measures throughput directly, and CPU work does not vary with resolution. It must also be windowed — a headless run creates no pipelines and draws nothing, so it cannot measure a GPU change at all.

Dolphin rewrites GFX.ini on exit

one clobbered experiment

Edit graphics settings only while the game is closed. Editing them during a run works until the process exits and overwrites the file with its in-memory copy.

The Steam Deck

every issue, and the fix

The port took four hardware iterations to boot, and every blocker was environment rather than a defect in the port — the recompiled module loaded correctly on every failed run. When a Deck symptom appears, suspect the environment first.

LD_LIBRARY_PATH shadowing broke Vulkan for the whole process

four hardware iterations

The launcher put its 66 bundled Debian 12 libraries on LD_LIBRARY_PATH, which outranks the system search path as a whole. Ten of those libraries are ones Mesa itself needs — and the Vulkan loader dlopens Mesa into the process — so no ICD loaded and vkCreateInstance failed.

Ordering within the variable is not a fix; a bundled library shadows the host's copy wherever it sits. Both launchers now ask ldconfig what the host has and bundle only the remainder — 58 of 66 were already present on an Arch-family host. Any "ship our own libs" scheme has this failure mode the moment the host dlopens something into the process.

The glibc floor: one fmod call broke every desktop-built module

a silent, complete failure

A binary's glibc floor is the highest versioned symbol it demands. Binaries run forward across glibc versions, never backward. cpu.c calls fmod exactly once — the round-half-to-even tiebreak — and glibc 2.38 added a new symbol version for it:

built on Arch / Fedora 39+ / Ubuntu 24.04   floor 2.38   FAILS on a Deck
built on Debian 12 / Ubuntu 22.04           floor 2.36   works

SteamOS is ~2.37, so it died at dlopen — after the player had extracted the disc and waited out a full recompile. Fixed with __asm__(".symver fmod,fmod@GLIBC_2.2.5");, safe because fmod is exact: verified .text byte-identical and frame hashes identical over 6000 frames.

A poisoned Vulkan pipeline cache, and it is self-perpetuating

looked exactly like a code regression

Worked in Desktop Mode, launched once in Game Mode, then Desktop Mode segfaulted too. The backtrace names it in one screen:

#0  libvulkan_radeon.so                          <- Mesa RADV
#5  Vulkan::VKPipeline::Create
#6  VKGfx::CreatePipeline(config, const void*, size_t)   <- cache blob
#7  ShaderCache::QueueUberPipelineCompile

A crash leaves the blob truncated, so every subsequent launch crashes replaying it and re-corrupts it — which is why it never wears off. The two modes have different cache files (the name carries a config/driver hash), so this is not cross-mode contamination.

mv ~/Desktop/steamdeck/userdata/Cache/Shaders/Vulkan-*.cache /tmp/

Nothing in that stack touches recompiled guest code, and a headless run — which never creates pipelines — passes on the same binaries.

The pad's SDL name depends on how the game was launched

an unfalsifiable netplay bug
over ssh, no Steam:   SDL/0/Steam Deck Controller
Steam Game Mode:      SDL/0/Steam Virtual Gamepad

Same physical pad, different name. A profile written in one context resolves to nothing in the other, and Dolphin reports no error — every binding evaluates empty, so the game reads a centred, unpressed controller. That presents as "the pad works in single player and does nothing in netplay", and it is unfalsifiable from the netplay layer, because the pad map and routing genuinely are clean. Delete the profile and let it be regenerated in the context you will play in.

Never hardcode the device name. Vertical axes read Left Y+ for up because that backend already inverts them to match XInput — do not "fix" the sign.

Building on the Deck: pacman's --needed silently no-ops

an hour

The Deck starts with no gcc, clang, cmake, ninja or pkg-config, /usr read-only, and /usr/include stripped to 14 entries — while pacman's database still claims glibc owns 504 files there. So pacman -S --needed skips exactly the packages you need.

The native build is worth it: 1154/1154 targets, all 47 dependencies resolving to /usr/lib, zero bundled libraries — which deletes the 66-library bundle and the LD_LIBRARY_PATH allowlist together.

Stale installs, and which one Steam actually launches

several failed netplay tests

~/Desktop/steamdeck/ is the only install and the Steam shortcut target. Two stale copies once existed and one silently became the thing Steam launched. Both machines must run the same runtime and the same module — mismatched modules are a desync waiting to happen.

mv over a running binary is safe: rename swaps the directory entry and the running process keeps its inode. That is how updates land without closing the game.

Desktop environment traps

KDE / Wayland / shell

The game opens on the wrong monitor, and xdotool cannot fix it

standing instruction

The game lands on the portrait panel DP-3 and sizes itself to fill it. Two separate problems block the obvious fix: the game is an XWayland window, so xdotool can read its geometry but KWin ignores its move requests — one attempt got the window snapped to a half-tile instead of moved. And Konsole is a native Wayland window, so xdotool cannot see it at all, meaning the terminal's monitor is only knowable by asking the compositor.

Both vanish inside KWin's scripting API, which sees every window and can set frameGeometry directly. work/tools/place-game-window.sh does this after every launch. Use print() in the script and read it back from journalctl --user -f — that is the only way to get output out of a KWin script.

pkill -f matches the shell running it

killed my own session twice

A pattern like pkill -f timeline.py matches the wrapper shell whose command line contains that string, so the command kills itself mid-script and the rest of the compound command never runs. pgrep -f has the same flaw in reverse: it reports the game as running when it is not, because the terminal's own command line mentions the path.

Use pgrep -x against the exact process name, or resolve a PID first and signal that.

Several threads share a name — keying by it returns an idle duplicate

a table of zeroes

The runtime has two threads named CPU thread and three named Video thread. A per-thread CPU sampler that keys a dictionary by name keeps whichever readdir returned last — usually one reading 0%. Sum by name, or key by tid.

Related, and more useful: read the thread name to tell which core mode is live, rather than trusting the config. Dolphin names them CPU thread + Video thread in dual-core, and a single CPU-GPU thread otherwise.

Action Replay codes need EnableCheats, which is not in the config

one silent no-op launch

userdata/GameSettings/GRSEAF.ini carries the USA codes — Dolphin ships only the PAL GRSPAF.ini, so the USA disc matched no game ini and the CHEATS tab came up empty. The codes are listed but not enabled, and EnableCheats = True must be set under [Core] in Dolphin.ini or the whole list loads and does nothing.

Useful codes: Absolutely Everything Unlocked, Infinite Time, P1/P2 Infinite Health, P1/P2 Play As Inferno. There is no CPU-vs-CPU code in the file.

Escape pauses the core, and looks exactly like a freeze

one false alarm, still cited

Escape opens the in-game overlay and pauses emulation — audio keeps playing and the game stops responding, which reads as a hang. Check the log for [menu] toggle open=1 (core pausing). Shift+Escape is the immediate quit.

Driving the game without hands

Dolphin's Pipe input backend is compiled in, so scripted input needs no code changes — but three things must all be true or every press is silently dropped:

Profiling needs none of this. Determinism is irrelevant to performance counters, so launch with RINGOUT_DETERMINISM_FRAMES=N so the process exits cleanly, play by hand, and the .profraw lands. A hard kill loses it.

Open questions

in order of value

Where the Deck's missing 3 fps actually goes

Answered in part, 13 August. The Deck runs 56.9 fps in real play, and it is CPU-bound — per-core load during a match is one saturated guest thread and seven near-idle cores:

cpu0 12%   cpu1  8%   cpu2 100%   cpu3 4%
cpu4  6%   cpu5 10%   cpu6  22%   cpu7 4%

It was also running at 1× internal resolution the whole time, so the graphics settings were never the cause. Two power explanations are already closed: package draw is 8 W against a 15 W cap, and raising the cap to 29 W did nothing; governor and EPP moved throughput 1.4%, inside noise.

What remains open is the guest thread itself. The recompiled module has no known headroom left — PGO, lazy FPRF and the dispatcher have all shipped, and layout is closed — so the next honest answer is probably that a single emulated PowerPC on a Zen 2 core at ~3.3 GHz effective is simply what it is. Do not reopen this without a new mechanism; the measured avenues are exhausted.

Confirmed and sharpened on 14 August. The 56.9 fps reading was briefly written off as stale and is not: measured on the actual final fight the Deck runs 50.5 fps with the CPU thread at 97% and the GPU idling at 9.5 W. That also turns this open question into a number — +18% — see the headroom section below.

How much headroom is there above 60 fps? answered 14 August

EmulationSpeed = 0. under [Core] lifts the limiter. Windowed, 12000 frames of arcade-match.txt, sampled once a second:

targetboot / menuschar selectgameplayvs 60
Desktop2011391101.83×
Steam Deck (3×, MSAA off)13292731.21×

Both are floors: input scripting is coupled to hash logging — GetConfig() returns early when RINGOUT_DETERMINISM_LOG is unset — so every run pays the per-frame whole-RAM CRC32, which is ~18% of the CPU thread.

Headroom is a property of the content you measured, not of the game

a 1.21× margin that was really 0.85×

The Deck's 73 fps above is the stage 1–2 fight, because that is as far as arcade-match.txt goes — the same limitation that keeps PGO coverage at 18% of blocks. On that basis the Deck looked comfortable and the older "56.9 fps, CPU-bound" reading looked stale. It was not. The actual final fight (stage 8 vs Inferno, played by hand, 423 samples over ~7 minutes, identical settings):

fps mean 50.5   min 48.1   max 55.3   under 60: 423 of 423 seconds (100%)
CPU thread 97.0%       GPU 46%, 9.5 W

The boss fight is ~30% more expensive than the early stages, and the margin does not survive it. The emulation thread saturates while the GPU idles — so unlike the desktop's MSAA problem, this is entirely the recompiled code. Never generalise a headroom figure past the content it was taken on.

This is the first concrete performance target the project has had: +18%. 60 / 50.5 = 1.19×, so roughly a fifth more CPU throughput would hold 60 in the final fight. Worth stating plainly against the remaining ledger: fastmem's entire bounded budget is ~8%, PGO (−11.9%) and lazy FPRF (−2.45%) are already spent, layout is closed three ways, and the LLVM backend lost by 77%. No single remaining lever reaches 18%.

Reaching the boss without playing the whole game: the Action Replay codes in GRSEAF.ini — P1 Infinite Health and P1 Win 1 Round To Win to get there, Infinite Time to hold the fight open. They produced zero invalid-read alerts, so they do not distort the measurement. Deck telemetry needs its own recorder (work/deck-finalfight/deck-timeline.py): the APU reports through amdgpu sysfs rather than NVIDIA counters, gpu_busy_percent is instantaneous and must be averaged, and xdotool silently finds no windows at all without XAUTHORITY — which looks exactly like the game not being up yet.

The benchmark harness is already throttled

read before testing

Across five arms of the PGO benchmark, every run took 201.5 s wall for 24000 frames (~119 emulated fps) while cycle counts differed by 2.2% between arms. Wall time pinned that hard against varying work is a speed limit, not a coincidence — and it is the other reason module-bench.sh insists on cycles.

So an unthrottled measurement needs the limiter lifted in the harness run, not only in a GUI session. Record the fps distribution rather than a peak: a single peak over a run containing boot and menus says almost nothing.

Two guest faults from the Action Replay codes

[alert] Invalid read from 0x0000005a, PC = 0x80009dc0
[alert] Invalid read from 0x0000005a, PC = 0x80032ca4

Seen once during boot with the unlock codes enabled, right after the intro FMV starts. The game played normally and no measurement was affected.

The obvious test cannot answer this — the fault is intermittent

saves a false all-clear

The natural experiment is one launch with EnableCheats = False to see whether the warning disappears. That assumes it fires reliably when codes are on. It does not: two later launches with EnableCheats = True and the same boot path — both reaching the FMV — produced zero alerts.

Absence is the normal case, so a clean codes-off run proves nothing. This needs several launches per arm, or a reproduction trigger better than "boot the game". Worth noting that a null-ish read at 0x0000005a looks more like a guest pointer used before initialization than a cheat write.

What Exhibition mode actually offers

If it runs CPU-vs-CPU fights it is the only known route to an unattended profile-training session — real gameplay, no intro FMV, no controller. Nobody has looked. Weigh it against the finding that broadening the training set was measured and lost.

Smaller items