Option to allow migrating rodata between segments (#463)

* start working on it

* fixes

* docs and such

* Fix pairing recommendations

* missed this

Author: AngheloAlf

CHANGELOG.md

@@ -1,6 +1,12 @@
 # splat Release Notes
 
+### 0.35.0
+
+* Add `pair_segment` option to segments:
+  * Allows pairing the sections of two different segments together, making cross-segment rodata migration possible.
+
 ### 0.34.3
+
 * `asm_emit_size_directive` now also affects generated assembly from `textbin`, `databin`, and `rodatabin` segments.
 
 ### 0.34.2

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.34.3,<1.0.0
+splat64[mips]>=0.35.0,<1.0.0
 ```
 
 ### Optional dependencies

docs/Segments.md

@@ -583,3 +583,36 @@ Defaults to the global option.
     vram: 0x80000460
     suggestion_rodata_section_start: False
 ```
+
+### `pair_segment`
+
+Allows pairing sections of two different segments together.
+
+The main purpose of this is to make the automatic rodata-to-function migration possible, since the default behavior only allows pairing different sections of the same name under the same segment only. This kind of ROM layout can be seen on some TLB games from N64 projects.
+
+This value expects the name of the other segment that should be paired to the current one. Only one of the two to-be-paired segments should have this attribute.
+
+**Example:**
+
+```yaml
+  - name:  init
+    type:  code
+    start: 0x00001000
+    vram:  0x10001000
+    pair_segment: init_data # This is the name of the following segment.
+    subsegments:
+      # -- snip --
+      - [0x15550, c, libultra/audio/init_15550]
+      # -- snip --
+
+  - name:  init_data
+    type:  code
+    start: 0x000290D0
+    vram:  0x800290D0
+    bss_size: 0x16690
+    # Note there's no `pair_segment: init` on this segment.
+    subsegments:
+      # -- snip --
+      - [0x2C6B0, .rodata, libultra/audio/init_15550]
+      # -- snip --
+```

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "splat64"
 # Should be synced with src/splat/__init__.py
-version = "0.34.3"
+version = "0.35.0"
 description = "A binary splitting tool to assist with decompilation and modding projects"
 readme = "README.md"
 license = {file = "LICENSE"}

src/splat/__init__.py

@@ -1,7 +1,7 @@
 __package_name__ = __name__
 
 # Should be synced with pyproject.toml
-__version__ = "0.34.3"
+__version__ = "0.35.0"
 __author__ = "ethteck"
 
 from . import util as util

src/splat/scripts/split.py

@@ -19,6 +19,7 @@
     get_segment_vram_end_symbol_name,
 )
 from ..segtypes.segment import Segment
+from ..segtypes.common.group import CommonSegGroup
 from ..util import conf, log, options, palettes, symbols, relocs
 
 linker_writer: LinkerWriter
@@ -38,6 +39,9 @@ def initialize_segments(config_segments: Union[dict, list]) -> List[Segment]:
     segments_by_name: Dict[str, Segment] = {}
     ret: List[Segment] = []
 
+    # Cross segment pairing can be quite expensive, so we try to avoid it if the user haven't requested it.
+    do_cross_segment_pairing = False
+
     last_rom_end = 0
 
     for i, seg_yaml in enumerate(config_segments):
@@ -80,6 +84,9 @@ def initialize_segments(config_segments: Union[dict, list]) -> List[Segment]:
 
             segments_by_name[segment.name] = segment
 
+        if segment.pair_segment_name is not None:
+            do_cross_segment_pairing = True
+
         ret.append(segment)
         if (
             isinstance(segment.rom_start, int)
@@ -112,6 +119,50 @@ def initialize_segments(config_segments: Union[dict, list]) -> List[Segment]:
             "Last segment in config cannot be a pad segment; see https://github.com/ethteck/splat/wiki/Segments#pad"
         )
 
+    if do_cross_segment_pairing:
+        # Do the cross segment pairing
+        for seg in ret:
+            if seg.pair_segment_name is not None:
+                found = False
+                for other_seg in ret:
+                    if seg == other_seg:
+                        continue
+                    if seg.pair_segment_name == other_seg.name and isinstance(
+                        other_seg, CommonSegGroup
+                    ):
+                        # We found the other segment specified by `pair_segment`
+
+                        if other_seg.pair_segment_name is not None:
+                            log.error(
+                                f"Both segments '{seg.name}' and '{other_seg.name}' have a `pair_segment` value, when only at most one of the cross-paired segments can have this attribute."
+                            )
+
+                        # Not user error, hopefully...
+                        assert (
+                            seg.paired_segment is None
+                        ), f"Somehow '{seg.name}' was already paired so something else? It is paired to '{seg.paired_segment.name}' instead of {other_seg.name}"
+                        assert (
+                            other_seg.paired_segment is None
+                        ), f"Somehow '{other_seg.name}' was already paired so something else? It is paired to '{other_seg.paired_segment.name}' instead of {seg.name}"
+
+                        found = True
+                        # Pair them
+                        seg.paired_segment = other_seg
+                        other_seg.paired_segment = seg
+
+                        if isinstance(seg, CommonSegGroup) and isinstance(
+                            other_seg, CommonSegGroup
+                        ):
+                            # Pair the subsegments
+                            seg.pair_subsegments_to_other_segment(other_seg)
+
+                        break
+
+                if not found:
+                    log.error(
+                        f"Segment '{seg.pair_segment_name}' not found.\n    It is referenced by segment '{seg.name}', because of the `pair_segment` attribute."
+                    )
+
     return ret
 
 

src/splat/segtypes/common/group.py

@@ -168,6 +168,10 @@ def get_subsegment_for_ram(self, addr: int) -> Optional[Segment]:
         for sub in self.subsegments:
             if sub.contains_vram(addr):
                 return sub
+        if isinstance(self.paired_segment, CommonSegGroup):
+            for sub in self.paired_segment.subsegments:
+                if sub.contains_vram(addr):
+                    return sub
         return None
 
     def get_next_subsegment_for_ram(
@@ -187,3 +191,22 @@ def get_next_subsegment_for_ram(
             if sub.vram_start > addr:
                 return sub
         return None
+
+    def pair_subsegments_to_other_segment(
+        self,
+        other_segment: "CommonSegGroup",
+    ):
+        # Pair cousins with the same name
+        for segment in self.subsegments:
+            for sibling in other_segment.subsegments:
+                if segment.name == sibling.name:
+                    # Make them reference each other
+                    segment.siblings[sibling.get_linker_section_linksection()] = sibling
+                    sibling.siblings[segment.get_linker_section_linksection()] = segment
+
+                    if segment.is_text():
+                        sibling.sibling = segment
+                    elif sibling.is_text():
+                        segment.sibling = sibling
+
+                    break

src/splat/segtypes/segment.py

@@ -274,6 +274,12 @@ def parse_suggestion_rodata_section_start(
                 return suggestion_rodata_section_start
         return None
 
+    @staticmethod
+    def parse_pair_segment(yaml: Union[dict, list]) -> Optional[str]:
+        if isinstance(yaml, dict) and "pair_segment" in yaml:
+            return yaml["pair_segment"]
+        return None
+
     def __init__(
         self,
         rom_start: Optional[int],
@@ -319,6 +325,9 @@ def __init__(
         self.parent: Optional[Segment] = None
         self.sibling: Optional[Segment] = None
         self.siblings: Dict[str, Segment] = {}
+        self.pair_segment_name: Optional[str] = self.parse_pair_segment(yaml)
+        self.paired_segment: Optional[Segment] = None
+
         self.file_path: Optional[Path] = None
 
         self.args: List[str] = args