Skip to content

Latest commit

 

History

History
140 lines (138 loc) · 7.29 KB

multiboot.md

File metadata and controls

140 lines (138 loc) · 7.29 KB

🌎 From: https://retrocomputing.stackexchange.com/questions/14317/what-is-the-protocol-for-bootstrapping-a-game-boy-advance-over-a-link-cable 🌎

According to the documentation for the no$ emulators (https://www.problemkaputt.de/gbatek.htm), the core of the GBA's multiboot functionality revolves a BIOS syscall, SWI 0x25. The GBA's boot firmware will naturally look for and start communicating on any connection mode it supports (be it the normal serial mode, MultiPlay mode, or JOYBUS mode) - after the host GBA establishes a communcation session and sends handshake and header data, this syscall will send the multiboot payload to each connected GBA, verify with a CRC checksum, and begin execution.

Payload Structure

The multiboot payload resides at 0x02000000 on the client GBA, which is the location corresponding to 256KB of external work RAM. The first 192 bytes are the same as a cartridge payload (entry point, Nintendo logo, game title, etc.), followed by these entries specific to multiboot payloads:

Address Bytes Label Comment
0x0c0 4 RAM Entry Point CPU will begin execution here if mulitboot was installed from another GBA
0x0c4 1 Boot Mode Leave at 0 - the BIOS will overwrite this depending on how the payload was downloaded
0x0c5 1 Client ID number Leave at 0 - the BIOS will overwrite this with the player number minus 1 (e.g. player 4 will get 0x03 here)
0x0c6 26 Not used
0x0e0 4 JOYBUS Entry Point CPU will begin execution here if multiboot was installed via JOYBUS

As with the cartridge header, these entry points should be 32-bit ARM branch instructions leading to the actual start of the code (e.g. B ram_start). Execution in general should be relative to 0x02000000 instead of 0x08000000 as it is when executing from cartridge (you will likely compile the Multiboot payload separately and include the binary in your cartridge)

The cartridge header portion is not particularly special - in fact, since the cartridge header and remaining payload are sent in separate steps, you can plan on just sending the actual cartridge header here. The ROM entry point, normally found at the start of the cartridge header, will be ignored during multiboot.

Transfer Protocol

The latter half of the multiboot protocol (sending the payload and executing it) are handled by the SWI 0x25 syscall. The first half (initiating the session and sending the cartridge header) must be handled by the session host:

  1. Prepare a "Multiboot Parameter Structure" in RAM. It should be 0x4c bytes long and contain the following fields at these addresses:
Address Bytes Label Comment
0x14 1 handshake_data Will be filled in later
0x19 3 client_data Will be filled in later using random data send by the clients
0x1c 1 palette_data Data controlling the color of the Nintendo logo on client devices - of the form 0b1CCCDSS1, where C=color, D=direction, and S=speed
0x1e 1 client_bit Will be filled in with each of bits 1-3 set if client 1-3 is detected
0x20 4 boot_srcp The start address of the payload after the cartridge header
0x24 4 boot_endp The exclusive end address of the payload. The total transfer length should be a multiple of 0x10, with a minimum of 0x100 and a maximum of 0x3ff40

  1. Initiate a multiplayer communication session, using either Normal mode for a single client or MultiPlay mode for multiple clients. This is accomplished using the RCNT and SIOCNT registers as with a multiplayer game session.

  2. Send the word 0x6200 repeatedly until all detected clients respond with 0x720X, where X is their client number (1-3). If they fail to do this after 16 tries, delay 1/16s and go back to step 2.

    • Note that throughout this process, any clients that are not connected will always respond with 0xFFFF - be sure to ignore them.

  3. Fill in client_bit in the multiboot parameter structure (with bits 1-3 set according to which clients responded). Send the word 0x610Y, where Y is that same set of set bits.

  4. Send the cartridge header, 16 bits at a time, in little endian order. After each 16-bit send, the clients will respond with 0xNN0X, where NN is the number of words remaining and X is the client number. (Note that if transferring in the single-client 32-bit mode, you still need to send only 16 bits at a time).

  5. Send 0x6200, followed by 0x620Y again

  6. Send 0x63PP repeatedly, where PP is the palette_data you have picked earlier. Do this until the clients respond with 0x73CC, where CC is a random byte. Store these bytes in client_data in the parameter structure.

  7. Calculate the handshake_data byte and store it in the parameter structure. This should be calculated as 0x11 + the sum of the three client_data bytes. Send 0x64HH, where HH is the handshake_data.

  8. Call SWI 0x25, with r0 set to the address of the multiboot parameter structure and r1 set to the communication mode (0 for normal, 1 for MultiPlay).

  9. Upon return, r0 will be either 0 for success, or 1 for failure. If successful, all clients have received the multiboot program successfully and are now executing it - you can begin either further data transfer or a multiplayer game from here.

Code sample on Github using the Rust GBA crate: https://github.com/TheHans255/rust-gba-multiboot-test.

Reference: