[stan69b]

Batch OoT-30, session A (pipelines compiled on the phone).

Why

The archive pso_offline.py bundles in an IPA holds the shader pairs' pulling bases and the compute pipelines. It holds no base with a vertex layout (a prewarm list's R row) and no native task / mesh pipeline (an M row). Both depend on what only the host knows: the descriptor pso_desc makes from a row's pso_skey and the shader's reflection. So an iPhone builds every listed one itself, at the prepare step of its first start, and keeps them in its own archive (pso_archive/).

An OS update makes Metal refuse that archive. On an iPhone 17 after iOS 27.2.1, every start logged 121 lines of [RED] pipeline archive file … not usable (deployment target for architecture applegpu_g18p … is not compatible with current OS). The bundled archive, made for the OS's major version, still opened.

In the owner's 30-minute play (pipelines up to frame lines), windows that compiled bases ran at 12-22 fps, for example bases compiled 17 / 12872 ms in one window and 4 / 45122 ms in Castle Town.

PR #2353 made these files for the Mac app (the host's prebuild tool in its bundle form, then metal-tt for other GPUs). The IPA did not get them.

The change

A-1: pso_offline.py --prewarm-host <Mac dmhost>

• Host stage. Runs the Mac host as the prebuild tool's bundle form (DM_PSO_PREBUILD=tool, DM_PSO_PREBUILD_OUT) on the iOS libraries the app ships. A Mac's Metal loads and compiles a library built for iOS; I checked this with Ocarina of Time's iOS libraries on macOS 27.2. The tool gets the profile's tables less the pair lists (the pairs are the archive's, so the tool would otherwise build them all) and a list of the R and M rows alone (the C rows' compute pipelines are in the archive already). It writes one file per flush period, its index (.keys) and its pipelines script.
• Compile stage. Compiles each script with metal-tt for every --gpu as <arch>-prewarm-<NN>.mtl4a, beside the period's index. A device computes the same keys. Groups of --batch-size are merged with metal-pack. A pipeline metal-tt refuses is left out by the halving compile_isolating already did, now shared as isolate().
• Opening. The host opens the files with the archive, through the existing pso_bundle_open_prewarm. No host change.
• Caching and failure. Both stages are cached in the work folder: the host run by its inputs, each compiled script by its bytes and the compiler's settings. A failure prints a red line and the app goes without these files, as before.
• build_ipa.sh. Passes DM_PSO_HOST, else dm/host/dmhost when its last build was for this game (made current first). DM_PSO_HOST=none makes none.
• NSP script. The library search by SHA-256 it had for the Mac app's other GPUs moved into pso_offline.py (script_libraries), and the NSP script calls it.
• Seed list. Ocarina of Time's pso_manifest.tsv gets 10,415 rows (5,249 S, 4,447 R, 719 C) from the iPhone's own pso_user.tsv.
  • These are the rows the seed list lacked once both lists' keys were parsed with pso_skey_parse and written again in the current layout (the phone's list held two layouts).
  • Every shader key is in shader_map.tsv with its stage.
  • They go before the list's last block, away from Ocarina of Time's seed list gets the 98 native task / mesh pipelines an iPhone 17 built at their first draw #2642's two hunks: git merge-file of the two versions gives no conflict.
  • The pair archive's plan is unchanged by them (33,365 bases, 4,125 compute pipelines).

A-3: the M rows

metal-tt takes the mesh pipeline descriptors the tool writes, so the M rows go in too. This is #2642's open item.

Checked

• A pilot of 60 R and 20 M rows from Ocarina of Time's list, through both stages for applegpu_g18p (iOS 27.0): 42 bases and 20 mesh pipelines, one file of 6 MB in 8 s, with a complete index of 62 keys.
• Tests:
  • test_pso_offline.py: 60 tests. New: Prewarm with a fake host and metal-tt (the tool's environment and tables, the files and indexes per GPU, reuse with nothing run, a GPU dropped, new rows rerunning the host alone, groups merged with a pipeline left out, a failed or missing host leaving the archive). Also a real metal-tt compile of a mesh pipeline descriptor for applegpu_g18p, and build_ipa.sh passing DM_PSO_HOST.
  • Also run: test_nsp_mac_app.py (70), test_docs, test_env_switches, test_lint_python. lint_python --against upstream/main finds nothing new in these files.
• regress.py: not run. The reach is the IPA build tool alone: no host, chain or runtime code changes, and the regress interface check uses pso_offline.plan, which is unchanged.

Phone (iPhone 17, iOS 27.2.1)

Pending. The phone build (the phone tree plus #2353's host part and #2539) and its first start after install will be added here.