This article is for the DOL file format. See DOL (Gotcha Force) for current research on Gotcha Force DOL.
|
This file format needs more research. Researches on headers / bodies structures are partially achieved. |
DOL files (from the GameCube codename dolphin) are files found in iso/GCM GameCube and Wii files. The 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 performance 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 developers. Code in .rel can be dynamically relocated and loaded by SDK OS lib (OSSetBootDol).
- In development 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 an 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 data begins relative from the dol start. 0 for unused section. |
| 0x048 | 4 × 18 | Sections virtual addresses - It tells where we load section data in virtual memory. 0 for unused section. |
| 0x090 | 4 × 18 | Sections lengths 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 data. | |
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 data.
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 kept.
All sections 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
The global memory organization describes how addressing used in the dol allow to access the different GameCube hardware components. This is really interesting and help to understand how to access busses / interfaces.
| 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 boot up) | |
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 contain system information ("Dolphin OS Globals") with global variables and also interrupts handlers specific to powerpc architecture. Those informations are interesting when creating a dol loader resolving cross references inside the code.
| Memory map | |||
|---|---|---|---|
| Address | 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 depending to its 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) describes 4 special registers:
- R1 is the stack pointer. We subtract the space needed from it when entering in a function (Stack Frame). Terminal functions (those 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 corresponds 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 corresponds to the .sdata (initialized variables) or .sbss (uninitialized variables).
- R0 when used with an offset don't care about its value. It allows 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 pointing 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 offers two functions for handling Arena: OSAllocFromArenaHi & OSAllocFromArenaLo. But the main program initializes a number of Heaps in it and Create / Destroy them as it needs.
DI - DVD Interface
The driver handling DVD accesses uses 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 these devices: GBA (Game Boy Advance), CONTROLLER, KEYBOARD, STEERING, TARUKONGA. The Serial Interface uses the Joybus protocol.
Softwares
These softwares can handle dol files:
- doltool.py - Virtual World RE.
- GeckoLoader, - JoshuaMKW, sup32.