Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Library:Libdragon

From ReverseEngineering.wiki
Library
Developer libdragon contributors (github.com/DragonMinded/libdragon)
Platforms Platform:Nintendo 64, iQue Player
Versions two maintained branches: trunk (stable) and preview (newer formats); IPL3 revisions r1-r10
License Unlicense (public domain)
Website https://libdragon.dev
On this wiki Facts · Code · Notes · Topics

Open-source (public domain, Unlicense) SDK for Platform:Nintendo 64 homebrew, with its own open-source IPL3 bootcode, a ROM builder (n64tool) that packs an optionally compressed ELF, a symbol table and a DragonFS filesystem behind a "TOC0" table of contents, and libraries for graphics (rdpq), audio and Joybus peripherals. A libdragon ROM can be recognised from its IPL3 and usually carries function names and source lines in its embedded SYMT symbol table.

Overview

libdragon replaces Nintendo's libultra for homebrew. A build (n64.mk) links the program into an ELF, generates a symbol table from it (n64sym), strips and by default compresses the ELF (n64elfcompress), and has n64tool write the ROM: libdragon's IPL3, then a table of contents, the ELF, the .sym file, an optional .msym (symbols for dynamic modules) and an optional DragonFS image (.dfs). The ROM never relies on Nintendo's 1 MiB-at-0x1000 load rule (Platform:Nintendo 64#Boot sequence).

Two branches exist and differ in on-ROM formats: trunk and preview (the ROM checked for this page, N64FlashcartMenu V0.3.4, was built from preview). The GitHub repository github.com/DragonMinded/libdragon was archived in September 2026 (last push 2026-09-14); ROMs built before then use one of these two branches, and the formats documented here are those of trunk e356bf3 and preview 39d0d60. ROMs built from preview carry a libdragon.version JSON file naming the branch and commit.

Identification

  • Header: CRC1/CRC2 at 0x10 are 0, clock rate and libultra version 0, title Libdragon padded with spaces unless the developer set one (n64tool --title).
  • IPL3: ROM 0x40 onwards equals libdragon's boot/bin/ipl3_prod.z64 from offset 0x40. Its first words load registers for the stage-1 code in DMEM; the hash still matches CIC 6102 (seed 0x3F), so the ROM boots on standard cartridges. The production IPL3 is longer than 4 KiB since r2: stage 2 continues after 0x1000, so the table of contents is not at 0x1000 but after the IPL3 (0x1930 with r10).
  • Release MD5s of ipl3_prod.z64 (from libdragon's boot/README.md): r10 1337f98513cb0eb17ccd908f5866348b, r9 4ed3e5fd564235a844af74366dba7f92, r8 419c213307cdb855934852c67759102b, r7 7f014ed41cc53bb1a5e44f211f8c3dec, r6 954cc30e419ba8561e252cd97f8da0a2, r5 1463a76f789aa2087dc0ba4e93d6c25d, r4 d78ddd06d2303d3f76d11de6b6326d69, r3 415c937a90ceee6f99d3d8a84edb42d3, r2 8eb4192531d365fe3607be973f2f4eb0, r1 d240dee9f218e48edffa16ab24249ecf. A ROM's own header differs from that file, so compare from 0x40, or compare CRC32 of ROM 0x40-0xFFF: 0x345E1229 for r8, 0x86472013 for r10.
  • Strings: TOC0 near the start, SYMT at the .sym entry, DragonFS 2.0/DragonFS 2.1 at the start of a DragonFS image, and the libdragon.version JSON ("branch": "preview", "hash": ...).

ROM layout

n64tool writes the files back to back with the alignments given by n64.mk (--align 256 before the ELF, 8 before .sym, 16 before .dfs) and records them in a 1024-byte table of contents placed 16-byte aligned right after the IPL3. The runtime finds it by scanning 1024 16-byte steps from ROM 0x1000 for the magic TOC0, then looks files up by extension (.sym, .msym, .dfs). Offsets in the TOC are ROM offsets; add 0x10000000 for the PI address.

  • trunk: header char magic[4] = "TOC0"; u32 toc_size (1024); u32 entry_size (64); u32 num_entries; then entries u32 offset; char name[60].
  • preview: header char magic[4]; u32 cookie; u32 toc_size; u16 entry_size; u16 num_entries; then entries u32 offset; u32 size; char name[56]. The cookie is a CRC32 over the written file contents, used to notice a ROM swapped at runtime.

The IPL3 code itself can contain the bytes TOC0 (it does in r10, before the real TOC), so a scanner must check that the next fields parse.

Compressed ELF

libdragon's IPL3 loads every PT_LOAD segment (see Format:ELF (Executable and Linkable Format) for the program header fields) of the first big-endian MIPS ELF it finds at a 256-byte-aligned ROM offset. Segments flagged PF_N64_COMPRESSED (0x1000 in p_flags) are compressed: p_vaddr is where the compressed bytes are loaded, p_paddr the destination of the decompressed data, p_filesz the compressed size and p_memsz the decompressed size plus BSS. A segment of type PT_N64_DECOMP (0x64E36341) holds the decompressor, loaded at its p_vaddr (or, if 0, into the IPL3's reserved last 64 KiB of RDRAM). To disassemble such a ROM, take the ELF from the TOC, decompress its segments and load them at p_paddr; the ELF's e_entry is the program entry (0x80000400 by default), where libdragon's _start begins (signature in the facts of this page). With the default compression level 1 each compressed segment is one raw LZ4 block (no LZ4 frame header; see Format:LZ4#Block format): a plain LZ4 block decoder over p_filesz bytes at p_offset gives the segment, as checked on N64FlashcartMenu V0.3.4 (535,664 compressed bytes to 828,712; the rest of p_memsz is BSS). Other levels use other algorithms (n64.mk passes N64_ROM_ELFCOMPRESS (default 1) as -c to n64elfcompress, which accepts 0 to MAX_COMPRESSION = 3 (tools/common/assetcomp.h lines 17-18) and calls asset_compress_mem_raw; in tools/common/assetcomp.c level 1 is LZ4 HC, level 2 is aPLib (case 2: // aplib) and level 3 is Shrinkler (case 3: // shrinkler), libdragon trunk commit e356bf3f56f7afbf7e5246329562f145965cfdfc (the doc comment above asset_compress still says "2 = lzh5", which the code does not do)); dumping RDRAM from an emulator after boot works for any level.

Symbol table (SYMT)

Every ROM built by n64.mk carries <program>.elf.sym, made by n64sym from the unstripped ELF, so libdragon ROMs usually ship function names, source file names and line numbers for function starts and call sites even though the ELF is stripped. This is the first thing to extract when reversing a libdragon ROM.

  • Version 2 (trunk): header "SYMT", u32 version, u32 addrtab_off, u32 addrtab_count, u32 symtab_off, u32 symtab_count, u32 strtab_off, u32 strtab_size (offsets from the start of the file). The address table is sorted big-endian u32 RAM addresses; bit 0 set marks a function start, bit 1 an inline duplicate. Each 16-byte symbol entry is u32 func_name_off, u32 file_name_off, u16 func_name_len, u16 file_name_len, u16 line, u16 offset_in_function, with names in the string table (not NUL-terminated).
  • Version 5 (preview): an 80-byte header ("SYMT" plus 19 u32: symbol count, chunk count and offsets of a chunk index, file and function tables, a Huffman table, file/function name blobs and a compressed stream). Names and addresses are Huffman/Shrinkler compressed; preview's tools/n64sym/n64symdump decodes them.

Boot flags

libdragon's IPL3 does not use the low-memory flags at 0x80000300 (only its compatibility build writes them). It leaves 16 bytes at the start of RSP DMEM (0xA4000000): RDRAM size (u32), a 32-bit random seed collected during boot, ROM type (u8: 0 cartridge, 1 64DD), TV type (u8: 0 PAL, 1 NTSC, 2 MPAL), reset type (u8: 0 cold, 1 warm), console type (u8: 0 N64, 1 iQue), and the ELF's ROM offset in 256-byte pages (u16). libdragon's _start copies them into globals (__boot_memsize, __boot_tvtype, __boot_resettype, __boot_consoletype) before calling main.

Code & repositories

  • https://github.com/DragonMinded/libdragon @ e356bf3f56f7afbf7e5246329562f145965cfdfc · license: Unlicense
    Open-source N64 SDK: hardware register definitions (include/, src/vi.h), an open-source IPL3 bootcode with documented boot hand-over (boot/), the ROM builder n64tool and the SYMT symbol-table generator n64sym (tools/). The preview branch (39d0d60) has newer TOC and SYMT formats.
    Tested on: Read at trunk e356bf3 and preview 39d0d60 (2026-09-15); header, TOC and ELF layouts checked with a Python parser on boot/bin/ipl3_*.z64 and the N64FlashcartMenu V0.3.4 ROM. · checked 2026-10-17; archived; last activity 2026-09-14; Note: the latest release ships binaries; the wiki links only the source, never the binaries

Pitfalls

  • Do not assume the trunk formats for a preview-built ROM (or the reverse): the TOC header and SYMT differ. Check the libdragon.version file or the field values.
  • The IPL3 reserves the last 64 KiB of RDRAM and clears all RDRAM except the first 0x400 bytes before booting, so RAM dumps from a fresh boot contain no leftovers.

Evidence & references

  • Source read at trunk e356bf3 and preview 39d0d60: boot/README.md (IPL3 features, boot flags, ELF compression, MD5 changelog), tools/n64tool.c, src/rompak.c, tools/n64sym.c and src/backtrace.c (SYMT v2), tools/n64sym/n64symdump.c (SYMT v5), n64.mk lines 117-137 (trunk).
  • Checked on N64FlashcartMenu V0.3.4 (N64FlashcartMenu.n64, AGPL-3.0, SHA-256 042b4831869c0ea366a7a2b768c644996d9f849c8cb6228833452e4128b2f3f9): IPL3 r10, TOC0 (preview layout) at 0x1930 with four files (ELF at 0x1E00, SYMT v5 at 0x84CE0, DragonFS 2.1 at 0x9D1C0, libdragon.version), and an ELF with a PT_N64_DECOMP segment and two PF_N64_COMPRESSED segments loading to 0x80000000 and 0x80000400.