[lunks]

What and why

Who needs it: Star Fox, whose note lists "a pso_manifest.tsv has not been recorded" open, and any game in bring-up without a recorded prewarm list. Their compute pipelines are built on the device at the first dispatch, at every start when the bundled archive lacks them. Star Fox has 233 compute shaders. No issue reports it.

The host builds every compute pipeline on the device, through the MTLDevice, at its first dispatch or at the prewarm's C rows. Two consequences:

• A game without a recorded prewarm list (a provisional profile, any game in bring-up) has nothing in the app's pipeline archive for its compute shaders (archive.tsv: bases only) and compiles them at their first dispatches.
• A pipeline the bundled archive does not hold (no bundle, as in a headless boot; a shader outside the map; an OS update the bundle's binaries do not survive) is built again at every start, in full whenever the system's shader cache has dropped it: the MTLDevice build goes through no pipeline serializer, so pso_archive never holds one.

A compute pipeline depends on its function alone (no threadgroup size or other option; the dispatch gives the threadgroup size), so it can be compiled without a play session.

1. pso_offline.py gives the archive a compute pipeline descriptor for each compute shader's <key>_b: the prewarm list's C rows first, then every compute row of shader_map.tsv (--shader-map, --manifest, --no-compute), leaving out functions with function constants (the host specializes those). They compile in groups of their own (batches.<arch>/c<index>, 16 each), cached by their inputs and merged with the bases by metal-pack. The host's new cps_new looks <key>_b up in the bundle first and builds it on a miss. The profile's tables are the default, so iOS archives (build_ipa.sh) get them too.
2. On a miss, cps_new looks in the device's own archive files, and after building through the MTLDevice (for the dispatch, as before) compiles the pipeline again through the Metal 4 compiler into the current flush period on a serial utility queue (cps_harvest, arch_capture_cs), so the next start finds it. The capture stays off the dispatch: building the dispatch's pipeline through it took 95 ms for Star Fox's first 5, against 1.2 ms through the MTLDevice. A period with compute pipelines is a plain file, never a p<seq> one; compaction captures them again as it does bases.

The log counts them (compute pipelines so far: N from the archive bundled with the app, M from this device's archive, K built, also in the pipelines up to frame line). Reference entries: Compute pipelines compiled at first use and Compute pipelines outside the bundled archive built at every start.

Checked

• Tests (M5 Pro, macOS 27.0, on these commits over main 056e41f): make -C dm/host/tests GAME=040074A01BF12000 run passes. make -C dm/gfx/tests GAME=040074A01BF12000 run passes (t_pso_bundle 69 checks, t_pso_archive 111 checks, t_pso_warm 99 checks, all 0 failed). t_pso_bundle builds an archive with compute shaders: the map's come from it with nothing built; one with constants and one outside the map are built, and only the latter is captured. t_pso_archive (compute_pipelines): built, captured in the background, written to a plain file, taken from it without a build, captured again at compaction; a function without a descriptor is never looked up.
• Tool tests with the repo's venv (lz4, zstd): test_pso_offline.py (new Compute class and group tests), test_nsp_mac_app.py, test_nsp_incremental.py, test_nsp_nup.py, test_docs.py: 219 tests pass (the three NSP tests skip 32 cases without a zstd module in the system Python and pass with the venv's: 164 tests). docs_symptoms.py --check passes.
• Measurements, all on Star Fox (0400E88025B1A000, v131072, then with a provisional profile; chain ae59da13e481), M5 Pro, macOS 27.0, on our fork with other host changes (among them HMMA/IMMA through TensorOps, whose <key>_bt libraries were kept out of the archive; that code is not in this PR):
  • Offline: 233 compute pipelines beside 3 bases, a 35 MB archive, built in 16 groups in 268 s against 453 s as one metal-tt run (background priority, load averages 19-26 from other jobs); unchanged inputs reuse it in 0.3 s. Two 90 s headless boots to the title with it took all 7 of their compute pipelines from it and built none.
  • Device archive, 90 s headless boots to the title without the bundle: before, 5 built at the first start (1.2 ms) and 9 at the second (2.2 ms), none kept; after, 5 built at the first start and written by the flushes, then 8 from the device's archive at the second (1.4 ms of lookups) and none built. Same frame reached, same [RED] lines.
  • With a warm system shader cache the lookups and the builds cost about the same; the gain is at a cold cache or a first start.
• Not run on this branch: no game boot (no Star Fox or other run of these exact commits), no iOS device, no frame-time comparison in play.
• Devices and OS: M5 Pro, macOS 27.0.
• regress.py check: not run. It reaches every game with compute shaders (the app's archive grows by their pipelines, and the device's archive files by their captures); Bananza and Star Fox would be the first to check.
• Lint: lint_python.py and lint_c.py not run (ruff, pyright and the pinned clang-tidy are not installed here).

Docs

• Both findings are in their docs/reference/shaders.md entries, with lines in Star Fox's note, and python3 dm/tools/docs_symptoms.py was run (the symptom index); docs/development.md describes the compute pipelines in the archive.
• A chain tool changed: not applicable (pso_offline.py is not a chain tool).
• No game files, keys or data extracted from a game in the change or the attachments

[seedds]

Landed as 30fb213, with you as co-author. One fix on top: plan_compute read the libraries through pathlib.Path. With a one-file library (b-<chain>.img, what dmsh_build.py writes now), it left out every compute shader as having no reflection, so the archive held none. It reads through romfs.Path now, as plan does, and test_pipelines_from_a_library_image covers it.

Measured on Ocarina of Time (v131072, M6, warm Metal cache):

• Archive: 4,125 compute pipelines, 480 MB, 204 s.
• With it: all 103 compute pipelines of a route from a save to the village came from the bundle; none were built.
• Without it: the first start's flushes wrote 88 compute pipelines into the device's archive, and the second start took 88 from it.

The cold-cache gain is #1522's measurement (195 s of submit-thread pipelines down to 0.9 s), cited in the docs. Return of the Obra Dinn quick regress: PASS. Its route dispatches no compute, so it only shows nothing else changed.