Skip to content

Split nvn_mtl.m into topic parts (mechanical, identical machine code) - #133

Closed
v0lumehi wants to merge 5 commits into
seedds:mainfrom
v0lumehi:split-nvn-mtl
Closed

v0lumehi wants to merge 5 commits into
seedds:mainfrom
v0lumehi:split-nvn-mtl

Conversation

@v0lumehi

@v0lumehi v0lumehi commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Builds on #87 and the pipeline series #122–#125: this PR contains their commits, and only the last commit is new here. It touches every line of nvn_mtl.m, so it should go in after them. Proposed in #131.

Update: #122 landed on main as 66abbc3, and this branch now builds on main (the commits of #123–#125 and #87 are still in it).

Update 2: #87 landed on main as a188613. The branch now builds on main with #123–#125 rebased, and the split was cut again from that nvn_mtl.m at the same top-level blocks (9,473 lines; 557 stay in nvn_mtl.m). Checked again: the parts put back give the unsplit file byte for byte; clang -E -P and otool -tvV (Mac and iOS) differ only in the 35 res_add_at line numbers, which stay distinct. dm/host/Makefile needs no change any more: main already lists nvn/*.inc in GFX_H.

dm/gfx/nvn/nvn_mtl.m had 9,281 lines with the series. That makes it hard to read one topic at a time, for people and even more for coding agents, whose context fills up with surrounding code.

What

nvn_mtl.m stays the only compiled file, with 522 lines: includes, the residency set, deferred release, mtl_init and the memory pools. It #includes 14 topic parts in the original order, in the same folder, named like the existing nvn_geometry.inc / rt_range_check.inc:

Part Lines Holds
nvn_mtl_submit.inc 383 queries, submission, encoder wrappers, blit helpers
nvn_mtl_ubuf.inc 420 inline uniform updates, commit, wait
nvn_mtl_tex.inc 862 textures, alias tables, upload paths
nvn_mtl_pass.inc 672 render passes, pass dumps, store lookahead
nvn_mtl_shader.inc 871 shader map, shader loading, descriptor pool
nvn_mtl_state.inc 622 draw state, vertex conversion, pso_desc
nvn_mtl_pso.inc 657 Metal 4 pipelines, archive, hybrid, prebuild
nvn_mtl_args.inc 398 depth-stencil states, dummy resources, encode_args
nvn_mtl_lookahead.inc 723 pass lookahead, hoisting, prediction
nvn_mtl_merge.inc 828 pass merge, deferred passes, fuse
nvn_mtl_indirect.inc 456 indirect draws, transform feedback
nvn_mtl_draw.inc 1,010 draw, dispatch, copies, clears, mtl_exec
nvn_mtl_shot.inc 306 screenshots, texture dumps
nvn_mtl_present.inc 593 the present path

