libdragon SDK

Libdragon IPL3 is an open-source bootcode required in each ROM to perform final hardware initializations (specifically RDRAM initialization and configuration) and load/run the main binary.

Key features include:

• ELF Loading: Searches for and loads an ELF file appended to the IPL3. Supports both 32-bit and 64-bit ELFs.
• Compression Support: Supports compressed ELFs where the ELF provides its own decompression function.
• High Performance: Boots large ELFs significantly faster than Nintendo's original IPL3.
• Flexibility: Supports ROMs of any size (even < 1 MiB) and does not require a header checksum.
• Reliability: Clears RDRAM before booting to ensure consistent behavior between emulators and real hardware.
• Entropy: Collects entropy during boot, providing a 32-bit random integer to the application.
• Development Mode: A version (ipl3_dev.z64) exists with a pre-signed trampoline (no need to sign every change) and a debugging library for USB/emulator logging.
• Compatibility: Works on iQue consoles and offers a compat build for legacy build systems.

The rect_pack library is a C++17 tool for packing rectangles into one or more sprite sheets or atlases. To use it, you provide a Settings object defining your constraints and a list of Size objects representing the rectangles you want to pack. The pack function returns a std::vector<Sheet>, where each Sheet contains the dimensions and the list of Rect objects (with their x, y, width, height, and rotated status) that fit within it.

Note on IDs: The id field in the input Size struct is used to correlate input rectangles with their output positions in the Rect struct. If a rectangle does not fit within the provided constraints, it will not appear in any returned Sheet.

#include <vector>
#include "rect_pack.h"

// Example usage concept:
rect_pack::Settings settings = { /* ... initialize settings ... */ };
std::vector<rect_pack::Size> sizes = { {1, 32, 32}, {2, 64, 64} };

std::vector<rect_pack::Sheet> sheets = rect_pack::pack(settings, sizes);

for (const auto& sheet : sheets) {
    for (const auto& rect : sheet.rects) {
        // Use rect.id to match back to the original size
        // rect.x, rect.y, rect.width, rect.height, rect.rotated
    }
}

By default, Libdragon uses this IPL3 via the n64tool application embedded in n64.mk. Standard libdragon applications will use it automatically.

If you are using your own programming environment, follow these requirements:

ELF Requirements

• Format: Provide a statically-linked ELF file.
• Alignment: The ELF file must be concatenated to the IPL3 .z64 file and must be 256-byte aligned. You can add other data before/after as long as the ELF remains 256-byte aligned.
• Segments:
  • All PT_LOAD segments will be loaded.
  • Virtual addresses must be 8-byte aligned.
  • File offsets must be 2-byte aligned.
  • Constraint: Do not load segments into the last 64 KiB of RDRAM, as this is reserved for IPL3.
• Header: IPL3 ignores the 64-byte ROM header.

Boot Flags (passed in DMEM)

IPL3 passes boot flags to your application at the beginning of DMEM. The layout is:

• Byte 0..3: Amount of memory (in bytes).
• Byte 4..7: 32-bit random number (entropy).
• Byte 8: ROM type (0: Cartridge at 0x10000000, 1: 64DD IPL at 0x06000000).
• Byte 9: TV type (0: PAL, 1: NTSC, 2: MPAL).
• Byte 10: Reset type (0: cold, 1: warm).
• Byte 11: Console type (0: n64, 1: iQue).
• Byte 12..13: Offset of the ELF header in ROM (in 256-byte pages; multiply by 256 for byte offset).
• Byte 14..15: Reserved.

Register State

• $sp (Stack Pointer) points to the end of the available RDRAM.

Pre-built binaries are available in the bin directory. You can build them from source using the provided Makefile.

Build Development Version

Creates ipl3_dev.z64. Includes full debug support and a pre-signed trampoline.

$ make

Build Production Version

Creates ipl3_prod.z64. This version is non-debug and must be correctly signed (e.g., using ipl3hasher) before use on real hardware.

$ make clean
$ make PROD=1

Build Compatibility Version

Creates ipl3_compat.z64. Also requires signing for real hardware.

$ make clean
$ make COMPAT=1

Integrating a custom IPL3 into your project

If you have built a custom ipl3_dev.z64 and want to test it with your game:

1. Add N64_ROM_HEADER=<path/to/ipl3_dev.z64> to your game's Makefile using n64.mk.
2. Alternatively, run make install in the IPL3 directory to embed it into n64tool by default (requires rebuilding n64tool).