How gsret/goldensun works
Overall Project Type and Purpose
• This is a disassembly/reverse-engineering project for Golden Sun. Its core goal is to “rebuild” the game ROM from disassembled source code and overlay modules.
• The project uses a structured file tree to organize many assembly source files, overlays (which refer to dynamic code/data modules in the ROM), include definitions, utility tools, and a build system (Makefile) that handles linking, verification (through SHA1 checks), and generation of the output ROM.
Main Components
• Build Infrastructure:
• Makefile: Controls the overall build process.
• Toolchain Requirements: GNU make, ARM binutils, C compilers (for the host tools in the “tools” directory).
• Input Artifact:
• The required original baserom.gba is the starting point.
• Core Disassembled Code:
• Main ROM code (organized in directories such as rom_15000, rom_185000, etc.) contains the bulk of the disassembled code.
• The “include” directory holds header files with common constants/macros (e.g., gba.inc, macros.inc).
• The “lib” directory contains utility assembly functions.
• Overlays:
• Found in the “overlays” directory with many subdirectories (e.g., overlays/rom_779188, overlays/rom_78603c, etc.). Overlays are segments of disassembled code loaded on demand.
• ROM Layout and Linking Information:
• The linker scripts (goldensun.ld, overlay.ld files in each overlay folder) and the wram.sym file define memory mapping and symbol definitions.
• Tools:
• The “tools” directory contains C utilities (for packing/unpacking overlay strings) that support the build process.
Architectural Relationships and Data Flow
• Input Phase:
• The baserom.gba file serves as the source ROM; its contents are used as a reference.
• Disassembly/Source Modules:
• The project is divided into multiple segments (ROM base parts and overlays) that correspond to regions of the original game.
• Each ROM region (in directories like rom_15000, rom_185000, etc.) is disassembled separately into assembly source (.s files). Overlay directories mirror this, with each overlay exposing “imports” and “exports” to manage their interplay.
• Build and Link Process:
• The Makefile orchestrates the compilation and linking: it takes all these disassembled source files, uses the linker scripts and symbol files to map them into memory appropriately, and produces a verified output (the rebuilt goldensun.gba or goldensun.bin).
• Verification:
• SHA1 and other verification files (e.g., goldensun.sha1, overlay.sha1 files) ensure that each module’s output matches known signatures.
• Auxiliary Tools:
• Tools (pack_strings, unpack_overlay, etc.) help prepare or post-process the disassembled code to match the ROM’s expected format.
Design Details
• Flow from the original baserom.gba into the disassembly source.
• From separate source directories into the build process.
• From build process outputs into the final ROM.
• Annotations:
• Notes on what “overlays” are, mentioning that these are dynamically loaded segments verified separately.
Architectural Patterns
• Separation of concerns: Each ROM region or overlay is isolated into its own module with explicit “imports/exports” boundaries.
• Layered build process: There is a dependency ordering – from disassembled source modules to pre-processing (tools), then to linking (build system) and finally to the output binary, with verification in between.
• Modularity: The use of overlays highlights a micro-module architecture wherein not all code is loaded at once, thus mirroring the original ROM’s memory management.
• Using a diagramming tool, lay out each block as described.
Happy diagramming!