Code moved only in whole top-level blocks. Nothing is renamed, reformatted or reordered, and each part has a one-line header. The only build change: dm/host/Makefile lists nvn/*.inc in GFX_H, so make rebuilds when a part changes. The tests' Makefile, the NSP script and the iOS project need nothing. dm/gfx/README.md lists the parts.

Checked

  • Preprocessed text (clang -E -P, with Mac and with iOS flags): identical to before, except the __LINE__ arguments below.
  • Machine code (otool -tvV, Mac and iOS): identical except 35 res_add_at(..., __LINE__) immediates. These are the site keys of the residency statistics, and they now count from each part's top. They are still unique: two would have collided, and one comment line keeps them apart.
  • Tests: the gfx run list and the host tests give the same results as before.

…sh_pull.py with its decoder dmsh_pull.metal)

A side library of every vertex shader with stage inputs, as <key>_bv is, whose main0 / main0_z have no [[stage_in]] and read their inputs from a per-draw layout block at buffer 16: per stream the base address, stride and divisor, per NVN attribute its state word, the base instance from [[base_instance]] (so indirect draws are right too). dm_fetch decodes the NVN format at run time into the register words Maxwell's fetch gives the shader, and the input takes them with as_type, so the body runs unchanged. A pipeline built with it has no vertex descriptor and serves every vertex layout the pair is drawn with; the hybrid pipelines (next change) draw with it while a draw's own pipeline is built.

The words are bit-identical to Metal's vertex-descriptor fetch for every format nvn_mtl.m vfmt knows and to the host's CPU conversion for the integer-read-as-float formats: unorm / snorm through the unpack builtins (a plain division under fast math is a unit in the last place off for up to half the values), R11G11B10F NaNs canonical as from Metal, divisors with Metal's rule base + (instance - base) / divisor. Positions are [[invariant]] and built with preserved invariance, so a pulling pipeline and the vertex-descriptor one compute the same positions. Transform feedback, geometry capture and layer entries get no variant; shaders without stage inputs need none. The run-time decode costs GPU time: +65 % of a vertex-bound draw with 8 attributes on an M2 Max, about 1 ms per million vertices, so it is meant only to bridge the frames until the draw's own pipeline is built.

The iOS app does not use the variants yet (the Metal 4 path is off on iOS by default), so build_ipa.sh leaves the _bp libraries out of the IPA unless IOS_PULL=1 (pack_ipa.py --skip-suffix).

Chain version 97e2f301eb73 (on main's dec5ee141a9f). Breath of the Wild's full Mac build (25 min, a full retranslation since the code fingerprint changed): 19,592 shaders ok, 8,888 pulling libraries generated (275 MB), none failed, 43 vertex shaders without stage inputs; every existing library is byte-identical to the previous build (19,592 _b.metallib and _b.metal, 6,254 _bf, 1,070 _bv). Other profiles' shaders were not rebuilt.

Tests: t_pull.m (304 checks: the 76 formats vfmt knows, 73 comparisons with Metal's fetch at aligned, 2-byte and stride-1 placements, 24 with the CPU conversion, stride 0 and divisors 1-3 with a base instance), t_pull_inv.m (2,000 random triangles: a depth prepass with one pipeline and depth-equal with the other passes every covered pixel, both ways round) and test_dmsh_pull.py (the generator: entries, ids it adds or keeps, entries left out, shaders declined; compiles for macOS and iOS); pack_ipa.py's --skip-suffix checked by hand. The other graphics tests and the host unit tests give the results they give on main. docs/reference/rendering.md ("Pulling vertex inputs") describes the variant and its cost; AGENTS.md lists the new chain files.
…ts shader pair's pulling pipeline meanwhile, on main's demand-first pipeline builds

On a miss the draw first takes its pipeline without compiling (its base made or in the archive, then a specialization). Failing that it draws with the pair's pulling pipeline (<key>_bp: no vertex descriptor, the streams read through a per-draw layout block at buffer 16, pull_bind), specialized with the draw's colour state, while its own pipeline is built in the background; a later draw takes that one. Both compute the same positions (t_pull_inv), so a draw that switches does not flicker or z-fight. Only a pulling base already made or archived is used; otherwise it is built in the background for the pair's next miss and the draw waits. Merged passes, readable-tile and diagnostic fragments, and layer-writing or transform feedback vertex shaders have no stand-in. DM_PSO_HYBRID=0 turns it off; it needs the Metal 4 path, so it is on by default on the Mac only.

On main's demand-first pipelines (seedds#75): pso_pend_kick stays the speculative admission (at most two running, at most two per prediction, the oldest finished entry reclaimed when the table is full). A draw with a stand-in queues its own pipeline before the prediction runs (pso_pend_demand): outside the speculative limit, on serial queues at utility QoS, one per two performance cores (pp_bg_queue), so a demanded build never waits behind speculation and speculation never waits behind it. The prediction spends its budget only on draws that will have no stand-in, since only those would wait. A draw that would wait for a build still queued makes the pipeline itself at once (pso_pend_take; Breath of the Wild's cold start waited 0.5-0.9 s for one pipeline behind a burst before). The first miss of a submission loads the shader libraries the rest of it binds in parallel (shader_prefetch_rest): 248 libraries in about 210 ms where one by one on the submit thread took about 1 s, in the hybrid and the waiting path alike.

Diagnostics: a "pipelines up to frame" line every 300 frames (submit-thread pipeline, library and prediction time, archive lookups, specializations, base compiles, hybrid draws, background builds, the draws that waited and why), DM_PSO_WAITLOG=1 (each wait over 20 ms with its pair), DM_PSO_PULL_ALL=1 (every draw with a pulling pipeline draws with it), and the longframe line's count of hybrid draws.

Breath of the Wild, Mac (M2 Max), steady state in Zora's Domain: mean GPU p50 over frames 2,400-5,100 was 8.98 ms with the hybrid, 8.98 ms on the Metal 4 path without it, 9.35 ms through the MTLDevice. Cold-start numbers are with the prebuild of the next change.

Tests: t_pull (346 checks, now also the layout block the host fills), t_pull_inv, t_pso_pending (48) and t_pso_archive (32) pass; the other graphics tests and the host unit tests give the results they give on main. docs/development.md ("Hybrid pipelines") and dm/gfx/README.md describe it.
…nd specialization, pulling stand-in with the draw's own pipeline queued first, or a build at once with the bounded prediction)
…he pipeline archive, with the pairs of agl's BAHS program variations (pso_pairs.tsv)

A pulling stand-in is used only when its base is made or archived, so a cold start's draws waited until the prebuild puts the base of every known pair into the archive (pso_prebuild): in the app after the prewarm, on a utility queue on half the performance cores, flushing every 1,000 bases (DM_PSO_PREBUILD=0: off), or as a tool on the Mac (DM_PSO_PREBUILD=tool: build, write, exit; DM_PSO_PREBUILD_DEPTH=zero, DM_PSO_PREBUILD_THREADS=<n>), once per chain version, depth mode and pair list (pso_archive/prebuilt.tsv). The NSP script runs the tool in a --platform mac build (pso_prebuild.log). Files that hold only bases without a vertex layout are named p<seq>.mtl4a; a base with a vertex layout is never looked up in them (each file a lookup misses in costs about 0.06 ms) and compaction leaves them alone.

The pairs: shader_pairs.tsv paired the stages of one BNSH variation and none of the pairs in agl's BAHS shader archives (.sharcb: the agl / gsys / terrain resource packs), and in Breath of the Wild 109 of the 543 pairs drawn on entering Zora's Domain came from those, so they had no stand-in. shader_split.py now reads a BAHS file's binary array (record size, kind: 0 vertex, 1 fragment, 3 compute, the entry bahs_shaders reads) and program array (record size, name length, stage mask, first binary index), and pairs the n-th vertex binary of a program with its n-th fragment binary (bahs_variations); a file whose arrays do not read back gives none. Those pairs go to a new table, pso_pairs.tsv, which only the prebuild reads (DM_PSO_PAIRS: another path): vs_pad keeps reading shader_pairs.tsv, so no shader library, inputs digest or other table changes. Breath of the Wild: 3,012 more pairs, and all 543 pairs drawn are now known; its shader_map / facts / pairs tables split again byte-identical. A profile made before the table existed still packs: the NSP script compares pso_pairs.tsv only where the profile has one, and otherwise keeps it beside the shader package and hands it to the prebuild. Seven other profiles have BAHS files (Odyssey, Wonder, Mario Kart 8 Deluxe, 3D World, Animal Crossing, Captain Toad, Tears of the Kingdom); their tables are made at their next pack.

Breath of the Wild, Mac (M2 Max), Zora's Domain save, empty Metal shader cache, no pso_user.tsv. Prebuild: 15,767 bases, 910 MB in 16 files, 187 s with 7 workers for the first 12,755 and 19 s for the 3,012 more; the files open in 2.2 s cold, 0.25 s from the file cache, and add about 850 MB of footprint. The frame entering the area: 340 ms with pso_pairs.tsv, 830 ms with shader_pairs.tsv alone, 990 ms through the MTLDevice (then frames of 738, 535 and 496 ms); draws that waited: 50 (20 ms), 102 (650 ms) and 512 (3,325 ms). The picture is the same.

Tests: t_pso_archive (41 checks: also a base without a layout flushed into a p file, and a base with a layout not looked up there); the other graphics tests, the host unit tests and test_nsp_mac / progress / chain give the results they give on main. Not run: an iPhone (the prebuild is off there with the Metal 4 path), the NSP script's pack end to end, the other BAHS profiles' splits. docs/development.md, dm/gfx/README.md and dm/games/README.md describe the prebuild and the table; Breath of the Wild's note (dm/games/01007EF00011E000/README.md, Pipelines on a cold start) has its measurements.
… change)

nvn_mtl.m (9,473 lines) keeps its includes, the residency set, deferred release, mtl_init and the memory pools (557 lines with the include lines); the rest moved, in contiguous blocks and in the original order, into 14 files nvn_mtl_<topic>.inc beside it that nvn_mtl.m #includes at the place they were cut from: submit, ubuf, tex, pass, shader, state, pso, args, lookahead, merge, indirect, draw, shot, present. One translation unit, every static still shared; the Makefiles, tests (MTL_T_SRC) and the iOS project compile the same single file. The .inc extension (as nvn_geometry.inc and rt_range_check.inc) keeps the parts out of the Makefiles' nvn/*.m wildcard; dm/host/Makefile's GFX_H already lists nvn/*.inc on main, so make rebuilds when a part changes. Each part opens with a comment saying what it holds; dm/gfx/README.md lists the parts.

Cut again on main with the pipeline series (seedds#123-seedds#125): the parts start at the same top-level blocks as before.

Checked, against the same tree unsplit:
- The parts with their header comments removed, put back in place of the include lines, give the unsplit nvn_mtl.m byte for byte.
- clang -E -P of nvn_mtl.m with the host's flags (Mac) and with iOS flags (arm64-apple-ios18.0, apple-a18): identical text apart from the line number argument of res_add_at (35 sites, __LINE__ now counts from the part's top; the sites stay distinct).
- Object code (otool -tvV of nvn_mtl.m compiled with the Makefile's flags): the same instructions at the same addresses on both platforms; the only differences are those line immediates. Same compiler warnings.
@v0lumehi

Copy link
Copy Markdown
Contributor Author

Parking this for now to keep the open PRs focused on the optimization stack. I'll reopen it if it's needed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant