Format:3DSX
| Magic | 33 44 53 58 ("3DSX") at offset 0 |
|---|---|
| Extensions | .3dsx |
| Endianness | little |
| On this wiki | Facts · Code · Notes · Topics |
Nintendo 3DS homebrew executable (.3dsx): a 32- or 44-byte header with magic 3DSX, three relocation headers, the code, rodata and data segments, then skip/patch relocation tables, with an optional embedded SMDH and RomFS.
Header
See Fact:3DSX/struct/Header. All fields are little endian. The base header is 0x20 bytes: magic 3DSX (0x58534433 as a u32), u16 header size, u16 relocation header size, u32 format version, u32 flags, then the sizes of the code, rodata and data segments and of the BSS (the uninitialized tail of the data segment, which is not stored in the file). When the header size is larger (3dsxtool writes 0x2C when it embeds an SMDH or RomFS) three more u32 follow: SMDH offset, SMDH size and RomFS (filesystem) offset.
Layout
The file order is: header, three relocation headers (code, rodata, data), the code segment, the rodata segment, the loadable part of the data segment (data size minus BSS size), then the relocation tables of the code segment, rodata segment and data segment in that order, then the SMDH and RomFS if present. The loader rounds each segment size up to 0x1000; the entry point is the start of the code segment; the application must clear its own BSS.
Relocations
Each relocation header is a list of u32 counts: 3dsxtool writes two (absolute and relative); a loader derives the number of tables from the relocation header size divided by 4 and skips tables from the third on. Each table entry is two u16, skip then patch: from the current word pointer skip skip words, then patch the next patch words. A patched word holds the segment-relative address in its low 28 bits and a sub-type in its top 4 bits. Absolute table: the sub-type must be 0 and the word becomes the final address. Relative table: the word becomes target minus the address of the word itself; sub-type 0 is a 32-bit signed offset and sub-type 1 clears bit 31 of the result. See Fact:3DSX/behavior/Relocation tables.
Notes
Azahar also accepts a file whose first four bytes are Z3DS when the wrapped-file magic stored in that header is 3DSX: Format:Z3DS is its own zstd-seekable compression wrapper (usually named .z3dsx), not part of the original format (Fact:3DSX/identification/Loader accepts Z3DS wrapper). Azahar only exposes the SMDH and RomFS when the header size is 0x2C (Fact:3DSX/behavior/Header size and extended fields in azahar).
The embedded Format:SMDH holds the titles and icon of the application. Azahar treats everything from the RomFS offset to the end of the file as the RomFS image. Unverified: the image layout (presumably Format:RomFS (3DS IVFC); I did not read azahar's reader) and that libctru's romfs mounting reads it.
See also Platform:Nintendo 3DS and Library:Libctru.
Code & repositories
- https://github.com/devkitPro/3dstools @
718d6f2330dbef9dd5726573392425dcbd451677· license: none
3dstools (3dsxtool, smdhtool): src/3dsxtool.cpp writes the 3DSX header and relocations, src/smdhtool.cpp the SMDH structures. Read for format facts only.
Tested on: source read, not run · checked 2026-10-18; last activity 2023-11-17; no license: not reusable - https://github.com/azahar-emu/azahar @
987f18405073960622e1043bb44005989135c6e1· license: GPL-3.0
azahar (3DS emulator, GPL-2.0): src/core/loader/3dsx.cpp, src/core/file_sys/cia_container.h/.cpp, ncch_container.h. Read for format facts only.
Tested on: source read, not run · checked 2026-10-18; last activity 2026-10-17; Note: the latest release ships binaries; the wiki links only the source, never the binaries