diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e43771f..07dccdce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # splat Release Notes +### 0.24.5 + +* New `use_src_path` option for incbins segments. + * Allows to make the generated assembly files relative to the `src_path` directory instead of the default `data_path`. + ### 0.24.4 * New yaml option: `matchings_path` diff --git a/README.md b/README.md index 920f7a18..3208841a 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ The brackets corresponds to the optional dependencies to install while installin If you use a `requirements.txt` file in your repository, then you can add this library with the following line: ```txt -splat64[mips]>=0.24.4,<1.0.0 +splat64[mips]>=0.24.5,<1.0.0 ``` ### Optional dependencies diff --git a/docs/Segments.md b/docs/Segments.md index 7c9ad99a..2b4b7f1b 100644 --- a/docs/Segments.md +++ b/docs/Segments.md @@ -275,6 +275,31 @@ While this kind of segment can be represented by other segment types ([`asm`](#a - [0x00B250, pad, nops_00B250] ``` +## incbins + +incbin segments correpond to a family of segments used for extracting binary blobs. + +Their main advantage over the [`bin`](#bin) segment is the incbins allows to specify a specific section type instead of defaulting to simply `.data`. This is done by generating an assembly file that uses the `.incbin` asm directive to include the binary blob. + +Generating assembly files enables better customization of these binaries, like allowing different sections or to define a symbol for the binary blob. + +If a known symbol (via a symbol_addrs file) matches the vram of a incbin segment then it will be emitted accordingly at the top. If the symbol contains a [`name_end`](Adding-Symbols.md#name_end) property then it will be emitted after the `.incbin` (useful for Nintendo64's RSP ucodes). + +Curretly there are 3 types of incbins, `textbin`, `databin` and `rodatabin`, which are intended for binary blobs of `.text`, `.data` and `.rodata` sections. + +If a `textbin` section has a corresponding `databin` and/or `rodatabin` section with the same name then those will be included in the same generated assembly file. + +By default the generated assembly file will be written relative to the configured [`data_path`](docs/Configuration.md#data_path). The per segment `use_src_path` option allows to tell splat that a given incbin should be relative to the [`src_path`](docs/Configuration.md#src_path) instead. This behavior can be useful to allow committing those assembly files to the repo since splat will not override them if they already exist, and still extract the binary blobs. + +```yaml +- { start: 0x06C4B0, type: textbin, use_src_path: True, name: rsp/rspboot } +- [0x06C580, textbin, rsp/aspMain] + +# ... + +- [0x093D60, databin, rsp/aspMain] +``` + ## PS2 exclusive segments ### `lit4` diff --git a/pyproject.toml b/pyproject.toml index 6e3eb018..01b5615c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "splat64" # Should be synced with src/splat/__init__.py -version = "0.24.4" +version = "0.24.5" description = "A binary splitting tool to assist with decompilation and modding projects" readme = "README.md" license = {file = "LICENSE"} diff --git a/src/splat/__init__.py b/src/splat/__init__.py index 804df3d7..e7fd2137 100644 --- a/src/splat/__init__.py +++ b/src/splat/__init__.py @@ -3,7 +3,7 @@ __package_name__ = __name__ # Should be synced with pyproject.toml -__version__ = "0.24.4" +__version__ = "0.24.5" __author__ = "ethteck" from . import util as util diff --git a/src/splat/segtypes/common/textbin.py b/src/splat/segtypes/common/textbin.py index 1be9d52d..610e0c19 100644 --- a/src/splat/segtypes/common/textbin.py +++ b/src/splat/segtypes/common/textbin.py @@ -7,6 +7,29 @@ class CommonSegTextbin(CommonSegment): + def __init__( + self, + rom_start: Optional[int], + rom_end: Optional[int], + type: str, + name: str, + vram_start: Optional[int], + args: list, + yaml, + ): + super().__init__( + rom_start, + rom_end, + type, + name, + vram_start, + args=args, + yaml=yaml, + ) + self.use_src_path: bool = isinstance(yaml, dict) and yaml.get( + "use_src_path", False + ) + @staticmethod def is_text() -> bool: return True @@ -18,6 +41,9 @@ def get_section_flags(self) -> Optional[str]: return "ax" def out_path(self) -> Optional[Path]: + if self.use_src_path: + return options.opts.src_path / self.dir / f"{self.name}.s" + return options.opts.data_path / self.dir / f"{self.name}.s" def bin_path(self) -> Path: