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

Platform:Nintendo 64

From ReverseEngineering.wiki
Platform
Developer Nintendo
Uses Library:libdragon
Versions NUS-001 (1996); iQue Player (2003, China; 144 MHz CPU, no PIF/IPL2)
Endianness big
On this wiki Facts · Code · Notes · Topics

Nintendo's 64-bit home console (1996). A NEC VR4300 CPU (MIPS III, big endian, 93.75 MHz) and the Reality Coprocessor (RSP vector unit, RDP rasterizer and the I/O interfaces) share 4 MiB of RDRAM (8 MiB with the Expansion Pak). All hardware registers sit at physical 0x04000000-0x048FFFFF, the cartridge ROM at 0x10000000, and every cartridge boots through the PIF boot ROM and a 4 KiB IPL3 bootcode stored at the start of the ROM.

Overview

  • CPU: NEC VR4300 (MIPS III: 64-bit registers, FPU as COP1, TLB), big endian, 93.75 MHz. The COP0 Count register ticks at half the CPU clock (46,875,000 Hz), so timer constants in game code are multiples of that. On the iQue Player the CPU runs at 144 MHz and the RCP at 96 MHz.
  • RCP (Reality Coprocessor), 62.5 MHz: the RSP (a MIPS-like scalar + vector core with 4 KiB DMEM and 4 KiB IMEM that runs microcode uploaded by the game), the RDP (rasterizer fed with command lists) and the interfaces MI (interrupts), VI (video), AI (audio DAC), PI (cartridge bus), RI (RDRAM) and SI (serial link to the PIF, which talks to controllers, EEPROM and RTC).
  • RDRAM: 4 MiB, 8 MiB with the Expansion Pak; the IPL3 sizes it at boot and stores the size for the game.
  • SDKs: commercial games use Nintendo's libultra; homebrew mostly uses Library:libdragon, whose public-domain source is the evidence for most register facts here. Both drive the same registers.

Memory map

Physical Uncached (KSEG1) Contents
0x00000000 0xA0000000 RDRAM (cached view 0x80000000)
0x03F00000 0xA3F00000 RDRAM chip registers (0x03F80000 broadcast)
0x04000000 0xA4000000 RSP DMEM, 4 KiB
0x04001000 0xA4001000 RSP IMEM, 4 KiB
0x04040000 0xA4040000 SP registers (DMA, status, semaphore)
0x04080000 0xA4080000 SP PC
0x04100000 0xA4100000 DP command registers
0x04300000 0xA4300000 MI registers
0x04400000 0xA4400000 VI registers
0x04500000 0xA4500000 AI registers
0x04600000 0xA4600000 PI registers
0x04700000 0xA4700000 RI registers
0x04800000 0xA4800000 SI registers
0x06000000 0xA6000000 64DD IPL ROM (when the 64DD is attached)
0x10000000 0xB0000000 Cartridge ROM (PI domain 1)
0x1FC00000 0xBFC00000 PIF boot ROM
0x1FC007C0 0xBFC007C0 PIF RAM, 64 bytes

Game code runs from RDRAM in KSEG0 (0x80000000 + physical, cached), so code and data pointers are 0x80xxxxxx; hardware registers are accessed through KSEG1 (0xA0000000 + physical, uncached), so register accesses show up as lui $at, 0xA440 and similar. Normalise with addr & 0x1FFFFFFF before comparing addresses from different tools. Games do not execute from the cartridge: code and data are copied to RDRAM by PI DMA.

Boot sequence

  1. The PIF boot ROM (IPL1/IPL2) runs on the CPU from 0xBFC00000. It copies the first 4 KiB of the cartridge (the 64-byte header plus the IPL3) into RSP DMEM at 0xA4000000, has the cartridge's CIC lockout chip check a hash of DMEM 0x040-0xFFF (see Format:Nintendo 64 ROM image#Boot code (IPL3) and CIC) and jumps to 0xA4000040.
  2. IPL2 hands boot flags to IPL3 in registers: s3 ROM type (0 cartridge, 1 64DD), s4 TV type (0 PAL, 1 NTSC, 2 MPAL), s5 reset type (0 cold, 1 warm), s6 CIC seed, s7 version.
  3. Nintendo's IPL3 initialises RDRAM, copies 1 MiB from cartridge 0x10001000 (ROM offset 0x1000) to the entry point stored in header word 0x08 (usually 0x80000400), checks the two CRC words at header 0x10/0x14 over that data, stores the boot flags at 0x80000300-0x8000031B and jumps to the entry point. Everything after the first megabyte is loaded later by the game itself.
  4. The game must then write 0x08 to PIF RAM offset 0x3C (0xBFC007FC) to finish the PIF boot; without it the PIF halts the CPU after about 5 seconds. Nintendo's IPL3 leaves this write to the game (libultra's start-up code does it); libdragon's IPL3 does it itself.

Low-memory boot flags written by Nintendo's IPL3 and by libdragon's compatibility IPL3:

Address Contents
0x80000300 TV type (0 PAL, 1 NTSC, 2 MPAL)
0x80000304 ROM type (0 cartridge, 1 64DD)
0x80000308 ROM base: 0xB0000000 cartridge, 0xA6000000 64DD
0x8000030C reset type (0 cold, 1 warm)
0x80000314 IPL2 version
0x80000318 RDRAM size in bytes (0x400000 or 0x800000)

libultra names these osTvType, osRomType, osRomBase, osResetType, osVersion and osMemSize, with osCicId at 0x80000310 and osAppNMIBuffer at 0x8000031C. Source: the Super Mario 64 decompilation defines them as fixed symbols in lib/asm/parameters.s (osTvType 0x80000300 through osAppNmiBuffer 0x8000031C) and declares them in include/PR/os.h (commit 9921382a68; osAppNMIBuffer is an array; the next symbol in the file, __osBbEepromAddress, is at 0x8000035C, which leaves 64 bytes for it). Test: search a game's boot segment for lw from 0x80000318 near the code that sizes the heap.

Controllers and the PIF (Joybus)

Controllers, Controller/Rumble/Transfer Paks, cartridge EEPROM and RTC are reached through the PIF: the CPU fills a 64-byte block in RDRAM, the SI DMA copies it to PIF RAM, the PIF runs it on the Joybus and the SI DMA copies the 64 bytes back. The block holds one command per port in order: a byte with the send length (including the command byte), a byte with the receive length, the command byte, the send data and room for the reply; a port is skipped with a single 0x00 byte, 0xFE ends the commands, and the last byte (0x3F) is the PIF control byte (0x01 = run the Joybus commands). Command bytes: 0x00 identify, 0x01 read controller, 0x02/0x03 accessory (pak) read/write in 32-byte blocks, 0x04/0x05 EEPROM read/write in 8-byte blocks, 0x06-0x08 RTC, 0xFF reset; see the Joybus facts of this page for the full list and the controller reply layout.

Timing constants

  • Count register: 46,875,000 Hz (CPU clock / 2); 72,000,000 Hz on iQue.
  • AI DAC clock: 48,681,818 Hz (NTSC), 49,656,530 Hz (PAL), 48,628,322 Hz (MPAL). The AI dacrate register holds round(clock / sample_rate) - 1, so an audio driver's sample rate can be recovered from the value it writes to 0xA4500010.

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
  • https://github.com/n64decomp/sm64 @ 9921382a68bb0c865e5e45eb594d9c64db59b1af · license: CC0-1.0
    Matching decompilation of Super Mario 64 (jp, us, eu, sh, cn). Useful without building: README and sm64.*.sha1 (SHA-1 of every ROM), Makefile (IDO 5.3 flags, per-file overrides, iQue egcs), assets.json.
    Tested on: source read, not run: Read at commit 9921382: README, Makefile, sha1 files; not built · checked 2026-10-18; last activity 2024-02-04

Pitfalls

  • PI DMA register names are from RDRAM's point of view: writing a length to PI_WR_LEN (0xA460000C) copies cartridge to RDRAM (the common case), PI_RD_LEN (0xA4600008) copies RDRAM to the cartridge. Lengths are written as size - 1. A ROM-to-RAM loader is a write of the RDRAM address to 0xA4600000, the cartridge address (0x10000000 + ROM offset) to 0xA4600004 and the length - 1 to 0xA460000C.
  • Under Nintendo's IPL3, RAM = entry point + (ROM offset - 0x1000) holds only for the first megabyte. Further code is DMA'd by the game to addresses of its choice (overlays), so a ROM offset can only be mapped to RAM through the game's own DMA calls or segment tables.
  • ROM dumps come in three byte orders; check the first word before reading any field (Format:Nintendo 64 ROM image#Identification).
  • libdragon ROMs do not follow the 1 MiB-at-0x1000 rule at all: their IPL3 loads an ELF stored in the ROM (Library:libdragon#ROM layout).

Evidence & references

  • libdragon (public domain, github.com/DragonMinded/libdragon) at trunk commit e356bf3 and preview commit 39d0d60: register definitions in include/ (rsp.h, rdp.h, mi.h, dma.h, regsinternal.h) and src/vi.h, src/audio.c, src/joybus/; its open-source IPL3 in boot/ (ipl3.c for the IPL2 register hand-over and low-memory flags, loader.c for the PIF boot termination).
  • n64brew.dev (community hardware wiki), referenced by libdragon's own tools.