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.
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:
|RAM Entry Point
|CPU will begin execution here if mulitboot was installed from another GBA
|Leave at 0 - the BIOS will overwrite this depending on how the payload was downloaded
|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)
|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.
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:
- Prepare a "Multiboot Parameter Structure" in RAM. It should be
0x4c bytes long and contain the following fields at these addresses:
|Will be filled in later
|Will be filled in later using random data send by the clients
|Data controlling the color of the Nintendo logo on client devices - of the form 0b1CCCDSS1, where C=color, D=direction, and S=speed
|Will be filled in with each of bits 1-3 set if client 1-3 is detected
|The start address of the payload after the cartridge header
|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
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.
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.
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.
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).
0x6200, followed by
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.
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.
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).
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.