Repository navigation
Conversation
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 |
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.
atinseau
force-pushed
the
codex/pr-mkw-60fps
branch
from
November 17, 2026 17:09
d0a00de to
54d4c27
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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,
=0restores 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 theDM_NVN_SUBTLtimeline 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_passover the IDs used since its last pass (a 2 ms stall once a second), per-pool texture lists for Finalize, annvn_hmapfor 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 keydispatch_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 keyshader_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 onin 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_feedbackon d6585a2; main has since fixed the same caller. Three changes of the measured series are left out because main has them since: theDM_GL_RENDERPROGS/DM_NVN_UNBIND_DEFERtable rows (b7e4b98), a storage takeover looking at each shared entry once (d664d31, the same fix found on Ocarina of Time) and typed counts oft_feedback/t_pso_prewarm's JSON arrays (854a596 made the same fix).Checked
0bd40f9f(PR head54d4c27f): the shader chain is391a0e7dce4b, 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; inputs49790ad645dd). 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.a2c731e3; merged928271e, test fixture fixd0a00de1):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.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.make -khad one failure: the OpenGL LOD-bias pixel assertion int_gl_imports, reproduced on unmodifieda2c731e3. Both CI CPU variants passed. In separate repeated runs,t_nvnalso intermittently faulted innvn_sparse_protectduring present; reproduced with the same stack on upstream.dm.tools.tests.test_shader_toolchain_cachepass under Python 3.14 (Mac-only, iOS-only and combined mesh selection included).DM_AB=300, both phase orders) for each change, in its commit message.regress.py checkwas 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..HEADnames 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_SPINandDM_WAIT_INDEXchange 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_SPLITand the slice-merge binds: Breath of the Wild's cube filters (DM_NVN_PASSDUMP).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 isDM_FPS_TARGET=0 DM_PRESENT_HZ=0 DM_PRESENT_LINK=0 DM_PRESENT_SCREEN=0 DM_VSYNC_HZ=240.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.
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
docs/reference/<subsystem>.mdentry, andpython3 dm/tools/docs_symptoms.pywas run (the symptom index)dmsh_chain.py --headerwas run anddm/gfx/nvn/dmsh_chain.his part of the change (chain: compare bounded uniform reads by 16-byte rows)