From 01500c171ef75fd2630fd46d881bde45320c294b Mon Sep 17 00:00:00 2001 From: Luke Street Date: Sun, 1 Mar 2026 16:26:36 -0700 Subject: [PATCH] Update all tools & update dtk docs --- config/GAMEID/config.example.yml | 29 +++++++++++++++++++++++++++++ configure.py | 8 ++++---- docs/getting_started.md | 6 +++++- docs/splits.md | 16 ++++++++++++++++ docs/symbols.md | 2 +- 5 files changed, 55 insertions(+), 6 deletions(-) diff --git a/config/GAMEID/config.example.yml b/config/GAMEID/config.example.yml index 7b38b79..9f79b4c 100644 --- a/config/GAMEID/config.example.yml +++ b/config/GAMEID/config.example.yml @@ -92,6 +92,10 @@ fill_gaps: true # Individual symbols can be excluded using `noexport` in the symbols file. export_all: true +# (optional) By default, local symbols referenced by other translation units +# are promoted to global scope. Set to false to disable this behavior. +globalize_symbols: true + # (optional) Custom template for `ldscript.lcf`. Avoid unless necessary. # See https://github.com/encounter/decomp-toolkit/blob/main/assets/ldscript.lcf ldscript_template: config/GAMEID/module/ldscript.tpl @@ -107,6 +111,13 @@ ldscript_template: config/GAMEID/module/ldscript.tpl # configure.py, in order to exactly match the original DOL. clean_extab: false +# (optional) Skip control flow analysis for specific address ranges. +# Useful for problematic code regions where analysis gets stuck. +# Ensure no `function` symbols exist in symbols.txt for the affected range. +skip_cfa_ranges: +- start: .text:0x80001234 + end: .text:0x80002000 + # (optional) Configuration for modules. modules: @@ -155,6 +166,10 @@ extract: # `SomeSymbol!.section:0x80001234` symbol: SomeSymbol + # (optional) Rename the symbol when extracting. + # Useful for symbols with generated suffixes, e.g. `test$1234` -> `test`. + rename: SomeSymbol + # (optional) The path to extract raw binary data to. # Path is relative to `build/GAMEID/bin`. binary: Lib/SomeSymbol.bin @@ -164,6 +179,20 @@ extract: # Path is relative to `build/GAMEID/include`. header: Lib/SomeSymbol.inc + # (optional) Controls the format of the extracted header. + # "symbol" (default) - Emits a C array named after the symbol. + # "raw" - Emits a raw byte array without symbol naming. + # "none" - Do not generate a header. + header_type: symbol + + # (optional) The path to extract relocation info as JSON. + # Path is relative to `build/GAMEID/bin`. + relocations: Lib/SomeSymbol_relocs.json + + # (optional) Passthrough fields for external asset processing tools. + custom_type: texture + custom_data: { format: RGBA8 } + # (optional) Block relocations from or to specific addresses. # For modules, this goes in the module's configuration above. block_relocations: diff --git a/configure.py b/configure.py index 0e67915..ba24603 100755 --- a/configure.py +++ b/configure.py @@ -156,12 +156,12 @@ if not config.non_matching: config.asm_dir = None # Tool versions -config.binutils_tag = "2.42-1" +config.binutils_tag = "2.42-2" config.compilers_tag = "20251118" -config.dtk_tag = "v1.8.0" -config.objdiff_tag = "v3.5.1" +config.dtk_tag = "v1.8.1" +config.objdiff_tag = "v3.6.1" config.sjiswrap_tag = "v1.2.2" -config.wibo_tag = "1.0.0" +config.wibo_tag = "1.0.2" # Project config.config_path = Path("config") / config.version / "config.yml" diff --git a/docs/getting_started.md b/docs/getting_started.md index 27f9612..6dab5bd 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -6,7 +6,11 @@ See [Dependencies](dependencies.md) first. 2. Rename `orig/GAMEID` to the game's ID. (For example, `GLZE01` for _The Legend of Zelda: The Wind Waker_.) -3. Extract your game to `orig/[GAMEID]`. In Dolphin, use "Extract Entire Disc" for GameCube games, or use "Data Partition" -> "Extract Entire Partition" for Wii games. +3. Place your game files in `orig/[GAMEID]`. There are two options: + + - **Disc image (recommended):** Place the disc image (ISO, GCM, RVZ, WBFS, CISO, GCZ, NFS, TGC, or WAD) directly in `orig/[GAMEID]`. When `object_base` is set in `config.yml`, decomp-toolkit will automatically read files from the disc image. Objects will be extracted to the filesystem on first build, so the disc image can be deleted afterward to save space. + + - **Extracted files:** In Dolphin, use "Extract Entire Disc" for GameCube games, or use "Data Partition" -> "Extract Entire Partition" for Wii games. 4. Rename `config/GAMEID` to the game's ID and modify `config/[GAMEID]/config.yml` appropriately, using [`config.example.yml`](/config/GAMEID/config.example.yml) as a reference. If the game doesn't use RELs, the `modules` list in `config.yml` can be removed. diff --git a/docs/splits.md b/docs/splits.md index a05eaa7..ab69e1f 100644 --- a/docs/splits.md +++ b/docs/splits.md @@ -53,3 +53,19 @@ path/to/file.cpp: [file attributes] - `rename:` Writes this section under a different name when generating the split object. Used for `.ctors$10`, etc. - `common` Only valid for `.bss`. See [Common BSS](common_bss.md). - `skip` Skips this data when writing the object file. Used for ignoring data that's linker-generated. + +#### `Sections:` header (REL modules only) + +REL modules can specify fixed virtual addresses for sections using a `Sections:` block at the top of the file. This is useful for projects where REL modules load at known addresses, allowing symbols and splits to use absolute addresses instead of section-relative ones. + +```yaml +Sections: + .text type:code vaddr:0x805A1234 + .data type:data vaddr:0x805B0000 + +path/to/file.cpp: + .text start:0x805A1234 end:0x805A2000 +``` + +- `type:` The section type. `code` or `data`. +- `vaddr:` The fixed virtual address of the section. When set, split and symbol addresses are written as absolute addresses. diff --git a/docs/symbols.md b/docs/symbols.md index ad56a31..11e1c70 100644 --- a/docs/symbols.md +++ b/docs/symbols.md @@ -30,7 +30,7 @@ All attributes are optional, and are separated by spaces. - `size:` The size of the symbol. - `scope:` The symbol's visibility. `global` (default), `local` or `weak`. - `align:` The symbol's alignment. -- `data:` The data type used when writing disassembly. `byte`, `2byte`, `4byte`, `8byte`, `float`, `double`, `int`, `short`, `string`, `wstring`, `string_table`, or `wstring_table`. +- `data:` The data type used when writing disassembly. `byte`, `2byte`, `4byte`, `8byte`, `float`, `double`, `int`, `short`, `string`, `wstring`, `string_table`, `wstring_table`, `sjis`, or `sjis_table`. - `hidden` Marked as "hidden" in the generated object. (Only used for extab) - `force_active` Marked as ["exported"](comment_section.md) in the generated object, and added to `FORCEACTIVE` in the generated `ldscript.lcf`. Prevents the symbol from being deadstripped. - `noreloc` Prevents the _contents_ of the symbol from being interpreted as addresses. Used for objects containing data that look like pointers, but aren't.