[marian-m12l]

This is my attempt at designing an API to support the GameCube Game Boy Advance cable (DOL-011).

The PR contains:

• Module gba_link with support for basic GBA Link Cable support (status, read/write Joybus commands)
• Module gba_link_multiboot for Multi Boot support (to upload a rom to a GBA while it's booting; this is a feature of the GBA BIOS)
• Example gbalink that demonstrates the APIs, including a very basic GBA rom

I believe @meeq is also working on a similar API, but I still wanted to give it a go on my own. Feel free to dismiss the PR, but hopefully it's helpful to some degree.

[marian-m12l]

While working on this API I noticed that the GameCube Game Boy Advance protocol is not greatly documented. I fixed the GBA Read/Write Joybus commands on n64brew.dev wiki, but I'm unsure whether a detailed documentation for Multi Boot over Joybus fits the wiki.

Here is my draft for such a documentation.

GBA Multi Boot protocol

When powering on a GBA, its BIOS listens to incoming serial data on several wire protocols, including JoyBus. The host console (GameCube or N64) can load a so-called Multi Boot ROM (with a specific additional header) up to 256 KiB large into the GBA WRAM, using commands 0x14 and 0x15. The steps for the Multi Boot protocol are listed below.

Multi Boot ROM

Any ROM sent over Multi Boot must be designed specifically. It must reside in WRAM, and contain an additional header:

Offset	Size	Name	Description
0xC0	0x4	RAM Entry Point	A 32bit ARM branch opcode, eg. "B ram_start"
0xC4	0x1	Boot mode	Generally set to 0x00. The slave GBA download procedure overwrites this byte by a value which is indicating the used Multi Boot transfer mode (0x01 for JoyBus mode).
0xC5	0x1	Slave ID number	Identifies the device. Value can be set in the range [1-3] to indicate the console's position.
0xC6	0x1A	Reserved	This field is unused.
0xE0	0x4	JoyBus Entry Point	If the GBA has been booted by using Joybus transfer mode, then the entry point is located at this address rather than at 0xC0. Either put your initialization procedure directly at this address, or redirect to the actual boot procedure by depositing a "B " opcode here (either one using 32bit ARM code).

GBA Readiness

The GBA BIOS cycles through its supported protocols, and may not respond to the JoyBus Info command (0x00).
The device should be polled until responding with identifier 0x0004. The third byte in the response contains the lower 8 bits of GBA's JOYSTAT register. Poll until bits 4 and 5 are high, indicating GBA is ready to initiate Multi Boot.

Read key A

First, emit command 0x14 to read a 4-bytes word from the GBA. The response is a random session key that must be used to cipher the payload later on.
Compute the session key (key A) by XOR'ing with secret key "sedo" (0x7365646f), then swap the bytes.

Compute key B

Key B is calculated on the host console. It is not random, but computed from the payload length and logo configuration.

• '''Payload length''' corresponds to the byte-length of the whole ROM being transferred. The effective payload length must be in range [0x200-0x40000]. Length must be rounded up to the nearest 8-bytes boundary if necessary. Whether padding value for the last few bytes matters is unknown. When computing key B, the payload length is transformed: substract 512, then shift right by 3 ranks (effectively dividing by 8). This results in a 14-bits value, that is slightly mangled as described in the table below.

• '''Logo settings''' gives some control on how the Nintendo logo is displayed on the GBA during transfer. Two parameters can be customized: the color of the logo and speed/direction of the color-switching animation.

Color takes a value between 0 and 6 and determines the "base" color for the animation.

Animation takes a values between -4 and 4. A value of 0 results in a fixed logo. Negative and positive values result in the logo switching between two colors: the base color and the following color. Sign indicates whether the animation starts from the base color (positive value) or from the following color (negative value). The higher the value, the faster the animation.

The table below summarizes the possible values and their visible result:

Color	Animation	Result
0 (${\color{pink}pink}$)	+<n>	${\color{pink}pink}$ to ${\color{blue}blue}$
	0	Solid ${\color{pink}pink}$
	-<n>	${\color{blue}blue}$ to ${\color{pink}pink}$
1 (${\color{blue}blue}$)	+<n>	${\color{blue}blue}$ to ${\color{cyan}cyan}$
	0	Solid ${\color{blue}blue}$
	-<n>	${\color{cyan}cyan}$ to ${\color{blue}blue}$
2 (${\color{cyan}cyan}$)	+<n>	${\color{cyan}cyan}$ to ${\color{green}green}$
	0	Solid ${\color{cyan}cyan}$
	-<n>	${\color{green}green}$ to ${\color{cyan}cyan}$
3 (${\color{green}green}$)	+<n>	${\color{green}green}$ to ${\color{yellow}yellow}$
	0	Solid ${\color{green}green}$
	-<n>	${\color{yellow}yellow}$ to ${\color{green}green}$
4 (${\color{yellow}yellow}$)	+<n>	${\color{yellow}yellow}$ to ${\color{red}red}$
	0	Solid ${\color{yellow}yellow}$
	-<n>	${\color{red}red}$ to ${\color{yellow}yellow}$
5 (${\color{red}red}$)	+<n>	${\color{red}red}$ to ${\color{pink}pink}$
	0	Solid ${\color{red}red}$
	-<n>	${\color{pink}pink}$ to ${\color{red}red}$
6 (${\color{pink}pink}$)	+<n>	${\color{pink}pink}$ to ${\color{white}white}$
	0	Solid ${\color{pink}pink}$
	-<n>	${\color{white}white}$ to ${\color{pink}pink}$

Logo configuration is encoded over 6 bits, depending on the sign of the animation setting, as shown in the table below:

Logo settings encoding
Animation < 0	—	—	5	4	3	2	1	0
	—	—	Color[2:0]			(|Animation|+3)[2:0]
Animation == 0	—	—	5	4	3	2	1	0
	—	—	1	1	1	Color[2:0]
Animation > 0	—	—	5	4	3	2	1	0
	—	—	Color[2:0]			(Animation-1)[2:0]

• '''Checksum''' is computed from the incomplete key B, composed only of the Payloed length and Logo data. It is defined as the sum of the three lower bytes, of which only the lowest 7 bits are preserved.

• '''Fixed bits''': bits 31, 23, 15, and 7 are always set to 1.

The table below shows how all these elements are mangled in the 4-byte word:

KEY B (before XOR)
31:24	31	30	29	28	27	26	25	24
	1	Checksum[6:0]
23:16	23	22	21	20	19	18	17	16
	1	Logo[5:0]						Lenth[14]
15:8	15	14	13	12	11	10	9	8
	1	Length[13:7]
7:0	7	6	5	4	3	2	1	0
	1	Length[6:0]

Finally, key B is obtained by XOR'ing with secret key, chosen from the value of bit 9 ("sedo" (0x7365646f) if bit 9 is set, "Kawa" (0x4b617761) otherwise).

Emit command 0x15 to write the 4-bytes key B to the GBA.

Send clear header

The ROM header (i.e. the first 0xc0 bytes of the ROM) is sent as cleartext. Simply emit commands 0x15 to write each 4-bytes word to the GBA.

Send the remaining of the payload

The remaining of the ROM, starting from offset 0xC0, up to the payload length rounded up to the nearest 8-bytes boundary, is ciphered using key A.

For each 4-bytes word remaining in the ROM, follow the algorithm (in pseudo-code):

swapped = swap(data)
keyA = (keyA * 0x6177614B) + 1;   // "Kawa"
swapped = swapped ^ keyA;
swapped = swapped ^ ((~(i + (0x20<<20))) + 1);
swapped = swapped ^ 0x20796220; // " by "
cipherText = swap(swapped)

Ciphertext is sent to the GBA by emitting 0x15 commands.

A CRC is calculated on the cleartext data during this phase. Its initial value is 0x15a0.

For each 4-bytes word, CRC is updated using the following algorithm (in pseudo-code):

for i in [0:31]
  if ((crc ^ data) & 1) {
    crc = crc >> 1;
    crc = crc ^ 0xa1c1;
  } else {
    crc = crc >> 1;
  }
  data = data >> 1;
}

