sort_segments_by_vram_dependency (#512)

* add sort_segements_by_vram_class_dependency

* fix spelling

* formatting

* add docs entry

* additional docs clarification

Author: z64a

docs/Configuration.md

@@ -526,6 +526,10 @@ Generates a discard section like this:
 
 Determines whether to add wildcards for section linking in the linker script (.rodata* for example)
 
+### ld_sort_segments_by_vram_class_dependency
+
+Ensures segments of vram classes with dependencies (`vram_symbol` / `follows_classes`) are written to the linker script AFTER the segments they depend on. This is intended to preserve vram class ordering for shifted builds (e.g., mods) and is not expected to produce a matching build. Disable this when a matching build is desired.
+
 ### ld_use_symbolic_vram_addresses
 
 Determines whether to use `follows_vram` (segment option) and `vram_symbol` / `follows_classes` (vram_class options) to calculate vram addresses in the linker script.

src/splat/scripts/split.py

@@ -6,6 +6,8 @@
 from typing import Any, Dict, List, Optional, Set, Tuple, Union
 from pathlib import Path
 
+from collections import defaultdict, deque
+
 from .. import __package_name__, __version__
 from ..disassembler import disassembler_instance
 from ..util import cache_handler, progress_bar, vram_classes, statistics, file_presets
@@ -222,6 +224,47 @@ def calc_segment_dependences(
     return vram_class_to_follows_segments
 
 
+def sort_segments_by_vram_class_dependency(
+    all_segments: List[Segment],
+) -> List[Segment]:
+    # map all "_VRAM_END" strings to segments
+    end_sym_to_seg: Dict[str, Segment] = {}
+    for seg in all_segments:
+        end_sym_to_seg[get_segment_vram_end_symbol_name(seg)] = seg
+
+    # build dependency graph: A -> B means "A must come before B"
+    graph: Dict[Segment, List[Segment]] = defaultdict(list)
+    indeg: Dict[Segment, int] = {seg: 0 for seg in all_segments}
+
+    for seg in all_segments:
+        sym = seg.vram_symbol
+        if sym is None:
+            continue
+        dep = end_sym_to_seg.get(sym)
+        if dep is None or dep is seg:
+            continue
+        graph[dep].append(seg)
+        indeg[seg] += 1
+
+    # stable topo sort with queue seeded in original order
+    q = deque([seg for seg in all_segments if indeg[seg] == 0])
+    out: List[Segment] = []
+
+    while q:
+        n = q.popleft()
+        out.append(n)
+        for m in graph.get(n, []):
+            indeg[m] -= 1
+            if indeg[m] == 0:
+                q.append(m)
+
+    assert len(out) == len(all_segments), (
+        "Encountered cyclic dependency when reordering segments by vram class."
+    )
+
+    return out
+
+
 def read_target_binary() -> bytes:
     rom_bytes = options.opts.target_path.read_bytes()
 
@@ -317,6 +360,9 @@ def do_split(
 
 
 def write_linker_script(all_segments: List[Segment]) -> LinkerWriter:
+    if options.opts.ld_sort_segments_by_vram_class_dependency:
+        all_segments = sort_segments_by_vram_class_dependency(all_segments)
+
     vram_class_dependencies = calc_segment_dependences(all_segments)
     vram_classes_to_search = set(vram_class_dependencies.keys())
 

src/splat/util/options.py

@@ -127,6 +127,8 @@ class SplatOpts:
     # `vram_symbol` / `follows_classes` (vram_class options) to calculate vram addresses in the linker script.
     # If disabled, this uses the plain integer values for vram addresses defined in the yaml.
     ld_use_symbolic_vram_addresses: bool
+    # Ensures segments of vram classes with dependencies (`vram_symbol` / `follows_classes`) are written to the linker script AFTER the segments they depend on.
+    ld_sort_segments_by_vram_class_dependency: bool
     # Change linker script generation to allow partially linking segments. Requires both `ld_partial_scripts_path` and `ld_partial_build_segments_path` to be set.
     ld_partial_linking: bool
     # Folder were each intermediary linker script will be written to.
@@ -512,6 +514,9 @@ def parse_include_asm_macro_style() -> Literal["default", "maspsx_hack"]:
         ld_sections_allowlist=p.parse_opt("ld_sections_allowlist", list, []),
         ld_sections_denylist=p.parse_opt("ld_sections_denylist", list, []),
         ld_wildcard_sections=p.parse_opt("ld_wildcard_sections", bool, False),
+        ld_sort_segments_by_vram_class_dependency=p.parse_opt(
+            "ld_sort_segments_by_vram_class_dependency", bool, False
+        ),
         ld_use_symbolic_vram_addresses=p.parse_opt(
             "ld_use_symbolic_vram_addresses", bool, True
         ),