Cet article est pour le format de fichier DOL. Voir DOL (Gotcha Force) pour les recherches en cours sur les dol Gotcha Force.
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.
BootInfo2 (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
L'organisation globale de la mémoire décrit comment l'adressage utilisé dans le dol permet d'accéder aux différents composants matériels de la GameCube. Ceci est très intéressant notamment pour les accès aux différents bus / interfaces.
| Mapping mémoire | |||
|---|---|---|---|
| Début | Fin | Taille | Description |
| 0x00000000 | 0x017fffff | 24MB | Adresses physique de la RAM |
| 0x80000000 | 0x817fffff | 24MB | Adresses logiques (Virtuelles) de la RAM, mises en cache |
| 0xC0000000 | 0xC17fffff | 24MB | Adresses logiques (Virtuelles) de la RAM, sans cache |
| 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 (mappé ici lors du boot) | |
La taille des registres matériels semble être renseignée dans un module Ghidra permettant de loader les fichiers dol.
Mémoire du programme (dol)
L'espace où le dol peut être chargé se situe dans les 24MB de la RAM en adressage virtuel mis en cache, des adresses 0x80003100 à 0x80700000 en matériel de production, ou 0x81200000 pour le matériel de développement.
Les 0x3100 premiers octets contiennent des informations système ("Dolphin OS Globals") notamment les routines appelées lors des interruptions spécifique à powerpc. On y retrouvera aussi tout un tas d'information sur l'iso ou encore l'offset de la FST etc.
| Mapping mémoire | |||
|---|---|---|---|
| Adresse | Description | ||
| 0x80003100 | Début du mapping des sections .text (généralement) | ||
| 0x80003140 | Entry point (early SDK v1.0 applications) | ||
| ? | Stack - à la suite de la dernière section avec une taille par défaut de 0x10000 octets | ||
| ? | ArenaLo - Bas de la mémoire tas (Heap) - initialisé par l'OS (SDK) à la suite de la pile | ||
| 0x81200000 | Adresse de chargement de l'Apploader | ||
| 0x81300000 | Adresse de chargement du Bootrom/IPL | ||
| ? | ArenaHi - Haut de la mémoire tas (Heap) - initialisé par l'OS (SDK) collé à la FST | ||
| ? | FST - Taille variable - collée à la fin de l'adressage virtuel | ||
| 0x81800000 | Fin de l'adressage virtuel | ||
Il est tout d'abord intéressant de noter que la mémoire tas contient l'apploader et la bootrom/IPL. Elle est allouée via l'api du SDK.
Le dol peut être mappé de 0x80003100 à 0x80700000 en production, ce qui laisse 7.3 Mo pour le programme.
La FST est chargée en fonction de son positionnement par rapport au dol dans l'iso/GCM:
- dol_offset_FST < dol_offset_iso -> virtual_address_FST > dol_address_FST
- dol_offset_FST > dol_offset_iso -> virtual_address_FST < dol_address_FST
Sections
On remarquera le comportement important de 4 registres spécialisés :
- R1 pointe sur la pile. On soustraira l'espace nécessaire pour chaque frame de fonctions. Les fonctions terminales (n'appelant pas de fonctions) n'auront pas forcément besoin de frame.
- R2 pointe sur le __SDA2_BASE__ Small Data Anchor en lecture seule. On trouvera les sections .sdata2 (constantes initialisées) ou .sbss2 (constantes non initialisées).
- R13 pointe sur le __SDA_BASE__ Small Data Anchor en lecture / écriture. On trouvera le .sdata (variables initialisées) ou .sbss (non initialisées.)
- R0 lors qu'il est utilisé avec un offset ne tient pas compte de sa valeur. Il permet d'adresser les 0x8000 premiers octets de l'espace d'adresse ou les 0x7fff derniers octets de l'espace d'adresses. (signed short)
Les SDA sont adressé avec un offset signed short (-0x8000 +0x7FFF). Lors de l'arrivée sur l'entrypoint, R1 R2 et R13 pointent sur l'espace de la Bootrom/IPL. La première fonction __init_registers leur donne alors une valeur dans l'espace d'adressage du dol recoupant souvent les sections .data et .bss initialement mappées dans le dol.
On retrouvera souvent les sections data dans cet ordre du fait de leur origine en format ELF32 :
- .ctors
- .dtors
- .rodata
- .data
- .bss
- .sdata (on vérifiera avec -0x8000(R13)
- .sbss
- .sdata2 (on vérifiera avec -0x8000(R2)
- .sbss2
- Suivi par la fin de la stack (0x10000 octets par défaut)
- Suivi par ArenaLo, le début de la mémoire tas généré par l'OS du SDK
- Apploader chargé en 81200000
- Bootrom/IPL chargé en 81300000
- ArenaHi collé à la FST
- FST collé à la fin de la mémoire (81800000)
On remarquera deux API du SDK OS gérant la mémoire tas : OSAllocFromArenaHi & OSAllocFromArenaLo.
DI - DVD Interface
Le driver qui permet d'accéder au DVD utilise la puce MN102 documentée sur yagcd. On trouvera les sources d'un plugin MN102 IDA Pro sur le site de la team Hitmen.
Documentation sur la lecture du disque.
EXI - External Interface
Les sources de Dolphin Emulator montrent l'usage de EXI. On y retrouve MemoryCard, MaskROM, AD16, Microphone, Ethernet, AGP, EthernetXLink, EthernetTapServer.
SI - Serial Interface
Les sources de Dolphin Emulator donnent des indices sur l'usage du registre hardaware SI. On y retrouve la connexion des périphériques GBA (Game Boy Advance), CONTROLLER, KEYBOARD, STEERING, TARUKONGA. L'interface SI utilise le protocole Joybus.
Logiciels
Ces logiciels ci-dessous permettent de manipuler les fichiers dol :
- doltool.py, proposé par Virtual World RE.
- GeckoLoader, proposé par JoshuaMKW, sup32.