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

Format:NSO

From ReverseEngineering.wiki
Format
Magic 4E 53 4F 30 ("NSO0") at offset 0
Endianness little
On this wiki Facts · Code · Notes · Topics

Nintendo Switch executable module (NSO0): a 0x100-byte header with three segments (text, rodata, data) that are optionally LZ4-compressed, SHA-256 hashes of the decompressed segments and a module id.

Header

See Fact:NSO/struct/Header. Layout per switchbrew documentation: magic, version, reserved, flags (bit 0-2: text/rodata/data compressed with LZ4; bit 3-5: verify hash on load), three (file offset, memory offset, size) segment descriptors, bss size, 32-byte module id (build id), compressed segment sizes, dynstr and dynsym extents, and three SHA-256 hashes of the decompressed segments (header total 0x100 bytes). Corrections from source: hactool places the dynstr and dynsym extents as two u64 at 0x90 and 0x98 (Atmosphere does not name them), and Atmosphere's flag word has eight bits, including PreventCodeReads and a Zstandard-with-BIC compression flag besides LZ4 (Fact:NSO/enum/NSO header flags). Unverified: that the extents are (offset, size) pairs relative to rodata, as the switchbrew page states; and the 0x1C/0x2C words as module name offset and size, which Atmosphere leaves unnamed. What the Atmosphere loader refuses: Fact:NSO/behavior/Atmosphere NSO checks.

Decompress each segment before analysis, load at the memory offsets, and apply the MOD0 header (Format:MOD0; its offset is stored at text+4 in libnx-built images, as in Format:NRO) for .dynamic. The module name may follow the header.

elf2nso (switch-tools) shows how a minimal NSO is produced: it takes the first three PT_LOAD segments of an AArch64 ELF as text, rodata and data, writes flags 0x3F, LZ4-compresses each segment, stores the SHA-256 of the decompressed bytes and copies the ELF's GNU build id note into the module id; see Fact:NSO/struct/NSO header as written by elf2nso. A KIP1 (Format:KIP1) is built the same way by elf2kip.

Related

Platform:Nintendo Switch, Format:NRO.

Address mapping in decompilation projects

The Switch decompilation projects write function addresses as the module's offset plus 0x7100000000, the base at which the main executable is mapped by the project's tools. Evidence: in zeldaret/botw data/uking_functions.csv the first function _init is at 0x0000007100000024, while OdysseyDecomp's data/file_list.yml lists the same kind of first entry (_init) at text offset 0x000024; its data_symbols.csv uses short forms such as 0x71018ff0e4. So address = 0x7100000000 + offset in the loaded image (text first, then rodata and data at their memory offsets from the header). Subtract 0x7100000000 before comparing with a raw NSO or loading into a disassembler at base 0.

The decompilation projects check the SHA-256 of the main NSO (compressed as shipped or uncompressed) and convert it to an ELF; see Software:The Legend of Zelda: Breath of the Wild and Software:Super Mario Odyssey for the published hashes, and Tool:Nx-decomp-tools. Unverified: the 0x7100000000 base is the one these projects use; the OS may load a process at a different address.

Code & repositories

  • https://github.com/switchbrew/switch-tools @ 22756068dd0ed6ff9734c59cb4f99ebd3f62555b · license: ISC
    switch-tools (ISC): src/npdmtool.c (builds NPDM from JSON), src/elf2nso.c (NSO header and segments), src/elf2kip.c (KIP1 header and capability encoding).
    Tested on: source read, not run · checked 2026-10-19; last activity 2024-10-23
  • https://github.com/Atmosphere-NX/Atmosphere @ 6b0c077b4c608a3a2ee712b8dc35fee87ceb62e8 · license: GPL-2.0-or-later (declared by the contributor for the files used; GitHub reports GPL-2.0 for the repository)
    Atmosphere (GPL-2.0): libraries/libstratosphere/include/stratosphere/ldr/ldr_types.hpp (NsoHeader, Npdm, Acid, Aci), stratosphere/loader/source/ldr_process_creation.cpp and ldr_meta.cpp (what the process loader checks).
    Tested on: source read, not run · checked 2026-10-19; last activity 2026-10-16; Note: the latest release ships binaries; the wiki links only the source, never the binaries
  • https://github.com/SciresM/hactool @ 1d64a83450e025622f3468c28fc4164dad2c5ef6 · license: ISC
    hactool (ISC): nso.h and nso.c (nso0_header_t, LZ4 decompression, segment hash check).
    Tested on: source read, not run · checked 2026-10-19; last activity 2023-12-04; Note: the latest release ships binaries; the wiki links only the source, never the binaries