Skip to content

nvn: Mario Kart World frame time and CPU at the 60 fps cap on the Mac - #2912

Open
atinseau wants to merge 47 commits into
seedds:mainfrom
atinseau:codex/pr-mkw-60fps
Open

atinseau wants to merge 47 commits into
seedds:mainfrom
atinseau:codex/pr-mkw-60fps

Conversation

@atinseau

@atinseau atinseau commented Nov 17, 2026 •

Copy link
Copy Markdown

What and why

Mario Kart World on the Mac (M3 Max) races at 77-96 fps uncapped on main, and at its 60 fps cap it misses frames (one run in two falls to 38-40 fps, up to 2,180 frames over 20 ms in a race) while spending about 30 ms of CPU a frame. This series makes the host submit, translate and encode a frame with less waiting and less CPU, and the GPU do less redundant work. Most commits are general fixes found on this game; three only touch its profile or note. Each commit is one change and builds on its own; its message gives the symptom, the cause, the fix, its switch (most new behaviour has one, =0 restores the old path) and its measurement, mostly in-run A/B (DM_AB=300, both phase orders).

The commits can also be taken one by one or as separate pull requests, if that suits review better.

Submission and segments:

  • nvn/rec: held submissions off by default on the Mac (DM_NVN_SUB_MERGE), frame p50 -0.6 ms.
  • nvn/queue: a submission goes to the replay node by node while it is copied (DM_NVN_SUB_STREAM, with the DM_NVN_SUBTL timeline that found it), frame p50 -0.5 to -1.4 ms.
  • nvn/mtl: the first segment is cut after 8 draws while the GPU is idle (DM_NVN_CUT_IDLE).
  • nvn/queue: plain records copied in runs, compact ones expanded in place (DM_NVN_Q_EXPAND); only records naming a texture or program are walked; a node's buffer is kept for the next; a node of pool settings only is applied without a Metal submission (DM_NVN_EMPTY_SUB).

Replay CPU (each a few % of the replay thread): per-block write generations in nvn_dirty, the address to pool index kept sorted in place, bindings resolved outside the registration lock, a per-class Metal texture check, fb_any_att, 32 cached views per texture, tu_pass over the IDs used since its last pass (a 2 ms stall once a second), per-pool texture lists for Finalize, an nvn_hmap for each pool's live textures, ARC borrows on the replay, sparse pool ranges without the mapping lock, leaf NVN getters on the caller's stack, the thread's kernel time through its pthread port.

GPU work:

  • nvn/mtl: a cube level's six faces drawn as six draws (DM_NVN_FACE_SPLIT), handheld GPU p50 -0.56 ms.
  • nvn/mtl: face-split passes of one level size merged across textures (DM_NVN_FACE_MERGE): the cube filter's three chains share one pass per level, 21 passes a frame become 7; uncapped GPU p50 -0.52 ms handheld and docked, the small passes' GPU time -0.7 ms a frame at the 60 fps cap (measured after the benchmark below, in-run A/B).
  • nvn/mtl: rangeless dispatches ordered by the game's barriers (profile key dispatch_rangeless game, Mario Kart World only), compute -0.5 ms a frame.
  • nvn/attachments: depth and stencil planes no draw uses go in DontCare (DM_NVN_DS_IDLE).
  • nvn/mtl: clears of consecutive array layers in one layered pass (DM_NVN_LC_LAYERS); compact binds no longer end a slice-merge look-ahead (9 fewer passes a frame).
  • chain: bounded uniform reads compared by 16-byte rows (profile key shader_row_bounds, Mario Kart World only).
  • nvn/mtl: recycled render-target heaps sized for dynamic resolution steps (fewer frames of 60-148 ms spent in residency commits).

Host threads (CPU at the cap):

  • host/thread: a 20 µs guest sleep sleeps (DM_SHORT_SLEEP), -0.25 to -0.41 W; guest waits sleep on a word of the thread without the thread lock (DM_WAIT_ON_ADDRESS, DM_G_SPIN), -1.7 ms of process CPU a frame; waiters kept in buckets by what they wait for (DM_WAIT_INDEX), -1.2 to -2.1 ms.
  • nvn/rt: a thread taken off its time-constraint policy gets its priority back.

Tools and diagnostics: DM_NVN_GPU_TS_SCALE (the game's dynamic resolution aims at a shorter frame: the player's choice, off by default), the Mac GPU power line (host/power), DM_NVN_SUBTL.