Send CRC

After the ROM payload has been transferred, the CRC is combined with the payload length and ciphered before being sent to the GBA.

crc = crc | (rounded_payload_length << 16);

Read and check dummy word

At this point, the GBA will boot into the uploaded ROM. It is however possible to read a "dummy" word using command 0x14.

The value received from the GBA should match one of :

• ciphered word at address 0x1f8 * ciphered word at address 0x1fc
• clear word at address 0x1f8 * clear word at address 0x1fc
• clear word at address 0x1f8 * ciphered word at address 0x1fc

[MesaBlack]

What is this, GBA to N64 compatibility?

[meeq]

What is this, GBA to N64 compatibility?

Yes, you can make an adapter to plug the GameCube GBA Link Cable into the N64 Controller Port: https://github.com/meeq/joybus-adapter

[MesaBlack]

would that mean an N64 game communicates with a GBA game to unlock stuff on the former?

[marian-m12l]

would that mean an N64 game communicates with a GBA game to unlock stuff on the former?

It means you have a (slow) serial link that the N64 can use to communicate with the GBA via read/write commands. What you do with it is up to you.

Notably, the GBA BIOS can receive a specially-crafted rom over Joybus, so you can upload the rom directly from the N64, no cartridge needed on the GBA.

[MesaBlack]

ok, so game in the Boy Advancee is optional, just like on GameCube.