docs/r4.md

# R4
This file documents the extra card commands supported by the original R4. Note that the original R4 only supported non-HC SD cards. As such the commands can only address up to 4GB on a SD card. All extra card commands for the R4 are for game mode and use the scrambler for both command and data as is usual for game mode commands. Write data (not command) send from the DS to the card appears never to be scrambled by the DS card hardware, although the scrambler state itself does advance.

It appears that all R4 commands use 0 cycles of initial latency (L1) and 24 cycles of page latency (L2), with the 6.7 MHz clock. Card id commands are not patched and use the timings from the retail game rom header, but without L1 latency (that's what the sdk does). Those can be as fast as a single cycle of L2 latency, depending on the game. Failing to respond to card id reads will trigger a card pull-out response in retail games. The card id should never be adapted to the retail game being played and should stay equal to the one that the console received the very first time at boot in normal mode. The actual value of the card id does not seem to matter much, as long as bit 31 reflects the protocol version that should be used.

* `0000000000000000` - No idea what it does, sending back `0x00000000` works.
* `B000000000000000` - Get card info. Normally returns `0x000001F4`.
    * The dldi driver checks for `(cardInfo & 7) == 4` in the `isInserted` function.
* `B2XXXXXXXX000000` - Start save read at address `0xXXXXXXXX`.
    * Address should most likely be 512 byte aligned. Returns `0x00000001` while the card is busy performing the read and `0x00000000` once the data is available. This command is polled as long as the return value is 1.
* `B3XXXXXXXX000000` - Get save data at address `0xXXXXXXXX` that was previously requested by command `B2`.
    * Not sure if the address is actually used by the card or can be any dummy value. Returns the 512 byte block of save data.
* `B4XXXXXXXX000000` - Sets the address (`0xXXXXXXXX`) of the FAT entry for rom (lsb of address is 0) or save (lsb of address is 1).
    * This is a 2-byte aligned SD address. Returns `0x00000001` while the card is busy initializing the cluster map and `0x00000000` once ready. This command is polled as long as the return value is 1.
* `B6XXXXXXXX000000` - Start rom read at address `0xXXXXXXXX`.
    * Address should be 512 byte aligned. Returns `0x00000001` while the card is busy performing the read and `0x00000000` once the data is available. This command is polled as long as the return value is 1. The data can then be read with the standard `B7` command.
* `B9XXXXXXXX000000` - Start SD read at address `0xXXXXXXXX`.
    * Address is in bytes, but should be 512 byte aligned. Returns `0x000001F4` while the card is busy performing the read and `0x00000000` once the data is available. This command is polled as long as the return value is not zero.
* `BAXXXXXXXX000000` - Get SD data at address `0xXXXXXXXX` that was previously requested by command `B9`.
    * Not sure if the address is actually used by the card or can be any dummy value. Returns the 512 byte block of SD data.
* `BBXXXXXXXX000000` - Start SD write to address `0xXXXXXXXX`.
    * Address is in bytes, but should be 512 byte aligned. The command expects 512 bytes of data that will be written to the SD card.
* `BCXXXXXXXX000000` - Get SD write status.
    * Not sure if the address is actually used by the card or can be any dummy value. Returns `0x00000001` while the card is busy performing the write and `0x00000000` once done. This command is polled as long as the return value is 1.
* `BDXXXXXXXX000000` - Start save write to address `0xXXXXXXXX`.
    * Address should most likely be 512 byte aligned. The command expects 512 bytes of data that will be written to the save.
* `BEXXXXXXXX000000` - Get save write status.
    * Not sure if the address is actually used by the card or can be any dummy value. Returns `0x00000001` while the card is busy performing the write and `0x00000000` once done. This command is polled as long as the return value is 1.

When initializing the R4 for retail rom use it seems there are some `0000000000000000` dummy commands send. Not sure if that is actually needed to make it work. After that `B4` is used to initialize the cluster map for rom and save file. The save file should have already been created on the SD card by the software on the DS side. The retail game is patched by the DS side software to perform rom reads using the requesting mechanism (`B6`/`B7`) and to perform save reads and writes using the corresponding card commands (`B2`/`B3` and `BD`/`BE`) instead of SPI. The advantage of the requesting/feedback mechanism for rom reads is that the data can be read as soon as it is ready. SD cards can have varying read latency and without a feedback mechanism you'd always have to account for the worst case, which can be more than the maximum amount of latency that can be specified in the IO registers and would be awful for the performance.
Initial commit 2025-11-16 15:41:34 +01:00			`# R4`
			`This file documents the extra card commands supported by the original R4. Note that the original R4 only supported non-HC SD cards. As such the commands can only address up to 4GB on a SD card. All extra card commands for the R4 are for game mode and use the scrambler for both command and data as is usual for game mode commands. Write data (not command) send from the DS to the card appears never to be scrambled by the DS card hardware, although the scrambler state itself does advance.`

			It appears that all R4 commands use 0 cycles of initial latency (L1) and 24 cycles of page latency (L2), with the 6.7 MHz clock. Card id commands are not patched and use the timings from the retail game rom header, but without L1 latency (that's what the sdk does). Those can be as fast as a single cycle of L2 latency, depending on the game. Failing to respond to card id reads will trigger a card pull-out response in retail games. The card id should never be adapted to the retail game being played and should stay equal to the one that the console received the very first time at boot in normal mode. The actual value of the card id does not seem to matter much, as long as bit 31 reflects the protocol version that should be used.

			* `0000000000000000` - No idea what it does, sending back `0x00000000` works.
			* `B000000000000000` - Get card info. Normally returns `0x000001F4`.
			* The dldi driver checks for `(cardInfo & 7) == 4` in the `isInserted` function.
			* `B2XXXXXXXX000000` - Start save read at address `0xXXXXXXXX`.
			* Address should most likely be 512 byte aligned. Returns `0x00000001` while the card is busy performing the read and `0x00000000` once the data is available. This command is polled as long as the return value is 1.
			* `B3XXXXXXXX000000` - Get save data at address `0xXXXXXXXX` that was previously requested by command `B2`.
			`* Not sure if the address is actually used by the card or can be any dummy value. Returns the 512 byte block of save data.`
			* `B4XXXXXXXX000000` - Sets the address (`0xXXXXXXXX`) of the FAT entry for rom (lsb of address is 0) or save (lsb of address is 1).
			* This is a 2-byte aligned SD address. Returns `0x00000001` while the card is busy initializing the cluster map and `0x00000000` once ready. This command is polled as long as the return value is 1.
			* `B6XXXXXXXX000000` - Start rom read at address `0xXXXXXXXX`.
			* Address should be 512 byte aligned. Returns `0x00000001` while the card is busy performing the read and `0x00000000` once the data is available. This command is polled as long as the return value is 1. The data can then be read with the standard `B7` command.
			* `B9XXXXXXXX000000` - Start SD read at address `0xXXXXXXXX`.
			* Address is in bytes, but should be 512 byte aligned. Returns `0x000001F4` while the card is busy performing the read and `0x00000000` once the data is available. This command is polled as long as the return value is not zero.
			* `BAXXXXXXXX000000` - Get SD data at address `0xXXXXXXXX` that was previously requested by command `B9`.
			`* Not sure if the address is actually used by the card or can be any dummy value. Returns the 512 byte block of SD data.`
			* `BBXXXXXXXX000000` - Start SD write to address `0xXXXXXXXX`.
			`* Address is in bytes, but should be 512 byte aligned. The command expects 512 bytes of data that will be written to the SD card.`
			* `BCXXXXXXXX000000` - Get SD write status.
			* Not sure if the address is actually used by the card or can be any dummy value. Returns `0x00000001` while the card is busy performing the write and `0x00000000` once done. This command is polled as long as the return value is 1.
			* `BDXXXXXXXX000000` - Start save write to address `0xXXXXXXXX`.
			`* Address should most likely be 512 byte aligned. The command expects 512 bytes of data that will be written to the save.`
			* `BEXXXXXXXX000000` - Get save write status.
			* Not sure if the address is actually used by the card or can be any dummy value. Returns `0x00000001` while the card is busy performing the write and `0x00000000` once done. This command is polled as long as the return value is 1.

			When initializing the R4 for retail rom use it seems there are some `0000000000000000` dummy commands send. Not sure if that is actually needed to make it work. After that `B4` is used to initialize the cluster map for rom and save file. The save file should have already been created on the SD card by the software on the DS side. The retail game is patched by the DS side software to perform rom reads using the requesting mechanism (`B6`/`B7`) and to perform save reads and writes using the corresponding card commands (`B2`/`B3` and `BD`/`BE`) instead of SPI. The advantage of the requesting/feedback mechanism for rom reads is that the data can be read as soon as it is ready. SD cards can have varying read latency and without a feedback mechanism you'd always have to account for the worst case, which can be more than the maximum amount of latency that can be specified in the IO registers and would be awful for the performance.