# gsret/goldensun architecture

> Architecture diagram of the GitHub repository gsret/goldensun, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gsret/goldensun
- Repository: https://github.com/gsret/goldensun

## Overview

##### 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!

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input
    OriginalROM["Original ROM (baserom.gba)"]:::input

    %% Disassembly / Source
    subgraph "Disassembly / Source"
        %% Main ROM Modules
        subgraph "Main ROM Modules"
            rom15000["rom_15000"]:::source
            rom185000["rom_185000"]:::source
        end
        %% Overlay Modules
        subgraph "Overlay Modules"
            overlay1["overlays/rom_779188"]:::source
            overlays_common["overlays/common"]:::source
        end
        %% Common Libraries and Headers
        subgraph "Common Libraries and Headers"
            include_node["include"]:::source
            lib_node["lib"]:::source
        end
    end

    %% Build System
    subgraph "Build System"
        makefile["Makefile"]:::build
        goldensun_ld["goldensun.ld"]:::build
        wram_sym["wram.sym"]:::build
        goldensun_sha1["goldensun.sha1"]:::build
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        tools_node["tools"]:::tool
    end

    %% Output and Verification
    verification["Verification (SHA1_checks)"]:::output
    output["Rebuilt ROM (goldensun.gba/goldensun.bin)"]:::output

    %% Data Flow from Input to Disassembled Source Modules
    OriginalROM -->|"feeds"| rom15000
    OriginalROM -->|"feeds"| rom185000
    OriginalROM -->|"feeds"| overlay1
    OriginalROM -->|"feeds"| overlays_common
    OriginalROM -->|"provides"| include_node
    OriginalROM -->|"provides"| lib_node

    %% Flow from Disassembled Sources and Tools to Build System
    rom15000 -->|"compiled by"| makefile
    rom185000 -->|"compiled by"| makefile
    overlay1 -->|"linked via"| makefile
    overlays_common -->|"linked via"| makefile
    include_node -->|"defines"| makefile
    lib_node -->|"provides utilities"| makefile
    tools_node -->|"pre/post-processes"| makefile

    %% Build System incorporating Linker Scripts and Verification Info
    makefile -->|"integrates"| goldensun_ld
    makefile -->|"integrates"| wram_sym
    makefile -->|"integrates"| goldensun_sha1
    makefile -->|"triggers"| verification
    goldensun_ld --> verification
    wram_sym --> verification
    goldensun_sha1 --> verification

    %% Final Output
    verification -->|"outputs"| output

    %% Click Events
    click makefile "https://github.com/gsret/goldensun/tree/master/Makefile"
    click goldensun_ld "https://github.com/gsret/goldensun/blob/master/goldensun.ld"
    click wram_sym "https://github.com/gsret/goldensun/blob/master/wram.sym"
    click goldensun_sha1 "https://github.com/gsret/goldensun/blob/master/goldensun.sha1"
    click include_node "https://github.com/gsret/goldensun/blob/master/include/gba.inc"
    click lib_node "https://github.com/gsret/goldensun/blob/master/lib/call_via.s"
    click rom15000 "https://github.com/gsret/goldensun/tree/master/rom_15000"
    click rom185000 "https://github.com/gsret/goldensun/tree/master/rom_185000"
    click overlay1 "https://github.com/gsret/goldensun/tree/master/overlays/rom_779188"
    click overlays_common "https://github.com/gsret/goldensun/tree/master/overlays/common"
    click tools_node "https://github.com/gsret/goldensun/blob/master/tools/pack_strings.c"

    %% Styles
    classDef input fill:#f7c6c7,stroke:#333,stroke-width:2px;
    classDef source fill:#c6f7d5,stroke:#333,stroke-width:2px;
    classDef build fill:#c6d4f7,stroke:#333,stroke-width:2px;
    classDef tool fill:#f7e2c6,stroke:#333,stroke-width:2px;
    classDef output fill:#f7d6c6,stroke:#333,stroke-width:2px;
```
