A byte-exact, from-scratch disassembly and layout of Final Fantasy Tactics
Advance (USA, AFXE), ready to start decompiling.
The analysis, split and matching harness live in fftadecomp-kit; they produced everything here from the ROM in this directory. No third-party decomp tool output is used.
Legacy provisional metrics (including the two percentage badges):
| Metric | Count | Percent | |
|---|---|---|---|
| Functions matched | 4,507 / 5,337 | 84.45% | ββββββββββββββββββββββββββββ |
| Bytes matched | 679,008 / 732,156 | 92.74% | ββββββββββββββββββββββββββββ |
| Bytes matched (index span) | 679,008 / 1,286,835 | 52.77% | ββββββββββββββββββββββββββββ |
The function denominator counts 5,337 provisional index entries
starting below 0x08150000; matched main bytes count indexed spans.
The byte denominator sums all legacy layout segments named code*,
including late-ROM labels, or falls back to the union of main indexed
spans when that sum is zero or the layout is absent. Labels do not
prove code ownership; index spans can be truncated or overlapping.
Generated by tools/status.py from config/functions.json and the
match reports in docs/match/.
Both byte denominators are provisional. Layout labels undercount
code; index spans can run long or cover code-like data. Neither
denominator is established. The index-span row divides the union
of matched entries' spans by the union, overlaps merged, of every
entry span starting below 0x08150000.
Matched bytes per 64 KiB region (of indexed span)
0x08000000 ββββββββββββββββββββ 62.3% 385/457 fns
0x08010000 ββββββββββββββββββββ 69.7% 380/414 fns
0x08020000 ββββββββββββββββββββ 73.2% 354/395 fns
0x08030000 ββββββββββββββββββββ 51.1% 145/169 fns
0x08040000 ββββββββββββββββββββ 60.6% 170/201 fns
0x08050000 ββββββββββββββββββββ 47.1% 167/192 fns
0x08060000 ββββββββββββββββββββ 67.4% 245/266 fns
0x08070000 ββββββββββββββββββββ 24.2% 48/78 fns
0x08080000 ββββββββββββββββββββ 41.5% 138/170 fns
0x08090000 ββββββββββββββββββββ 37.3% 238/278 fns
0x080A0000 ββββββββββββββββββββ 28.2% 111/143 fns
0x080B0000 ββββββββββββββββββββ 34.9% 129/155 fns
0x080C0000 ββββββββββββββββββββ 57.2% 452/487 fns
0x080D0000 ββββββββββββββββββββ 66.2% 379/428 fns
0x080E0000 ββββββββββββββββββββ 64.0% 123/152 fns
0x080F0000 ββββββββββββββββββββ 59.4% 94/128 fns
0x08100000 ββββββββββββββββββββ 57.6% 86/114 fns
0x08110000 ββββββββββββββββββββ 43.4% 85/138 fns
0x08120000 ββββββββββββββββββββ 65.4% 351/390 fns
0x08130000 ββββββββββββββββββββ 50.7% 252/298 fns
0x08140000 ββββββββββββββββββββ 44.8% 175/284 fns
0x08150000+ assets and data; 1,395 index entries
Legacy credit: 4,507 matched functions and 679,008 indexed bytes. Only exact matches are committed - see the rule in Matching.
Additional verified late-ROM spans: 0 functions; 0 complete-body bytes. These separately indexed and verified ROM bodies include their internal literal pools, exclude external alignment and RAM aliases, and do not alter the legacy metrics. No late-ROM denominator is established; neither summary certifies exhaustive whole-game coverage.
Library units: 3 recorded in config/library_units.json.
Prebuilt library objects that the original build compiled with another
toolchain. Each function inside one is verified with its unit's
toolchain, or with the default one where both emit the same function.
They are part of the legacy metrics above and are listed here apart
from the rest of the code.
| Unit | Range | Toolchain | Functions matched | Bytes matched |
|---|---|---|---|---|
| boot -O0 | 0x08000438-0x080007C8 |
agbcc-O0-v1 |
7 / 9 | 512 / 638 |
| agb_flash FLASH512_V130 | 0x0814189C-0x0814220C |
agbcc-O1-v1 |
11 / 24 | 708 / 2,406 |
| libgcc dp-bit | 0x08142BE8-0x081439C8 |
old-agbcc-O2-v1 |
16 / 20 | 1,860 / 3,538 |
| Everything outside library units | default | 4,473 / 5,284 |
The block above β badges and table β is generated, not typed. Recompute and rewrite it with:
python ../fftadecomp-kit/tools/status.py --write # from the match reports
python ../fftadecomp-kit/tools/status.py --write --verify # recompile everything first
python ../fftadecomp-kit/tools/status.py --check # exit 1 if stale (CI does this)or make status / make verify. Two GitHub Actions workflows keep it honest:
status fails a push if the committed numbers are stale and refreshes them
weekly, and matches refuses any function in src/ that lacks a match report
saying byte-identical β which is the repo rule, enforced.
The badges are shields.io endpoint badges: each one reads a JSON file
(functions.json, bytes.json) served from this repository's badges
branch. The status workflow rebuilds those files from the percentages in the
committed docs/status.md and republishes the branch on every push to main,
with a weekly run and a badges repository dispatch as backstops. They read
only the Functions matched and Bytes matched rows of the table.
| File | Final Fantasy Tactics Advance (USA, Australia).gba (local baserom.bin symlink) |
| Size | 16,777,216 bytes (16 MiB) |
| SHA-1 | 4AC05441F4DE70A4EC3DD932116346C61B8783D9 |
| Title / code | FFTA_USVER / AFXE (USA), maker 01 |
| Entry point | 0x080000C0 (b 0x080000C0 at 0x08000000) |
| Verified rebuild | rebuild.py (in the kit) β SHA-1 matches the base ROM exactly |
1. The cartridge header passes validation.
- The Nintendo logo at
0x08000004-0x0800009Fmatches the expected logo. - The computed and stored header checksum are both
0x89.
Earlier reports of 148 differing logo bytes and a computed checksum of 0x85
were analyzer defects, not evidence of ROM damage. The corrected kit validates
both fields. A copy named Final Fantasy Tactics Advance (USA, Australia).gba
was also checked byte-for-byte against this baserom and is identical. Compare
SHA-1 against the value above before starting a matching build.
2. The main code region is the first ~1.3 MiB, but executable code also exists later.
The layout is not "text, then rodata, then gfx" like an unstripped build:
| ROM range | Size | What it is |
|---|---|---|
0x08000000-0x080000C0 |
192 B | cartridge header |
0x080000C0-0x08150000 |
1.31 MiB | code region β Thumb-dominant, data and literal pools interleaved |
0x08150000-0x08A39820 |
~9.5 MiB | mostly assets: high-entropy blobs (~7.5 bits/byte, compressed or packed) and 4bpp tile data (~3.5-4.5), with known copied executable routines |
0x08A39820-0x08FE1350 |
~5.9 MiB | zero padding |
0x08FE1350-0x08FFFFFF |
~124 KiB | 0xFF padding to the 16 MiB boundary |
The installer at 0x08002768 references the 176-byte image
[0x08A38A2C,0x08A38ADC) for copying to 0x03005E78 through the
SVC 0x0B wrapper at 0x0814186C. Under the BIOS CpuSet contract, its
third call copies 88 halfwords. The image contains these complete Thumb
bodies, not one 176-byte function:
| ROM body (exclusive end) | Installed RAM body (exclusive end) | Bytes | Instructions |
|---|---|---|---|
0x08A38A2C-0x08A38A5E |
0x03005E78-0x03005EAA |
50 | 25 |
0x08A38A60-0x08A38A9C |
0x03005EAC-0x03005EE8 |
60 | 30 |
0x08A38A9C-0x08A38ADA |
0x03005EE8-0x03005F26 |
62 | 31 |
Two external zero halfwords complete the copied image. RAM placements are
aliases of these ROM bodies, not additional functions. Installation does not
prove that later RAM writes preserve their bytes. The installer itself owns
80 bytes: 58 code bytes (26 instructions), two internal alignment bytes and
five required literal words. Its return before those literals is not its
complete boundary. The function denominator below 0x08150000 remains
provisional and excludes these later bodies. The byte denominator instead
sums legacy layout segments named code*, including late-ROM segments;
those labels do not prove code ownership. Neither denominator establishes
exhaustive whole-game coverage.
Startup chain, walked from the entry point:
0x080000C0 ARM crt0: CPSR/user-mode switch, stack and IRQ vectors, then
`ldr r1,[pc,#0x154]; mov lr,pc; bx r1` into Thumb
0x08000254 Thumb init: hardware setup, table copies, then calls into the
function at 0x08000670 and others
0x08000670 Thumb sets four bit-fields in the block at 0x03000000
(45 instructions; matched at -O0)
config/functions.json indexes 6,731 entries. 5,336 start below
0x08150000 (5,327 Thumb, 9 ARM); they are the function denominator in
the status block. The other 1,395 start at or above 0x08150000 (1,287
Thumb, 108 ARM) and are mostly data. Decoded linearly as strict ARMv4T
Thumb (16-bit forms plus bl pairs), skipping the literal words their own
PC-relative loads name, only about 19% of the 1,287 high Thumb entries
(roughly 245) are valid from start to end, against about 99% of the 5,327
Thumb entries below 0x08150000. Fewer than ten of the valid high entries
contain a bl, and none of those calls lands below 0x08150000. The exact
counts shift by a few with decoder details (how bx low bits, bkpt or a
bl straddling the end are treated) and a Thumb-2 decoder accepts far more,
so read them as proportions, not as a tracked metric. This decode
gap is the evidence that code ends and assets begin at 0x08150000. Function boundaries come from a
prologue pattern plus a linear walk that must reach a return or a tail
branch, which is what keeps the 4bpp tile data from producing thousands of
fake functions (the byte pair 0xB5xx looks like push {rX, lr} about once
every 300 KiB of tile data).
Matched bytes per 64 KiB region below 0x08150000 are in the status block
above (Matched bytes per 64 KiB region), regenerated with the block.
baserom.bin verified copy of the ROM (gitignored)
asm/
ffta.s master armips script: includes the chunks below
code_00000000.s .. one file per 64 KiB of the code region, labelled asm
code_00140000.s
tail.s everything after the code region, .incbin in file order
manifest.json every run of the ROM in address order
files/ raw runs carved out of the ROM - GENERATED, gitignored
(16 MB of Square's data; regenerate with make split)
symbols/
functions.txt address end size instrs, human readable
ffta.sym address size name (func_08000670 ...)
config/
rom_layout.json header, per-segment classification, stats
coverage.json code/data runs, RLE-style
functions.json the function list, machine readable
logs/analysis.txt full analysis report (coverage table, segment dump)
tools/ see fftadecomp-kit (this repo's data is produced by it)
src/ matched C only - one file per function
include/ffta.h base types, struct shapes, prototypes
docs/toolchain.md how the compiler was identified, and how to build it
docs/match/ per-function match reports
Parked/ attempts that do not match yet (see the rule in Matching)
Makefile thin wrapper around the kit
linker.ld GBA memory map reference
The tooling lives in its own repo so it can be used on any GBA image:
git clone https://github.com/shubshub/fftadecomp-kit.git # private
make check KIT=../fftadecomp-kitThe tools need nothing but Python 3 and capstone, on any OS. On a checkout, carve the ROM with the tracked index and prove the split exact:
python -m pip install capstone
make split check
# which runs:
# python ../fftadecomp-kit/tools/split.py baserom.bin . # tracked index -> asm/, files/
# python ../fftadecomp-kit/tools/rebuild.py . # must print: byte for bytemake check is the same as rebuild.py. split also rewrites the tracked
symbols/ffta.sym; restore it with git checkout -- symbols/ffta.sym unless
you meant to change it.
Do not run analyze.py, make init or make regen on a checkout.
analyze.py regenerates the tracked index in config/, symbols/ and
logs/ from a fresh scan of the ROM (~10 min, 16 MiB), and is only for
producing that index from scratch; make init and make regen run
analyze, refine, split and check. Under WSL/Linux,
../fftadecomp-kit/tools/bootstrap.sh installs the rest of the toolchain.
make rom # armips asm/ffta.s, then verify against the base ROMThe .incbin data guarantees every non-code byte is right; the assembly in the
code region is what armips has to re-encode exactly.
The compiler has been identified: agbcc β gcc 2.9-arm-000512 for Thumb/elf
(12 May 2005). Full details, build instructions and the flag study are in
docs/toolchain.md.
agbcc -mthumb-interwork -O2
The first seven matches are listed below; the complete, growing catalog is in
src/ and docs/match/. Each is verified by compiling the C and comparing the
entire ELF function symbol against the ROM, including its literal pools:
| address | bytes | what it is |
|---|---|---|
0x08017514 |
18 | four byte stores, 4th argument on the stack |
0x08011040 |
22 | copies three 16-bit fields and returns a byte at offset 0x1D |
0x080112D4 |
20 | copies three s16 fields out of a struct |
0x08006ADC |
28 | table slot write + flag clear (u8 index) |
0x0801CD4C |
32 | scatters 4 bytes from the table at 0x02007F10 |
0x08017AC4 |
20 | sets flag bit 1 and stores two 32-bit fields |
0x0801E68C |
28 | copies three words from the structure at 0x02007F40 |
python ../fftadecomp-kit/tools/match.py 0x08017514 # or: make match ADDR=0x08017514
The tool preprocesses (agbcc is a raw cc1 and does not run cpp itself),
compiles, assembles, strips, and diffs against the ROM bytes.
To verify that all currently matched C integrates into the full ROM:
python ../fftadecomp-kit/tools/rebuild.py . --compiled
python ../fftadecomp-kit/tools/rebuild.py . --compiled --output build/ffta-mixed.gbaThe optional output must not already exist. This is a partial mixed C/ROM build: verified compiled symbols replace their original ranges, while unmatched code and data remain original. The tool reports both byte counts and compares the entire resulting image. Byte-exact integration is not 100% decompilation.
Two findings worth keeping in mind while writing C:
- The compiler reads stack arguments straight off
spβ 286 functions in the ROM do this, with no frame pointer. Modern GCC will not. - Address constants must go in a variable. For
func_0801CD4C, writing((u8 *)0x02007F10)[0x0d]inline makes the compiler fold every access into its own literal-pool entry; a local pointer gives the single load the ROM has.
Only byte-exact matches, from plausible source, are committed.
tools/match.py puts a function through two gates, and both have to pass:
- Bytes. The entire compiled ELF function, including literal pools, must
be identical to the ROM. Mode and alignment must agree, relocations must
be resolved, and a complete return must be verified. The verifier
accepts only function shapes it has a supported profile for - among them
local control flow and loops, fixed Thumb frames, named data literals,
direct calls summarised by the ABI, switch tables (including ones that
pass function addresses, and switch functions that call through the
_call_via_rNthunks), audited division runtimes, BIOSCpuSet/CpuFastSetfills,CpuSetcopies that install a code image in RAM, and dead arguments. Every profile states the premises it does not prove; the variable stack-index profiles also take an unproved bound on each index, and admit nothing untilconfig/stack_index_premises.jsoncarries a reviewed entry for the function - a written review and the exact rows (site, expression, bound) checked against its callers. The kit README lists every profile and its limits; anything else fails closed. - Plausibility. The source must look like something a developer could
have written.
tools/plausible.pyrejects inline asm, optimisation pragmas, dead code (if (0),while (0),#if 0),if/elsearms that are the same single statement,volatile, placeholder bodies, steering padding, attributes that only affect emission, and comments that admit the code exists to steer the compiler.volatilehas two narrow exceptions, both defined in the kit README: a direct, commented access to a hardware register in0x04000000-0x040003FF, and objects on the maintainer's allowlist. Do not extend either.
A function that fails either gate is not a match. Byte-identical output from
implausible source is the failure case this rule exists for: it proves the
bytes, not the decompilation. Such a function reports
IMPLAUSIBLE - bytes match but the source is not code a developer would have written, and its report deliberately does not contain the string the CI looks
for.
Passing both gates is necessary, not sufficient. Source that is there only because it moved the bytes is a fake even when the gate does not catch it. Code that does nothing at run time ships only when the ROM itself shows it - a test the ROM still performs, a zero term its instruction order needs - and it carries a comment citing the addresses. The rule, with what ships and what does not, is Evidence first in AGENTS.md.
Anything that fails either gate, and any byte-identical source that needs a
fake, goes in Parked/<address>/ with its match report, until it is fixed β
not until a compiler flag is nudged.
Agents working in parallel have to claim the address they are on, so the claim
lives as an issue in fftadecomp-kit β the ledger is shared, the repo is
not. reserve.py goes through the authenticated broker and works for any
contributor with a gh login:
python ../fftadecomp-kit/tools/reserve.py check 0x08011040 # 0 free, 1 taken
python ../fftadecomp-kit/tools/reserve.py claim 0x08011040 --who me --note "..."
python ../fftadecomp-kit/tools/reserve.py claim 0x08011040 0x080112D4 --who meContributors with permission to edit the ledger issue can use
../fftadecomp-kit/tools/take.py (same list/check/claim commands) to
write it directly. A permission failure there is not a lease: take.py falls
back to a broker request, and only an accepted response holds the address.
Both paths refuse an address that is already reserved, matched on the default
branch, or in an open pull request.
claim refuses an address somebody else holds. Reservations are leases: ping
while working, release when you stop β especially when you conclude a
function cannot be matched, with --unmatchable so the next agent is told to
skip it. Anything quiet for 3 days is auto-released by a workflow.
A batch claim creates one issue after checking every member. Release members
individually with release ADDRESS --issue NUMBER --who me --reason "...";
the issue remains open until its last member is released. Serialize updates
to a batch so one release cannot overwrite another.
The recipe is fixed at -mthumb-interwork -O2; do not search flags per
function. The exception is five startup functions (0x08000460,
0x0800052C, 0x0800058C, 0x08000670, 0x080006D0) that were built at
-O0 and match only under the kit's dedicated
compiler-orphan-address-constants-O0-v1 profile; their reports record it.
Library objects prebuilt with other settings take their toolchain from a
whole library unit, never from a per-function flag: see the kit README's
Library units.
In the earlier 43-match frameless corpus all 43 matched at -O2,
-O3 and -Os and 12 differed at -O1, so the sweep never separated those
three levels (see docs/toolchain.md). A function that calls a static helper
could still tell them apart.
- Function bodies come from a prologue scan. The scan finds where a
function starts but not always where it ends, because a conditional branch
falls through.
make refinecorrects the index from the committed match reports, so ends are only as good as the functions matched so far. - Literal pools are data gaps, which is why code and data alternate
throughout the code region. Turning the
data_*.bingaps between functions into.pool+ named constants is the first thing to do per function. - Not every entry comes from a prologue. Kinds
call(840 below0x08150000),pointerandcallback*arebltargets and address constants, and a handful of false positives survive deep in the asset regions. Compare against a real disassembler (Ghidra/IDA) when you start a specific area.
- Work through the small functions. The earliest matches were all leaf
functions with no branches. A good place to start is the other complete
leaf/straight-line functions listed in
symbols/functions.txtβ same shape, same harness, and each one teaches you about struct layouts. - Check the optimisation level if you find a function that calls a static
helper: whether the call survives would separate
-O3, which inlines static functions, from-O2/-Os. - Track progress in the status block above (overall rows and per-region
bars) and, per function, in the match reports under
docs/match/. Notemips_to_cdoes not apply β it only reads MIPS. - Name as you go.
func_08017514β whatever it really does, insymbols/ffta.symand in the.globallines of the asm.