DOL (File format)

← Gotcha Force

This article is for the DOL file format. See DOL (Gotcha Force) for current research on Gotcha Force DOL.

DOL files (from the GameCube codename dolphin) are files found in iso/GCM GameCube and Wii files. Observations below concern only GameCube dol. Before being a dol the file was in ELF file format compiled from C sources with the GameCube SDK. All libs are staticly linked but in some dols we found some kind of external code loaded in the REL format.

Boot Info 2 (BI2) dol configuration

For performances optimizations it is advisable to keep a max loaded length of 4Mb. This restriction is enabled by default with the DolLimit setting set to 4Mb in the BI2. This limit is often disabled by developpers. Code in .rel can be dynamically relocated and loaded by SDK OS lib (OSSetBootDol).

• In developpement boards we can map sections in virtual memory up to 0x81200000.
• In production boards we can map sections in virtual memory up to 0x80700000.

After this limits the apploader will raise an error.

Format

The dol is a iso/GCM GameCube system file and is placed independently of the mini DVD user space (FST). The dol offset is stored in the boot.bin:0x420 at the beginning of the GCM/iso.

Header

The dol header has a length of 0x100 bytes which describe how the dol must be loaded in virtual memory and how to prepare this memory.

Dol header
Offset	Length	Description
0x000	4 × 18	Sections offsets - It tells where the section datas begin relative from the dol start. 0 for unused section.
0x048	4 × 18	Sections virtual addresses - It tells where we load section datas in virtual memory. 0 for unused section.
0x090	4 × 18	Sections length in bytes. 0 for unused section.
0x0d8	4	bss virtual address - Where bss start in virtual memory. bss areas are 0 initialized.
0x0dc	4	bss length in bytes.
0x0e0	4	Entry point - Virtual address where we start executing when the dol has been loaded. This function shouldn't terminate.
0x0e4	0x1c	Padding.
0x100	Header end. Start of section datas.

The first 7 sections are .text section containing executable code. We can find interrupts handlers or padding in it.

The 11 next sections are for .data containing initialized datas.

The .bss interval can contain .data or .text sections in it. If this is the case then the .bss is splited to not override existing sections and only out parts are keeped.

All section have to be aligned to 32 bytes. The apploader align all section length to upper 32 bytes

Memory organization

Yet Another GameCube Documentation / YAGCD provide a very good documentation on memory organization.

Memory global organization

Global memory organization describe how addressing used in the dol allow to access the differents GameCube hardware composants. This is really interesting to understand the bus / interfaces access.

Memory mapping
Begin	End	Length	Description
0x00000000	0x017fffff	24MB	Physical address of the RAM
0x80000000	0x817fffff	24MB	Logical address of the RAM, cached
0xC0000000	0xC17fffff	24MB	Logical address of the RAM, not cached
0xc8000000		2MB	Embedded Framebuffer (EFB)
0xCC000000			Hardware registers
0xCC000000			CP - Command Processor
0xCC001000			PE - Pixel Engine
0xCC002000			VI - Video Interface
0xCC003000			PI - Processor Interface (Interrupt Interface)
0xCC004000			MI - Memory Interface
0xCC005000			AI - Audio Interface
0xCC006000			DI - DVD Interface
0xCC006400			SI - Serial Interface
0xCC006800			EXI - External Interface
0xCC006C00			Streaming Interface
0xCC008000			GX FIFO (Graphic display lists)
0xe0000000	0xe0003fff	16k	L2 Cache
0xfff00000		1MB	IPL (mapped here at bootup)

Hardware registers length and composition is detailed here.

User program area (dol)

As seen above the dol is mapped in the 24MB of RAM in virtual cached address space from 0x80003100 to 0x80700000 in production boards, and 0x81200000 in development boards.

The first 0x3100 bytes contains system informations ("Dolphin OS Globals") with globals variables and also interrupts handlers specific to powerpc architecture. This informations are interesting when creating a dol loader resolving cross references inside the code.

Memory map
Adress	Description
0x80003100	Start of mapped sections .text (usually)
0x80003140	Entry point (early SDK v1.0 applications)
?	Stack - After the last section with a default length of 0x10000 bytes
?	ArenaLo - Bottom of the Area initialized by the OS (SDK) after the Stack
0x81200000	Load Address of the Apploader
0x81300000	Load Address of Bootrom/IPL
?	ArenaHi - Top of the Area initialized by the OS (SDK) stuck to the FST
?	FST - Variable length - Stuck to the end of virtual cached memory space.
0x81800000	End of the virtual cached memory space (24MB)

The Area contains the apploader and the bootrom/IPL. This area is allocated by the SDK api and is used to create and destroy Heaps in it.

The dol can be mapped from 0x80003100 to 0x80700000 in production boards leaving 7.3 MB for the program.

The FST is loaded in virtual memory deppending to it's position from the dol in the GCM/iso:

• FST_offset(iso) < dol_offset(iso) -> FST_virtual_address > dol_virtual_address
• FST_offset(iso) > dol_offset(iso) -> FST_virtual_address < dol_virtual_address

Sections

The PowerPc Embedded Application Binary Interface (EABI) describe 4 special registers:

• R1 is the stack pointer. We substract the space needed from it when entering in a function (Stack Frame). Terminal functions (thoose which don't call any functions) don't always need a frame.
• R2 is the read only Small Data Anchor __SDA2_BASE__ addressed with a signed short offset. It correspond to the .sdata2 (initialized constants) or .sbss2 (uninitialized constants).
• R13 is the Read / Write Small Data Anchor __SDA_BASE__ also addressed with a signed short offset. It correspond to the .sdata (initialized variables) or .sbss (uninitialized variables).
• R0 when used with an offset don't care about it's value. It allow to address 0x8000 first bytes of memory space and 0x7fff last bytes (signed short).

As said above SDA are used with a signed short offset (-0x8000 +0x7FFF). When we reach the entry_point then R1 R2 and R13 are pointer in the Bootrom/IPL. The first function __init_registers initialize them for executing the dol and we can see that it's set to the beginning of some .data and .bss sections.

We found this section originally build in the ELF32 file format:

• .ctors
• .dtors
• .rodata
• .data
• .bss
• .sdata (should correspond to -0x8000(R13)
• .sbss
• .sdata2 (should correspond to -0x8000(R2)
• .sbss2
• Followed by the stack (by default 0x10000 bytes length)
• Followed by ArenaLo initialized by the SDK
• Apploader loaded at address 81200000
• Bootrom/IPL loaded at address 81300000
• ArenaHi stuck to the FST
• FST stuck to the end of memory (81800000)

The SDK offer two functions for handling Arena: OSAllocFromArenaHi & OSAllocFromArenaLo. But the main program initialize a number of Heaps in it and Create / Destroy them as it need.

DI - DVD Interface

The driver handling DVD accesses use the chip MN102 documented on yagcd. The Hitmen team has programmed a plugin for it: MN102 IDA Pro.

Some more documentation on disc reads.

EXI - External Interface

Dolphin Emulator sources show how EXI is used: MemoryCard, MaskROM, AD16, Microphone, Ethernet, AGP, EthernetXLink, EthernetTapServer.

SI - Serial Interface

Dolphin Emulator sources show devices using SI. We found this devices: GBA (Game Boy Advance), CONTROLLER, KEYBOARD, STEERING, TARUKONGA. The Serial Interface use the Joybus protocol.

Softwares

This softwares can handle dol files:

• doltool.py - Virtual World RE.
• GeckoLoader, - JoshuaMKW, sup32.