gbdev / gbdev/pandocs

Document SGB bootrom header send command

Open
#658 2 comments 0 reactions 0 assignees View on GitHub
content
Dominant language
Markdown
Stars
783
Forks
134
Avg merge
6h 54m
Merged PRs (30d)
3

Description

The SGB bootrom has special header send command, which the SGB BIOS expects to be sent (if it's not sent, the BIOS locks up). This has the SNES side validate the header (i.e. check the GB logo) and there're various checksums in the packets which are also "validated" (kind of). This is also how the SNES side decides to enable SGB features.

The command has packets starting with 0xF1, 0xF3, 0xF5, 0xF7, 0xF9, and 0xFB, although the BIOS only validates the first packet here. These don't follow the standard command layout, but if you were to interpret them as such, you'd see them as commands 0x1E and 0x1F with weird lengths, which Pan Docs notes as being "explicitly ignored."

In reality, the header sent command is handled in a separate handler which is ran when the SGB is booted up. Once the header is sent, the SNES stops the GB side and (assuming the header has a valid GB logo) plays the BIOS intro animation. Once it's done, it proceeds to reboot the GB side, which means the header is sent again, using the same special command handler. After which, the checksums in the packets sent are checked if they match the checksums in the previous set of packets sent (as a way to prevent a TOCTOU bug I guess?).

The SGB treats command 0x1E and 0x1F as a special case and sets the command index to 0 (i.e. functionally the same as forcing the command length to 1). This might have been intended to avoid issues in case the SGB bootrom was being ran under the normal command handler (but I'm not sure how that could happen, outside of maybe using a cart that asserts the /RESET pin)

Contributor guide

Open the contributing guide

Research direction

Start by locating the existing SGB command documentation and use the behavior described here to determine where the bootrom header send command belongs. Document its packet prefixes, validation and reboot behavior, plus the special handling of commands 0x1E and 0x1F; done when the command's behavior and relationship to SGB features are clearly covered.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.