Document 1.4.3 as a second build target: AGENTS.md commands, backlog item 39 with what is open, architecture

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Valiantsin DzerakhandClaude Opus 5.5 committed 2026-10-26 19:30:24 +03:00
1 parent b245b07722
commit 20ee7152ad
3 files changed
+17 -15

No files matched your search

+2 -1
View File
@@ -43,7 +43,8 @@ Setup and verify commands: [docs/toolchain-windows.md](docs/toolchain-windows.md
- `tests\diff\atomic.py`: exclusive load/store sequences and ARMv8.1 atomics; needs no game files.
- `tests\diff\func.py`: whole leaf functions as the generator emits them, loops and jump tables included.
- `tests\excl_mt.py`: the exclusive monitor helpers of `cpu.h` under contention and ABA, on several threads; needs no game files.
- Game code build (`.venv`): `recomp\gen.py --exefs build\extracted\v121\exefs --out generated\v121 --patches recomp\patches-v121.txt` writes the C (about 15 s). The patch table holds the 60 fps and real-time frame step code patches, switchable at run time (`recomp/patches.py`); `.venv-py314\Scripts\python tools\make_romfs_patches.py` writes their RomFS half to `build\v121\romfs-patches`. `tools\build_game.py` compiles and links `build\v121\totk.exe` with Ninja (about 200 s clean, incremental after). `recomp/layout.py` alone decides module bases. Jump tables are resolved by `recomp/jumptables.py`; after changing it, `tests\jumptables_check.py` must report 0 disagreements with its Unicorn oracle.
- Game code build (`.venv`): `recomp\gen.py --exefs build\extracted\v121\exefs --out generated\v121 --patches recomp\patches-v121.txt` writes the C (about 15 s). The patch table holds the 60 fps and real-time frame step code patches, switchable at run time (`recomp/patches.py`); `.venv-py314\Scripts\python tools\make_romfs_patches.py` writes their RomFS half to `build\v121\romfs-patches`. `tools\build_game.py` compiles and links `build\v121\totk.exe` with Ninja (about 200 s clean, incremental after). `recomp/layout.py` alone decides module bases. Jump tables are resolved by `recomp/jumptables.py`; after changing it, `tests\jumptables_check.py` must report 0 disagreements with its Unicorn oracle (on 1.4.3 too: `--exefs build\extracted\v143\exefs`).
- Game version 1.4.3: the same commands with `v143` (`--patches recomp\patches-v143.txt`, `build_game.py --version v143`, `make_romfs_patches.py --version v143`). Its builds default to `build\profile-v143`; `run_game.py` runs it on copies of the 1.2.1 save backups.
- Shader census (`.venv-py314`): `tools\shader_census.py --version v121 [--translate]` extracts every Maxwell shader to `build/v121/shaders/` and runs it through `build\xlate\totk_xlate.exe` and `spirv-val`; failure groups go to `failures.txt`. `tools\xlate_smoke.py` checks the translator alone, without game files.
- Shader preparation (`.venv-py314`, once per build dir and translator): `tools\prepare_shaders.py build\v121` translates the variants of the MacNativeGames shared shader list (read from `refs/` at run time) into the build's shader cache and builds their stage libraries into the driver cache (`totk.exe --prepare-shaders`, about 5 min, 1.3 GB); play then translates and compiles only variants the list lacks.
- Open work with its evidence: [docs/backlog.md](docs/backlog.md).
+1 -1
View File
@@ -24,7 +24,7 @@ MacNativeGames cannot run on x86-64 as is: its CPU path executes ARM64 code nati
- ExeFS and RomFS extraction: MacNativeGames' Python extractor (Python 3.14 for `compression.zstd`, `.venv-py314`).
- Update merging: hactool at `1d64a83`, with MacNativeGames' BKTR patches (`toolchain/hactool`).
- Verification: MacNativeGames' `expected-v*.json` hashes of ExeFS, RomFS and fonts.
- Primary version: 1.2.1, the update most players have. MacNativeGames supports it with the same build path as the others. 1.0.0, 1.1.2 and 1.2.1 share `sdk`, `subsdk0` and `rtld` byte for byte, so the lifted SDK modules and the host's SDK boundary serve all three; only `main` differs. 1.4.3 replaced all three modules (new SDK 20.5.22, RELR relocations, audio renderer REV15) and is a separate target; work on it has started on a branch and is not merged.
- Primary version: 1.2.1, the update most players have. MacNativeGames supports it with the same build path as the others. 1.0.0, 1.1.2 and 1.2.1 share `sdk`, `subsdk0` and `rtld` byte for byte, so the lifted SDK modules and the host's SDK boundary serve all three; only `main` differs. 1.4.3 replaced all three modules (new SDK 20.5.22, RELR relocations, audio renderer REV15) and is a second target on the same build path: `--version v143`, `recomp/patches-v143.txt` (state in backlog item 39).
- Windows driver: `tools/extract.py` runs the vendored extractors (`tools/vendor/macnativegames/`) and identifies the update by the SHA-256 of its `main`. hactool has no Darwin `funopen` here, so the base Program NCA is copied out of the NSP before the BKTR merge (about 17 GB of temporary space).
### 2. CPU: lift ARM64 to C
+14 -13
View File
@@ -173,19 +173,20 @@ Each platform item gets a written design first, agreed with the maintainer.
every render target ourselves); MacNativeGames has neither. The software keyboard could move onto
SavageWindRecomp's `osk.mm`.
39. **Game version 1.4.3** (branch `task/v143`, paused). The 1.4.3 files extract and verify, and the generator runs on
them unchanged. Estimate: one day to the title screen, two to three to play at 60 fps. Steps:
1. `stg` no-op lift, DT_RELR in `recomp/nso.py` and `runtime/loader.c`, symbol count from DT_GNU_HASH for `sdk`
and `subsdk0`.
2. Jump tables: 26 disagreements and 83 unresolved sites down to 0 unexplained, with 1.2.1 still at 0.
3. Tools take a version instead of `v121`; re-measure the `--probe-loader` table (`loader.c` `expect[]`) and
`boot.c` `expected_inits`; new boot anchors (`boot.c` `CHECKPOINT_RET`, `NVN_RET`).
4. RELRO (`nn::ro::ProtectRelro`) and the new SDK imports; run to the title screen.
5. `recomp/patches-v143.txt` from MacNativeGames `game_patches_v143.c` (fps60, bounce, cloth; the real-time step
rewritten for the `sys+0x1da` coefficient); the player position of `frame_rate.c` `player_pos`;
`make_romfs_patches.py --version` (`Common.Product.140`).
6. Audio REV15 is mostly in place (`audren.c`, `audio_mixer.c`): fix the REV11 self-test, check the override
signatures (biquad, font decode), and listen for render differences in play.
39. **Game version 1.4.3** (branch `task/v143`). Builds, boots and plays: the field save (a 1.2.1 save, converted on
load) runs at 60 fps with game speed 1.000, REV15 audio without underruns, 0 unimplemented NVN calls, 0 validation
errors; every probe passes on 1.4.3 and on 1.2.1; the jump-table check reports 0 disagreements on both; the
installer takes either update. Open:
1. Shader preparation: the MacNativeGames list at our pin has 134 keys of 1.4.3 (its compiler changed every
binary), so 1.4.3 translates nearly every shader on first sight in play. A list recorded from our own 1.4.3
play, or a newer pin, would fill it.
2. Not played beyond the field save and the opening cutscene: combat, abilities, cutscenes, menus, saving; whether
1.2.1 loads saves that 1.4.3 wrote.
3. The installer end-to-end test (`tests/installer_e2e.py`) runs only on 1.2.1.
4. MacNativeGames' 1.4.3 output, render and fixed resolution patches (`game_patches_v143.c`) are not ported; 1.2.1
has none of them either.
5. The opening cutscene (Zelda under Hyrule Castle) shows hard light bands on 1.4.3 and on 1.2.1 alike; whether
that is the game's look or ours is not checked.
40. **Community ExeFS patches** (`.ips`, `.pchtxt` for 1.2.1): apply them through the generator's patch table
(`recomp/patches.py`). RomFS mods already load (`romfs.c`, `TOTK_ROMFS_MODS`). Code-module mods (exlaunch
`subsdk9`) need porting one by one.