Mario Kart World: enc_thread on in its profile, dispatch_rangeless game, shader_row_bounds 1, and its note (where a frame's time goes, what was tried and not kept).

The original series fixed a build error in t_feedback on d6585a2; main has since fixed the same caller. Three changes of the measured series are left out because main has them since: the DM_GL_RENDERPROGS / DM_NVN_UNBIND_DEFER table rows (b7e4b98), a storage takeover looking at each shared entry once (d664d31, the same fix found on Ocarina of Time) and typed counts of t_feedback / t_pso_prewarm's JSON arrays (854a596 made the same fix).

Checked

  • Rebased on upstream 0bd40f9f (PR head 54d4c27f): the shader chain is 391a0e7dce4b, including the upstream SHFL, ordered-not-equal and half-precision FTZ changes as well as the profile row-bounds optimization. The rebased tree was checked against an independent three-way merge. All 37 selected qtest targets and all 89 shader/tool tests passed; the latter included Metal GPU readback and iOS shader compilation. Both full Mario Kart World libraries were rebuilt (11,560/11,560 shaders, Mac and iOS; inputs 49790ad645dd). A Mac handheld smoke run loaded the new image and completed the 1,200-frame race window at 59.17 fps (14 frames over 20 ms, four over 50 ms). No iPhone gameplay run. GitHub Actions for this head.
  • Previous validation (upstream parent a2c731e3; merge d928271e, test fixture fix d0a00de1):
    • git nx qtest --base origin/main: 36/36 selected tests passed. Targeted checks also covered overlapping dirty ranges, retirement/reuse (20,000 rounds; 2,000 under ThreadSanitizer), shader row bounds, and the upstream mesh-stage inlining change.
    • Rebuilt all 11,560 Mario Kart World Mac shaders on the merged chain 8c770a0f0fea. The Mac host loaded that image in a handheld Mario Bros. Circuit smoke run: 59.95 fps over frames 1800–2999, eight frames over 20 ms and none over 50 ms. This is a smoke run; the comparative measurements below were made on the earlier revisions they name.
    • The full local graphics run with make -k had one failure: the OpenGL LOD-bias pixel assertion in t_gl_imports, reproduced on unmodified a2c731e3. Both CI CPU variants passed. In separate repeated runs, t_nvn also intermittently faulted in nvn_sparse_protect during present; reproduced with the same stack on upstream.
    • LLVM 23.1.4 clang-tidy on all 354 sources: 187 findings, matching the baseline. GitHub Actions for the previous revision.
    • The mesh-target test now supplies the shader rewriter used by the merged upstream builder. All 29 tests in dm.tools.tests.test_shader_toolchain_cache pass under Python 3.14 (Mac-only, iOS-only and combined mesh selection included).
    • Earlier validation: each original series commit built the Mac host on d6585a2; the previous published head passed all nine GitHub checks. The Metal logic fixture ran all 949 replay checks and the geometry shader test covered 40 GPU primitive-ID cases.
  • Games run, with title ID and version: Mario Kart World (0400C3F00006E000), base version v0 (main build 9e244438c3d8ef1c), a Mario Bros. Circuit race from the boot-to-race save, frames 1800-5400, handheld and docked, uncapped and at the 60 fps cap; compared by the race tool's frame times, GPU times, process CPU, CPU energy and wakeups, and the race pictures (below). In-run A/B (DM_AB=300, both phase orders) for each change, in its commit message.
  • Devices and OS: Apple M3 Max on AC, macOS 27.0.1 (26A434), a Mac shared with other work. No iPhone run.
  • For a change every game uses: regress.py check was not run: Mario Kart World is the only game on this Mac, and its build comes from a disc image, not the NSP layout the harness reads. regress.py impact 8d62601f..HEAD names Breath of the Wild, Tears of the Kingdom, Pokémon Scarlet and Hades; they, and the iPhone, have not run this series. The changes most worth a check elsewhere, each with a switch that brings the old path back:
    • DM_SHORT_SLEEP, DM_WAIT_ON_ADDRESS / DM_G_SPIN and DM_WAIT_INDEX change every game's thread SVCs: a thread-heavy game (Tears of the Kingdom, Breath of the Wild, Silksong, Octopath Traveler II).
    • DM_NVN_DS_IDLE: a game that uses stencil.
    • DM_NVN_FACE_SPLIT and the slice-merge binds: Breath of the Wild's cube filters (DM_NVN_PASSDUMP).
    • The time-constraint priority fix and held submissions (still on by default there): the iPhone.
  • Measurements before and after: below.

Measurements

Mario Kart World, Mario Bros. Circuit race, M3 Max on AC (2026-11-17): main 8d62601 against this series on it (before its rebases onto 422ec24 and d6585a2, which drop three commits main now has, and before its last commit, the face-split pass merge), each with its own shader library, two runs of each build per configuration in ABBA order (git nx's race tool, frames 1800-5400), on a calm Mac (other processes kept the GPU 10-13 % busy before each run). Uncapped is DM_FPS_TARGET=0 DM_PRESENT_HZ=0 DM_PRESENT_LINK=0 DM_PRESENT_SCREEN=0 DM_VSYNC_HZ=240.

Uncapped, handheld / docked main this branch change
fps 95.8 / 77.0 120.0 / 113.5 +25 % / +48 %
frame p50 10.30 / 12.83 ms 8.26 / 8.78 ms -20 % / -32 %
GPU p50 7.79 / 10.31 ms 6.12 / 7.72 ms -21 % / -25 %
translation CPU p50 7.27 / 7.56 ms 4.67 / 5.06 ms -36 % / -33 %
process CPU a frame 26.7 / 27.4 ms 22.3 / 23.2 ms -17 % / -16 %
CPU energy a frame 62.0 / 64.5 mJ 50.3 / 52.5 mJ -19 % / -19 %
instructions a frame 141 M / 146 M 116 M / 121 M -18 % / -17 %

Handheld, both runs of this branch held exactly 120.0 fps, which looks like a 120 Hz limit (this Mac's display): that gain is a floor.

At the 60 fps cap, handheld main this branch change
fps 49.9 (39.9 and 59.9) 60.0 (both runs)
frames over 20 ms 1,005 (129 and 1,880) 76 (66 and 85) -92 %
frame p95 27.2 ms 19.4 ms -29 %
process CPU a frame 30.2 ms 25.4 ms -16 %
CPU energy a frame 59.7 mJ 43.7 mJ -27 %
instructions a frame 144 M 119 M -17 %
wakeups a second 2,220 3,940 +77 %

Docked at the cap, main held 60 fps in one run and fell to 38.3 fps in the other (2,180 frames over 20 ms), as on the day before (39.0 and 59.8 fps). This branch held 60.0 and 59.8 fps (4 and 25 frames over 20 ms, process CPU 24.4 and 24.9 ms a frame against main's 27.8 at 60 fps, CPU energy 41.8 and 48.0 mJ a frame against 64.1). One more run of this branch dropped to 49.9 fps with one 2.5 s burst of slow frames while the Mac's load average climbed past 90, and later runs of both builds ran under a load average of 900 (iOS simulators starting); they are left out.

The wakeups rise because a guest sleep of 20 µs now sleeps (DM_SHORT_SLEEP): the game's job dispatcher spun through it before. System GPU energy is not in the tables: it is the whole Mac's, and at the cap it follows the frame rate each build reached. A first benchmark of the same work on main edc7eff (before the last five commits and the rebase) gave the same picture: uncapped +26 % / +33 % fps, at the cap 52.3 / 49.4 -> 59.9 / 59.5 fps, process CPU -17 % / -18 % a frame.

Docs

  • The finding is in its game note or its docs/reference/<subsystem>.md entry, and python3 dm/tools/docs_symptoms.py was run (the symptom index)
  • A chain tool changed: dmsh_chain.py --header was run and dm/gfx/nvn/dmsh_chain.h is part of the change (chain: compare bounded uniform reads by 16-byte rows)
  • No game files, keys or data extracted from a game in the change or the attachments

@github-actions github-actions Bot added host The Horizon host: SVCs, services, threads, memory (dm/host) nvn NVN on Metal and its tests (dm/gfx/nvn, dm/gfx/tests) tools Tools and scripts (dm/tools, scripts) docs Documentation shader chain The shader translation chain (DMSH_CHAIN): a change rebuilds every game's shaders game: 0400C3F00006E000 A game profile labels Nov 17, 2026
@atinseau

Copy link
Copy Markdown
Author

Hi @seedds, could you take a first look at the NVN queue changes for Mario Kart World on Mac? The submission-streaming commit can be reviewed on its own; its message has the A/B measurements on M3 Max. Given the size of the series, would a standalone PR for that change on current main be easier to review? Thanks!

On the encode thread (DM_NVN_ENC_THREAD, the default on iOS and for
profiles with enc_thread on), a submission that ends while the GPU still
runs an earlier command buffer is held and committed later with the next
ones (rx_commit). That was made for the iPhone, whose GPU lowers its clock
when it idles. On the Mac a held submission waits until the GPU has run out
of work, so each batch of the frame started behind an idle GPU.

DM_NVN_SUB_MERGE now defaults to holding only on iOS (TARGET_OS_IPHONE). On
the Mac every submission is committed on its own; DM_NVN_SUB_MERGE=1 holds
them as before and ab alternates it with the DM_AB phases. check_t_feedback
runs its held-submission cases with DM_NVN_SUB_MERGE=1, and t_feedback's
merge case skips itself when holding is off.

Measured on Mario Kart World (M3 Max, uncapped race, DM_NVN_SUB_MERGE=ab in
phases of 300 frames): frame p50 0.65 ms shorter docked and 0.60 ms shorter
handheld with holding off (handheld 8.1-8.35 ms against 8.8-9.6 ms), the GPU
busier, and no frame over 20 ms either way. At the 60 fps cap holding saved
no CPU energy (+0.04 W with it).
The game's main thread waits on the fence of the frame before, so the host's
translation of each frame sits between two of its GPU runs. The profile's
enc_thread on moves Metal encoding to a thread of its own, as on iOS for
every game, so translation and encoding overlap.

Measured on an M3 Max at the time (uncapped race, two alternated runs each):
docked 77.4-77.7 -> 80.0-80.7 fps (frame p50 12.5 -> 12.1 ms), handheld
104.3 -> 106.6 fps.
nvnQueueSubmitCommands copies the submission on the game's thread (its
records, a few hundred KB a frame, and the programs and textures they name,
as they are at submit). The job reached the replay only once all of it was
copied, under the submission lock the replay translates under. Mario Kart
World starts each frame with one submission of six command nodes between
event waits, copied in 0.85-1.1 ms while the GPU, done with the previous
frame, had nothing to run.

nvn_queue_submit now queues the job before the copy, and each command node
goes to the replay as soon as an event wait, a sync wait or a fence closes
it (nq_take_staged), so the replay translates and commits the first
commands while the game's thread copies the rest. The copy holds no
submission lock: programs are pinned by serial (mtl_prog_snapshot_pin, the
pins with a lock of their own in nvn_owner.m) and resolved by the replay;
texture pins take the owner's lock. A job still being copied holds its
queue (open), so later submissions keep their order. Command node buffers
grow geometrically instead of 4 KB at a time. DM_NVN_SUB_STREAM=0 copies
the whole submission first as before (ab alternates it); a frame capture
(DM_NVN_CAPTURE) keeps that order.

DM_NVN_SUBTL=<f>[-<f2>] is the diagnostic that found it: a timeline of those
frames on the guest clock (game submits, copy done, replay begins, segments
committed and run on the GPU, sync waits, presents).

Measured on Mario Kart World (M3 Max, uncapped, DM_AB=300
DM_NVN_SUB_STREAM=ab, race phases only): docked frame p50 11.9-13.2 ->
11.2-12.3 ms (0.7-1.4 ms lower in five of six phase pairs, one even), p90
12.6-14.7 -> 11.9-13.5 ms; handheld 9.7-11.0 -> 8.9-9.9 ms (lower in seven
of seven pairs). GPU time unchanged. At the 60 fps cap the race held
59.8 fps with every frame on screen for one vsync, as before.

Checked: t_wait_event, t_queue_lifetime, t_render_enable_queue,
t_queue_origin, t_sub_overlap and t_serial_owner pass with
DM_NVN_SUB_STREAM on (the default) and off.
A segment is committed every DM_NVN_CUT (64) draws between passes. A frame
often starts with many small passes (Mario Kart World: cube map filters and
small targets, 36 draws in its first command node), so the whole node was
translated, about 0.5 ms of encoder creation, before the GPU got any of it.

While nothing the replay committed is on the GPU (g_seg_inflight 0),
sub_cut_ready now ends a segment at the first pass boundary after
DM_NVN_CUT_IDLE draws (default 8, 0 off, ab alternates it). With work on the
GPU nothing changes, since sub_cut commits only then (DM_NVN_CUT_BUSY), so
no more command buffers queue behind running work. DM_NVN_CUT_BUSY takes ab
too, to measure that rule: segments committed behind running work were
0.17 ms worse at the frame p50.

Measured on Mario Kart World (M3 Max, uncapped race, 8 draws alternated with
off every 300 frames): the frame's time above its GPU time 1.79 -> 1.47 ms
docked on average over eight phase pairs (lower in seven, the eighth
stalled), about 1.9 -> 1.45 ms handheld; frame p50 0.3-0.6 ms lower where
the scene's GPU time matched. Alternated together with the streamed
submission: frame time above GPU time 2.35 -> 1.53 ms, lower in eight of
eight pairs, frame p50 about 0.6 ms lower (docked).

Checked: t_reorder_chain (its cut counts), t_sub_overlap, t_wait_event,
t_queue_lifetime, t_render_enable_queue, t_counter_clock, t_gpuprof,
t_feedback, t_ub and t_geometry_hazards.
nvn_dirty_since_cached checks a texture's pages one by one against the
stamp of its upload. A Mario Kart World race binds packaged textures of
several MB, each checked page by page after any write to any tracked page
(the game makes one or two a frame): about 3 % of the replay thread on an
M3 Max.

Each range now keeps, per block of 64 pages, the highest generation of its
pages (bgen, raised in stamp_page by compare and swap, since two writers may
take their generations in one order and store them in the other), and the
check passes over a block none of whose pages was written since the stamp.

Measured with the next replay changes of this series (encode_args_ binding
order, tex_tp, treg_t's hot fields, fb_any_att): Mario Kart World's replay
5.28 -> 5.07 ms a frame, frame p50 8.22 -> 8.07 ms (M3 Max, handheld,
uncapped, in-run A/B).
mtl_addr and mtl_gpu_addr find a guest address's pool through a per-thread
cache, then by binary search over the pools sorted by start address. Every
pool added or removed marked the index stale, to be sorted again at the
next lookup, and emptied every thread's cache. A Mario Kart World race keeps
about 5,000 pools alive and adds about five and frees about three a frame:
0.8 full sorts a frame on the replay thread, and about 9 % of its lookups
missed the cache (1,024 pages, 8 recent pools), each a lock and a search.

A valid index now takes each change in place (pidx_add, pidx_drop: a binary
search and a move of the entries after it), with each entry's start address
beside it in g_pidx_lo so the search reads one array. Registering or
removing a large pool still marks it stale. A cache entry now counts only at
the pool generation it was made at, so a new generation needs no clearing,
and the cache holds 4,096 pages and 32 recent pools (PC_BITS, PC_RECENT).

Measured on Mario Kart World (M3 Max, handheld, uncapped race): pidx_sort
took 2.3 % of the replay thread's busy time and pool_held 4.2 %; after,
pidx_sort no longer appears and pool_held takes 1.3 %. The cache misses
2.3 % of lookups instead of 9 %, and the replay's CPU time a frame is about
4 % lower (in-run A/B), though the table no longer fits the L1 cache.
encode_args_ resolved every binding of a shader under g_rmu, the lock the
game's command threads take to register textures (Mario Kart World: about
100 new textures a frame), walked rf.b twice testing each binding's kind,
and asked each bound Metal texture for its type and pixel format: in a
race, about 3 % of the replay thread waiting on the lock, 3 % in the walks
and 2 % in the two messages (M3 Max).

- bind_no_reg names the kinds resolved without the texture and sampler
  registrations (uniform and storage buffers, the shader's own segments and
  tables, push constants, driver segments); bord_build orders a shader's
  bindings once, those first, and encode_args_ takes g_rmu only for the
  rest. Any other kind, a new one included, is resolved under the lock.
- tex_tp reads the type and pixel format the ID's view was made with
  (view_tt, view_pf, set with the view) instead of messaging the texture.
- treg_t puts the fields tex_fast_rid reads and writes for each binding
  first, about 40 bytes instead of three cache lines of the 440-byte entry.

Measured with the other replay changes listed in the per-block generation
commit: replay 5.28 -> 5.07 ms a frame, frame p50 8.22 -> 8.07 ms (M3 Max,
handheld, uncapped, in-run A/B).
tex_mtl_ on every lookup and tu_find on every use stamp asked an object
whether it is a texture with conformsToProtocol: (a walk of the class's
protocol list on every call) or respondsToSelector:. In a Mario Kart World
race the replay thread spent about 3 % of its busy time there (M3 Max).

is_mtl_tex keeps the answer per class for the first 16 classes seen
(textures, views, NvPkg, buffers) in a lock-free table; a class past those
is asked each time.
fb_prepare's depth rule, tile plan and snapshot loop each walk a fragment
shader's bindings for one that names an attachment of the pass, and in a
race nearly no draw has one: about 2 % of Mario Kart World's replay thread
(M3 Max). fb_any_att answers that first, from the pass's attachment serials
and the shader's texture and image slots; a shader that reads through
handles in uniform buffers, pool tables or dynamic tables answers yes and
takes the whole path as before.

passdump(), asked for every binding of every draw, reads g_pd_a0 with a
relaxed load instead of the sequentially consistent one a plain read of an
_Atomic gives.

Measured with the other replay changes listed in the per-block generation
commit: replay 5.28 -> 5.07 ms a frame (M3 Max, handheld, uncapped).
Texture views are kept by the Metal texture they view and the view's
parameters, 4 per texture. Mario Kart World samples its two reflection cubes
(one 128x128 RG11B10Float array of 12 layers) through 28 views, 7 levels x
2 cubes x 2 swizzles, which pushed each other out: about 57 views made
again a frame (17,741 made against 21,472 reused in 300 frames), 4.5 % of
the replay thread on an M3 Max. Its mip chains, drawn in passes that sample
the level above, also made their same-pass feedback views at every draw,
1.4 % of the replay thread.

The cache keeps 32 views per texture (VC_WAYS; a set is 1 KB, for the ~150
textures holding views), and fb_view takes feedback views from it. With 32,
about 2 views a frame are made (702 made, 38,094 reused).
The slow frames of an uncapped Mario Kart World race showed a host gap once
a second: at a submission's start, the release of render targets drawn
over (tu_pass) looked at each of the race's 130,000 texture IDs, each its
own cache line of a 440-byte entry, 1.9-2.3 ms of the replay thread while
the GPU waited (M3 Max, docked).

Each ID now goes into a list the first time it is stamped in a pass's
interval (tu_use, under g_rmu, with the list's epoch in treg_t.tu_mark), and
each submission takes up to 128 of the list onto the records (tu_tick,
tu_take_locked), so the pass finds little left. A use taken early in the
interval keeps that stamp: a record lags by at most one pass, against the
3 s a target waits. Past 16,384 IDs in one interval the pass looks at every
ID, as before.

Measured: about 10,000 IDs are used a second and a pass takes about 0.05 ms
(0 to 21 entries left for it), the releases unchanged (about 165 textures,
680 MB by frame 1700). t_dead_targets checks that each ID used goes once
into the list and that the pass empties it.
A game whose dynamic resolution budgets a 60 Hz frame from the differences
of its GPU timestamp reports keeps its full resolution on a fast GPU, even
uncapped. DM_NVN_GPU_TS_SCALE=<factor> (off by default; 1 or less is off)
makes a frame's reports read its GPU work as factor times as long from the
frame's first report (a + factor * (t - a), per frame the submission was
replayed in), so the game aims at 1 / factor of its budget. The picture is
smaller when the game lowers its size, so it is the player's choice.

DM_NVN_GPU_TS_SCALE=ab:<factor> applies it only in the DM_AB phases a switch
set to ab is on in: the resolution then moves between two sizes at each
phase, a repeatable test of what a resolution change costs (the next
commit's recycled heap measurement used it).

Mario Kart World docked on an M3 Max, uncapped, one run each: off 95.4 fps
(frame p50 10.15 ms, GPU 8.81 ms); 2: 117.8 fps (8.03 ms, GPU 6.70 ms, the
scene at about 1664x932). t_counter_clock checks the stretch across frames.
A render target is made in a placement heap of its own, which waits for a
texture of its size once freed (rh_place). Two limits made Mario Kart World
make its targets' memory again whenever its dynamic resolution moved:

- A waiting heap took a texture down to two thirds of its size. A docked
  step from 2560x1440 to 2134x1200 (69 % of the area) left every target's
  heap too large, so each step made them again: hundreds of MB that a
  residency commit then made resident on the replay thread, frames of
  60-110 ms. rh_fit lets a heap take a texture down to 40 % of its size
  (DM_NVN_RT_RECYCLE_FIT, in percent, default 250).
- At most 256 MB of heaps waited, less than a docked set of targets. At the
  60 fps cap, with the GPU at a low clock and the resolution moving every
  frame, the oldest were freed just before a size wanted them again: 1,341
  heaps made and 1,114 freed in 900 frames, 1.2-2.1 GB added to the
  residency set per 300 frames, single frames of 95-148 ms. rh_cap now
  allows a sixteenth of the device's recommended working set, from 256 MB
  up to 1 GB (DM_NVN_RT_RECYCLE_MB overrides it).

Measured with the resolution moved between two sizes every 300 frames
(DM_NVN_GPU_TS_SCALE=ab:2.5 DM_AB=300, docked, uncapped, M3 Max, two runs
each, 2,700 frames): heaps made 2,859-3,003 -> 1,866-1,919, residency added
6.9-7.7 -> 4.7-4.9 GB and its commits 400-406 -> 277-279 ms, frames over
20 ms 16-18 -> 11-12, the most resident memory the same (about 11 GB). At
400 % the small textures took the large heaps: fewer made, more committed
(310 ms). check_t_rt_recycle has a target half a waiting heap's size take
it.
Dispatches are ordered as NVN orders them: a barrier when the game issued
one since the dispatch before, or when a copy's range meets the dispatch's.
A dispatch whose reach is no memory range (an image, a buffer texture, a
handle in a uniform slot, global memory traced to no storage buffer) kept
the full order on both sides. Of Mario Kart World's about 120 dispatches a
race frame, about 94 are such, many of one workgroup, so its compute work
waited on itself.

With the new profile key dispatch_rangeless game, a rangeless dispatch
follows the game's barriers against other dispatches too, and is ordered
against copies as a whole: a barrier before it when a copy, update or fill
ran since the last barrier, and each later copy waits for it, as it counts
as having read and written everything. Only Mario Kart World's profile sets
it. DM_NVN_DISPATCH_RANGELESS=0/1 overrides the key and ab alternates it;
the periodic compute dispatch line counts each kind.

Measured on Mario Kart World (M3 Max, uncapped race, DM_AB=300
DM_NVN_DISPATCH_RANGELESS=ab, DM_NVN_GPUPROF=every:20, five phase pairs
each): compute and copy time a frame docked 1.29-1.51 -> 0.87-0.99 ms
(paired -0.48 ms), handheld 1.11-1.32 -> 0.69-0.76 ms (-0.52 ms); render
passes unchanged; frame p50 -0.36 ms docked and -0.33 ms handheld. The race
pictures show its particles, shadows and HUD as before.

Checked: t_dispatch_barrier in both modes, with rangeless dispatches in
both orders (a chain behind the game's barriers gives the sequential
result, unordered dispatches get no barrier, copies stay ordered both ways,
a rangeless dispatch between a fill and a copy is ordered after the fill
and before the copy).
A draw whose fragment shader writes the six faces of a cube level at once
computes all six outputs in one thread, each from its own face's direction.
Mario Kart World's cube map filters make 32 cube samples per face, 192 per
thread: a 64x64 level is 128 SIMD groups of such threads and a 2x2 level
one, too few to hide the samples' latency, so the pass cost a few long
threads whatever its pixel count.

fsp_plan, for every game: a draw of at most six vertices and one instance,
whose four to eight colour targets are distinct layers of one level of one
array or cube texture, is drawn once per target into one layered
attachment. Each draw has a pipeline with only that target's colour output,
built whole (PSO_FACE), so the compiler drops the other outputs' work; the
colour attachment map sends that output to the one attachment, and a
vertex amplification view mapping sends the draw to the target's layer, as
in slice-merged passes. The draw keeps its targets whenever it could tell
the difference or a precondition is missing (blending, alpha to coverage,
logic operations, alpha test, depth or stencil, discard or sample mask,
storage or image writes, reads of its own targets, a target it does not
write, a clear, layers that cannot be attached together, no Metal 4
compiler, pipelines still building). DM_NVN_FACE_SPLIT=0 turns it off and
ab alternates it.

Measured on Mario Kart World (M3 Max, docked race), per pass: 64x64
271 -> 66 us, 32x32 150 -> 30 us, 16x16 to 2x2 about 95 -> 21-25 us. In-run
A/B (DM_AB=300, uncapped): docked GPU p50 9.53 -> 8.57 ms; handheld GPU p50
7.93 -> 7.37 ms and frame p50 9.59 -> 9.31 ms, shorter in each of six phase
pairs.

Checked: a Metal harness drew all six levels of a chain with the game's
uniform blocks both ways and read them back: no texel differs. t_perf_order
draws six outputs into six array layers in reverse order through the
replay, before the pipelines are built, after the split, and with a
fragment that may discard (no split); every layer holds its own output.
A shader row could carry NVN2's task and mesh stage numbers (6 and 7) while
the host uses slots 3 and 4. The prewarm workers cache a shader by name, so
the first worker could publish the raw stage even for a later request from
a valid mesh row; a draw using that shader could then write stage 7 into its
own mesh row, and the next launch rejected that row: the game logged
"task / mesh pipeline: ... required at frame" for pipelines the manifest
held.

Standalone shader rows now load with the stage in the game's shader map, as
the live loader does; a stored stage 7 reads as 4 only in a mesh row, with
the map, task, fragment and render-state checks unchanged. Prewarm prepares
one library per shader name and one pipeline per normalized mesh state and
task shader.

Found on Mario Kart World: a base-game A17 Pro session recorded 12 native
mesh pipelines, ten with mesh stage 7. Replaying the same manifest on an M3
Max through frame 1,200, the old host prepared none and built 11 at their
first draw; this one prepares 12 and builds none at a draw. t_pso_skey and
t_pso_warm load raw and host stage numbers together and check the first
demand and its pixels.
The game's note gains what the work in this series found and measured on an
M3 Max: where a race frame's time goes uncapped (docked and handheld), what
bounds it after each change, the cube map filters, barriers between draw
passes, attachment traffic, the boot that can abort at the course video
(nn::codec 3604, open), its compute queue, what was tried and not kept, and
the residency commits at the 60 fps cap. Docs only.
A depth-stencil target stays attached for the whole NVN pass, so both planes
were loaded (and stored) whatever its draws did: Mario Kart World's race
loads the stencil plane of its 2560x1440 Depth32Float_Stencil8 in about 15
passes a frame whose draws never enable the stencil test (~50 MB docked).

A plane no draw of the pass used in that pass's earlier occurrences (passes
keyed by their attachments, g_dsi_tab) now goes in with load and store
DontCare; a later draw or partial depth-stencil clear that needs it ends the
pass first (dsi_guard), so a wrong prediction costs a pass split, never a
pixel. Metal touches a plane only through the depth-stencil state (dss_get).
On by default; 0 loads every plane, ab alternates with DM_AB.

In-run A/B on an M3 Max (uncapped race, both phase orders): docked GPU p50
-0.24 ms, frame p50 -0.15 ms, attachment loads about -35 MB a frame;
handheld GPU p50 -0.20 ms, frame p50 -0.08 ms; no fallback, same pictures.

Check: check_t_ds_idle (64 checks under the Metal debug layer, each case
against the switch off); t_unwritten_store pins the switch off.
A uniform read at a computed offset is bounded in the shader by comparing
its word index with the binding's size, ((uint(row) << 2u) | uint(column)) <
size >> 2u: a shift, an or and a compare on every read. The size table holds
only 0, 65536 or sizes rounded up to 256 bytes, and the column is some value
& 3, so with shader_row_bounds 1 dmsh_fetch.row_bounds compares the row,
uint(row) < size >> 4u: the same choice for every row whose word index does
not wrap, and false where it wraps (where the word comparison could read past
the binding). Shaders whose column is not a value & 3 keep the word form.

On for Mario Kart World (3,900 of 11,560 shaders; chain 150dffe2a4dc). Its
material pixel shaders loop over lights with about 12 bounded reads a light:
off the game 7-12 % faster (31b1e17f0c848ab3, 2 and 8 lights); in the race
(M3 Max, docked, uncapped, GPU profile, two pairs of runs in both orders)
scene passes 2.43 -> 2.34 and 2.42 -> 2.23 ms a frame, deferred lighting
0.48 -> 0.43 and 0.48 -> 0.44 ms. Pictures unchanged.

Check: test_dmsh_fetch.py (test_row_bounds); all 127,628 bounded comparisons
in the game's compile cache have a column x & 3.
What the 2026-11-16 search tried in in-run A/B and did not keep (open pull
requests seedds#2526, seedds#2677 and seedds#2771 measured on this game, DM_NVN_ARGS_LEAN,
DM_NVN_REC_EAGER, DM_NVN_PASS_FENCE), and what shader_row_bounds measured on
its light loops. Docs only.
sleep_precise returns once its deadline is within 20 µs, which the deadline of a
20 µs SleepThread is from the start, so that sleep returned without sleeping.
Mario Kart World's job dispatcher (main+0x4520 on v0), which its WorkerMgr
threads and main thread call to wait for a job group, sleeps exactly 20 µs (625
ticks of 31.25 MHz) between its scans of the job arrays, with three yields a pass
that the yields' register test reads as progress: the wait was a busy loop.
dm_guest_sleep_ns now makes a sleep of up to 40 µs one nanosleep of its length.
DM_SHORT_SLEEP=0 returns at once as before (ab alternates with DM_AB phases,
through nvn_mtl.m's sw_mode, exported as mtl_sw_mode / mtl_sw_on). The power
line's top yielders count short sleeps and the length of the last one.

M3 Max, race at the 60 fps cap, in-run A/B: handheld CPU energy 4.35 -> 4.00 W
(-0.41 W paired, 4 of 4 pairs), 72.8 -> 68.0 mJ a frame, WorkerMgr threads
26 % -> 10 % of a core; in the other phase order -0.25 W paired (5 of 5),
-4.3 mJ a frame; docked, phases inverted, -0.22 W. Uncapped handheld: frame
p50 -1.1 ms paired, replay -0.45 ms a frame.

Test: t_pollwait (a 20 µs sleep asks for one host sleep of 20 µs; fails without
the change), host tests, git nx qtest.
The power line had no GPU energy on the Mac (task_power_info's GPU time reads 0),
and at a frame-rate cap the GPU lowers its clock, so its time per frame does not
show what a change saves. With each power line, dm_gpu_power_request (memstat.m)
has a helper thread read IOReport's "Energy Model" GPU Energy channel (the whole
system's GPU; an in-run A/B's paired phases cancel the other apps) and this
process's GPU time (the AGX driver's AppUsage accumulatedGPUTime on its user
clients of the IOAccelerator), and log "GPU power up to frame N". The reads stay
off the frame thread: subscribing takes about 55 ms once, then about 2 ms a
request (M3 Max). iOS: no-op.

The energy is the whole system's GPU: on a Mac shared with other apps a
single phase pair moves by 2-5 W (DM_NVN_DS_IDLE at the 60 fps cap read
-1.9 W paired in one phase order and +1.1 W in the other), so read it on a
quiet Mac in both phase orders; development.md says so.

Test: git nx qtest (18/18), test_docs.
The largest item of the attachment traffic counters is no real traffic: a
6144x6144 sparse texture whose three largest levels the game draws into
with two small draws a frame, counted as loaded and stored whole, while an
Apple GPU loads and stores only the tiles geometry touches (a Metal test on
the M3 Max: 47 us for such a pass against 286 us with the draw over all of
it). The tiny passes are the cost there: at the 60 fps cap the cube filter
chains' 21 levels take 50-64 us each, about 1.4 ms of a frame's 7.5 ms of
encoder time (open). Docs only.
What a race frame's 116 render passes cost on the CPU at the 60 fps cap
(Instruments Time Profiler on the host, M3 Max, handheld): about 5-6 us a
pass on the encode thread making and ending render encoders and 3.6 us
opening it on the replay, about 1 ms a frame; why the passes end
(DM_NVN_PASSDUMP); and the QoS utility class and DM_RT=0, tried and not
kept. Docs only.
Every waiting thread was on one chain, g_wait, and pick walked all of it to find
the waiter to wake, a wake walked it again to take the thread off, and
SignalToAddress, a lock handoff, a condition signal and an event's signal walked
it too, all holding the scheduler lock G over structures other cores write. With
dozens of threads waiting each wake held G long enough that the other threads
queued on it, each with a kernel wait and wake of its own.

The chain is now doubly linked (a thread leaves it in place), and the waiters
are also in buckets (wb_slot: lock and address waits by address, condition waits
by key, synchronization waits in one bucket); pick and the other walks look at
one bucket. The waiter chosen is the same (priority, then registration order).
DM_WAIT_INDEX=0 walks the whole chain as before; ab alternates with DM_AB.

Mario Kart World keeps about 87 threads waiting: at its 60 fps cap about
50,000 acquisitions of G, 31,000 picks and 22,000 waits and wakes a second.
M3 Max, in-run A/B at the cap: handheld CPU energy -0.23 W paired (5 of 5
pairs), process CPU -1.9 ms a frame; docked, phases inverted, -0.18 W (5 of
5). Uncapped handheld process CPU -1.2 / -2.1 ms a frame, frame time
unchanged (+0.10 / -0.05 ms).

Test: t_waitaddr (waiters on two addresses; run with and without the index),
host tests both ways, git nx qtest.
A CFMutableSet leaves a deleted mark in each removed value's bucket and
clears them only when it grows, so a pool whose textures come and go at a
steady count slowed down without end. In Mario Kart World (largest pool
about 37,000 live textures) an add or remove took about 2.5 us midway
through a race, 171 Time Profiler samples in 10 s on guest threads at the 60
fps cap; 6 after.
treg_drop_pool_views walked every registered texture ID under g_rmu at each
nvnMemoryPoolFinalize. Mario Kart World registers about 130,000 IDs of 440
bytes; the walk took 58 Time Profiler samples in 10 s on guest threads at
the 60 fps cap, none with the per-pool list (g_treg_pool, pprev / pnext,
kept in mtl_reg_tex / treg_unlink as the serial list is). t_pool_notes
checks IDs moved or unregistered from a list's head, middle and end.
lc_land opened a clear-only pass per waiting clear. Mario Kart World clears
the five layers of a 128x128 2D array one at a time every frame: 5 of its 9
clear-only passes. lc_layer_run merges groups that each clear one colour
attachment in the same slot through one-layer views of consecutive layers of
one level of the same 2D array, with the same colour, into one pass with
renderTargetArrayLength. At the 60 fps cap (handheld, ab in both orders):
4-4.5 fewer passes a frame, GPU time -0.42 / -0.44 ms a frame, CPU unchanged
within noise. New test t_lazy_clear_layers (switch on and off, Metal
validation).
sm_scan stopped at OP_BIND_UBO_SMALL and OP_BIND_VBUF1, plain state as
OP_BIND_UBO and OP_BIND_VBUF are. Mario Kart World binds them between its
per-layer draws into a 128x128x5 and a 64x64x6 array: merged in pairs, later
runs not at all. At the 60 fps cap (handheld, both phase orders): 9 fewer
passes a frame, GPU time -1.03 to -1.23 ms, process CPU -0.35 to -0.52 ms,
CPU energy -0.15 W. t_perf_order binds them between layers.
The game's submitting thread copied each record with its own call and
memcpy, expanded each compact record into a 4 KB stack buffer and copied its
canonical records once more, and looked each named program or texture up in
the job's table. Runs of plain records are now copied with one memcpy and
walked in place (nq_copy_run), compact records expand straight into the node
(nq_room), and the job keeps its last snapshotted object. Mario Kart World
at the 60 fps cap (handheld, ab in both orders): the presenting thread's CPU
0.92 -> 0.79 ms a frame (-0.126 / -0.129 ms, ten of ten phase pairs).

An acceleration-structure build is not plain: nq_record_one also copies
the CPU arrays it points to (nq_as_snapshot), so OP_AS_BUILD stays out of
the runs.
A thread filling a pool's protected pages in order took one fault, signal
and mprotect per 16 KB page, each fault walking every registered range. A
fault on the page where the thread's last fault or release ended now
releases the next protected pages of that range in one mprotect, a window
doubling up to 32 pages, stopping at the first unprotected page and before
the range's last page; released pages are stamped as written. Mario Kart
World streams texture storage this way (82-96 % of faults on the next page):
80-90 % fewer faults while it streams at the 60 fps cap (handheld, ab both
orders). Benchmark: 1.5 us of CPU a page instead of 5.6 (12 among 5,000
ranges). New test t_dirty_ahead (on and off), benchmark b_dirty_fill.
cap_rec_fields with the queue's snapshot callbacks changes nothing but
texture and program fields, yet every copied record went through it, with
indirect calls for each address. cap_rec_snap (beside cap_rec_fields) names
the ops that have such fields, t_capture checks it against the walk for
every op, and the copy walks only those. nq_plain is a bit test. Mario Kart
World at the 60 fps cap (handheld, ab in both orders, temporary switch): the
presenting thread -0.031 / -0.075 ms a frame, nine of ten pairs.
Each guest wait slept on the thread's condition variable with the thread lock G
as its mutex, so a woken thread took G back inside pthread_cond_wait, and
Darwin's mutex sleeps in the kernel at once when G is held. block now waits on a
word of the thread (os_sync_wait_on_address) with G let go; a wake bumps the
word after setting woke under G, so a wake between the unlock and the sleep
fails the kernel's compare. g_lock waits up to 4 µs for a held G in user mode
before sleeping, unless another thread already sleeps for it.

DM_WAIT_ON_ADDRESS=0 / DM_G_SPIN=0 restore the old wait and lock (ab for A/B).
The power report's threads line counts G's acquisitions, contention and spins.

Mario Kart World, M3 Max, 60 fps cap, in-run A/B: handheld process CPU -1.6 ms
a frame (10 of 10 pairs), CPU energy -0.17 / -0.20 W; docked -2.2 ms, -0.33 W.

Test: t_wait_word (hand-offs under a contended G, timed waits), both ways and
under tsan-threads; host test suite, qtest.
Setting a time-constraint policy takes a thread's QoS away, and the standard
policy that rt_retire set afterwards left the thread at the task's default
priority, 31 on the Mac, below every other guest thread (47 with the QoS
user-interactive). Mario Kart World's main thread acquires in the menus, so
it ran every race at 31. Each slot now keeps the thread's timeshare base
priority from when it took the slot, and rt_standard follows the standard
policy with a precedence importance of the difference (31 -> 47). Setting
the QoS again or pthread_set_timeshare_self did not restore it; the QoS
policy flavour is refused.

DM_RT_FRAME also takes ab: off phases send the frame threads back through
rt_standard. MKW at the 60 fps cap (M3 Max, both phase orders): with the frame
threads' declarations, process CPU -0.83 / -0.52 ms a frame, CPU energy -0.13 /
-0.04 W, so they stay on. The retire line names the thread and its priority.

Test: t_rt_comp models the kernel's priorities and checks the retired acquire
thread is back at 47 (fails without the precedence step).
Every submission grew a fresh commands buffer from nothing to a few hundred KB
by doubling, each step a realloc that often moved it into pages never touched,
and freed it after the replay. The replay now hands the buffer back
(nq_buf_put; the 8 largest of 64 KB or more are kept) and a new node takes the
largest kept one as its first (nq_buf_take). DM_NVN_Q_RECYCLE=0 frees as before
(ab for A/B).

Mario Kart World, M3 Max, 60 fps cap, in-run A/B both orders: the submitting
thread's @cpu_ms -0.037 / -0.051 ms a frame (7 of 10 pairs). A run that
poisoned each kept buffer before reuse rendered the race as usual.

Test: queue tests (t_nvn, t_capture, t_queue_lifetime, t_wait_event, ...),
qtest.
thr_sys_ns took a port reference with mach_thread_self and dropped it with
mach_port_deallocate, two more kernel calls each time; the replay reads it
twice per job (nq_cost_begin / nq_cost_end), about 6,000 times a second in Mario
Kart World at its 60 fps cap (59 samples in a 10 s Time Profiler trace). The
pthread's own port gives the same value: 780 -> 445 ns a call (M3 Max,
dev/tools/thrsys.c), about 0.035 ms a frame. The translation detail line's
kernel time reads as before (0.29-0.34 ms a frame).
Every commands node of a game's submission was replayed between mtl_sub_begin
and mtl_sub_commit: a Metal command buffer, its fence, residency naming and
completion, about 55 us of process CPU even with nothing encoded. A node that
only sets its queue's texture and sampler pools (and signals nothing) is now
applied to its queue's state with no submission (mtl_exec_state_only); the
queue keeps its last fence. Not while capturing. DM_NVN_EMPTY_SUB=0 submits
them as before (ab for A/B).

Mario Kart World submits two such nodes a frame (queues 6 and 7). 60 fps cap,
M3 Max, handheld, both phase orders: 2.3 fewer command buffers a frame,
process CPU -0.73 / -0.42 ms a frame on average (7 of 10 pairs), frame times
equal, CPU energy within the noise.

Test: t_empty_sub (switch on and off; mutation-checked), qtest 20/20.
The submit thread retained and released objects that other tables
already hold, at every draw: the arena block of every argument block
(arena_alloc's strong out-parameter and the locals that took it), the
uniform buffers cbuf_slot hands back only for a diagnostic check, and
every program and pipeline prog_get and pso_get return, as ARC ignores
__unsafe_unretained on a return type and paid an autorelease and a
claim per call.

arena_alloc_u lends the block (the submission's arena list, then the
free list, hold it); cbuf_slot, cbsize_table, ub_padded and
encode_args_'s locals borrow; prog_get_ptr and pso_get_ptr return a
pointer that the old names bridge (the serial table and the pipeline
caches hold them; a program without a serial is kept in
g_prog_noserial); draw_ keeps its pipeline unretained, its program
pointer stays strong as it is compared by address.

Mario Kart World at the 60 fps cap, Time Profiler: reference counting
went from 11.4-12.1 % of the replay thread's samples to 8.2 %, about
0.18 ms of a frame's 4.5-5 ms of replay (M3 Max).
The replay's reference counting left after the arena blocks, programs
and pipelines: tex_by_id returned each ID's view as an object (an
autorelease and a claim for every binding that missed tex_fast_rid's
own test), as did hybrid_get, pull_pso and sm_amp_get, whose
__unsafe_unretained return types ARC ignores; draw_color_writes asked
the DM_NVN_MAGSCAN diagnostic for an override at every draw, an object
return even when it is off; and a few locals retained shaders their
program holds.

tex_by_id_ptr returns the view g_treg holds (the caller holds g_rmu),
the three pipeline lookups return pointers as pso_get_ptr does, the
diagnostic is asked only while it is on, and prog_border, fb_prepare,
draw_gs_check and tu_find borrow.

Mario Kart World at the 60 fps cap, Time Profiler: the replay thread's
reference counting 8.2 % -> 5.2 % of its samples (11.4-12.1 % before
the previous step), about 0.15 ms of a frame (M3 Max).
nvn_sparse_alias answered whether a guest range may alias another pool
through a sparse virtual pool's own range under g_vp_mu, which the
game's mapping threads take, by walking every such pool; the replay
asks it for each texture a draw samples against each attachment and
for every compute access. The ranges are host mmap reservations on
both sides of the guest's address space, so a lowest-highest bound
leaves the guest's addresses inside it.

The ranges are kept sorted in a fixed table rewritten under g_vp_mu
whenever a pool reserves or drops its range, behind a sequence count
(a seqlock). nvn_sparse_alias and nvn_host_readable binary-search it
without the lock (the ranges never overlap) and fall back to the
locked walk while it is written, past 1,024 ranges, or for an address
inside a range.

Mario Kart World at the 60 fps cap, Time Profiler: nvn_sparse_alias
47 -> 6 of the replay thread's samples in 10 s, tex_storage_overlap
28 -> 5, about 0.06 ms of a frame (M3 Max).
Every implemented NVN function but the command recording calls went
through the big-stack entry, including handle builders, buffer address
getters and the setters of state objects and builders, which a game
calls in the tens of thousands a frame. Mario Kart World makes about
17,000 such calls a frame (nvnDeviceGetTextureHandle 5,000,
nvnChannelMaskStateSetChannelMask 2,400, nvnBufferGetAddress 1,000,
the blend, colour, depth-stencil, polygon and texture view setters
300 to 900 each), each saving its registers and switching stacks.

The 59 leaf functions listed in g_nvn_leaf, each of which only reads or
writes a few fields, stay on the caller's stack; a line one logs goes
to the big stack by itself (dm_log). A listed name that is not an
implemented function stops the start.

Mario Kart World at the 60 fps cap, Time Profiler: the entry and its
helpers went from 111 to 9 of the game threads' samples in 10 s, about
0.17 ms of their CPU a frame (M3 Max).
A face-split draw holds its pass alone, and a game that filters several
cube maps level by level draws each chain's levels in a row. Mario Kart
World's three chains (one cube texture and an array of two cubes) came as
21 passes a frame, though each level of a chain samples only the chain's
source cube, and each small pass costs about as much GPU time as a large
one.

When a face-split pass is about to open, fsm_plan scans the ops after its
draw in replay order (as cs_hoist_try does), applying state ops and target
changes, for face-split draws into other textures or layers whose level has
the same size, format and layer count. Up to three join the pass as
attachments 1-3 (fsm_attach; a colour attachment map sends their outputs
there), fsm_run draws them after the pass's own draw with their own state,
and the replay skips them where it reaches them (fsm_take). One joins only
when nothing passed over reads or writes its targets and nothing passed
over writes what it samples; every draw passed over must draw into colour
targets only and sample known textures, and the scan stops at any other
draw or op. Nothing joins while lazy clears or deferred uniform updates
wait or occlusion samples are counted. DM_NVN_FACE_MERGE=0 turns it off,
ab alternates it with DM_AB.

Mario Kart World, M3 Max, handheld race, in-run A/B (DM_AB=300,
DM_NVN_GPUPROF=every:20) on a Mac busy with other apps: 21 cube filter
passes become 7 (about 101 -> 87 a frame). At the 60 fps cap, the GPU time
of passes up to 64x64 -0.67 and -0.76 ms a frame in the two phase orders
(six of six pairs each), render passes -0.54 and -1.15 ms, system GPU
energy -0.60 and -0.26 W. Uncapped, GPU p50 -0.52 ms handheld and docked
(six of six pairs each), docked frame p50 -0.38 ms. Process CPU unchanged
within the noise.

Test: t_perf_order draws X level 0, X level 1, then layers 0-5 and 6-11 of
Y at levels 0 and 1, into textures cleared first: two passes of three
attachments with the merge, six without, every layer holding its own
output, under Metal validation (also with DM_NVN_FACE_MERGE=0); qtest
32/32.
The standalone fixture calls finish without loading a game profile. Supply the default value for shader_row_bounds so its synthetic shader builds and all 949 Metal replay checks run.
Do not pass a nullable descriptor name to Metal when specializing a device function. Keep the existing fallback on failure. Drop the obsolete t_logic nullability entry; LLVM 23.1.4 reports 187 findings on the merge with main, all within the reduced baseline.
The shared GPU read event now also serves texture uploads. Check the MDI wait counter so the geometry snapshot cases still assert exactly which draws needed a CPU wait.
Carry forward the previous merge resolution: the face-split replay uses the CPU and GPU addresses returned at allocation, and the documentation names the borrowed arena helper. The resulting tree matches the independently resolved merge with upstream.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation game: 0400C3F00006E000 A game profile host The Horizon host: SVCs, services, threads, memory (dm/host) nvn NVN on Metal and its tests (dm/gfx/nvn, dm/gfx/tests) shader chain The shader translation chain (DMSH_CHAIN): a change rebuilds every game's shaders tools Tools and scripts (dm/tools, scripts)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant