[aksmith-git]

What and why

Follow-up to #1245 (sn0wst0rm), on its head 5269ecc5: this branch is that PR plus one commit, e364b8c6, so the diff here shows #1245 too until it lands. Opened against main as the template asks; if it is better folded into #1245 itself, the commit cherry-picks onto 5269ecc5 as is.

Symptom. With the guest event queue ordering, Ocarina of Time (Switch 2) on an iPad Pro (M5), Docked 1536x864, runs with the GPU idle between the scheduler's chunks. The game makes about 6 submissions a frame; cut at its event signals, waits and recorded fences they become 37 host submissions, and the GPU drains between a chunk and the next while the host commits it:

iPad Pro (M5), Kokiri Forest, same scene	waits ignored (before #1245)	#1245 as merged
host submissions per frame	6	37
GPU idle inside the frame, p50	0.00 ms	2.5 ms
frame, p50	20.4 ms	22.9 ms
64-draw segment commits per frame	6.4-6.9	1-3

GPU time per frame is the same in both. The frame listing shows 35 chunks for 6 guest submissions, alternating queue 5 (compute) and queue 1 (graphics) about 12 times, cut by 19 signals and 26 waits that were all satisfied by the scheduler before the next chunk; the DM_NVN_GPUPROF timeline shows 1.6 ms of idle before the 760-draw colour pass (the segment counter restarts per chunk, so the pass is committed whole where it used to be fed in 64-draw segments) and about 60 smaller gaps at the other chunk boundaries.

Cause. Every chunk qe_pump offers is a host submission of its own: a command buffer, an allocator lease, a visibility buffer, a completion record, a commit and, with the encode thread, a rec_drain(). It is not a CPU wait on the previous chunk's fence (qe_read only picks the projected value over the mapped word, and sync waits are satisfied by nvn_qs_scheduled); it is the granularity.

Change. DM_NVN_CHUNK_MERGE=1 (off by default; ab alternates it with DM_AB): qe_pump keeps a chunk's command buffer open and encodes the chunks it offers next into it. mtl_chunk_end lands the chunk's passes, clears, deferred draws, uniform updates and blit encoder (what mtl_sub_commit does before it commits), the queue is sealed as after a commit, mtl_chunk_begin sets the per-chunk state of sub_begin without a new buffer, allocator, visibility buffer, completion record or segment clock. The buffer commits when the pump has no ready step left (every pump ends committed), before a present, and in submission timestamp mode when the next chunk belongs to another logical submission (post_run takes one clock per buffer; in segment mode chunks of any submission share one). The scheduler records the open buffer's fence as mtl_pending_fence() = g_fence + 1 (the convention OP_FENCE_SYNC and the PASSGPU ring use) for the chunk and for the signal's projection; every CPU wait on a fence runs its pump first under the submission lock, so no thread can wait on a fence not yet committed. Ordering is unchanged: the chunks go onto the one Metal queue in the order the scheduler offered them, and a chunk whose wait is not satisfied still waits for its producer's offer. What changes is that a satisfied wait, a signal or a recorded fence costs no commit, allocator, visibility buffer, completion record or drain.

The [nvn] timing line gains scheduler chunks per frame N, M of them merged into an open command buffer. Reference entry: docs/reference/nvn-objects.md, "Scheduler chunks committed one by one"; the switch in docs/env_switches.tsv.

Checked

• Tests (M4 Pro, macOS 27; GAME=0400C3F00006E000, since this base has no Ocarina of Time profile): t_queue_schedule 295 checks / 0 failed, check_t_capture 82 / 0, check_t_queue_vis 94 / 0, check_t_queue_alloc 388 / 0 (32 split chunks, 0 allocator waits), check_t_nvn 327 / 0 both ways (it now runs once plain and once with DM_NVN_CHUNK_MERGE=1), and DM_NVN_CHUNK_MERGE=1 DM_NVN_GPU_TS=submission ./t_nvn 327 / 0 (the one-clock-per-buffer rule). dm/tools/tests/test_docs.py 11 OK; test_env_switches.py fails on this base as before the change (DM_NVN_CUT_FIRST, DM_TEST_ALLOC_LEGACY, not touched here).
• make -C dm/host GAME=0400C3F00006E000 dmhost builds (0 errors).
• Games run: none on this exact branch yet. The same change on our Ocarina of Time stack (main of 2026-11-08 with Honor NVN event dependencies across guest queues #1245, Ocarina of Time: keep gameplay at real speed below 60 FPS #1704, Game-mode draw passes hold the next pass's task and mesh shaders until their fragments are done #1707, Profile key gpu_ts_hz, the tick rate of raw counter reports (default 614.4 MHz, unchanged): Ocarina of Time reads them at 31.25 MHz, so its wind and leaves moved 19.66 times too fast #1714 and our changes) builds and passes the same tests there (t_nvn 336 / 0 both ways); the iPad run of the merged form is queued and I will post its numbers here. The numbers above are the before.
• Not run: regress.py (off by default; the path exists only once a game has recorded an event wait).
• Devices and OS: iPad Pro (M5) for the measurements; M4 Pro, macOS 27 for the tests.

Docs

• The finding is in docs/reference/nvn-objects.md, and python3 dm/tools/docs_symptoms.py was run (the symptom index)
• No game files, keys or data extracted from a game in the change or the attachments