Revise the explanation of the cartridge header (#429)

Co-authored-by: Anton Ihonen <[email protected]>
Co-authored-by: Antonio Vivace <[email protected]>

Author: avivace

src/Power_Up_Sequence.md

@@ -207,7 +207,7 @@ Rely on it at your own risk.
 ### Common remarks
 
 The console's WRAM and HRAM are random on power-up.
-[Different models tend to exhibit different patterns](https://twitter.com/CasualPkPlayer/status/1409752977812852736?s=19), but they are random nonetheless, even depending on factors such as the ambient teperature.
+[Different models tend to exhibit different patterns](https://twitter.com/CasualPkPlayer/status/1409752977812852736), but they are random nonetheless, even depending on factors such as the ambient temperature.
 Besides, turning the system off and on again has proven reliable enough [to carry over RAM from one game to another](https://www.youtube.com/watch?v=xayxmTLljr8), so it's not a good idea to rely on it at all.
 
 Emulation of uninitialized RAM is inconsistent: some emulators fill RAM with a constant on startup (typically $00 or $FF), some emulators fully randomize RAM, and others attempt to reproduce the patterns observed on hardware.

src/The_Cartridge_Header.md

@@ -1,70 +1,79 @@
 # The Cartridge Header
 
-An internal information area is located at $0100-014F in each cartridge.
-It contains the following values:
+Each cartridge contains a header, located at the address range `$0100`—`$014F`.
+The cartridge header provides the following information about the game itself and the hardware it expects to run on:
 
 ## 0100-0103 - Entry Point
 
-After displaying the Nintendo Logo, the built-in boot procedure jumps to
-this address ($0100), which should then jump to the actual main program
-in the cartridge. Usually this 4 byte area contains a `nop` instruction,
-followed by a `jp $0150` instruction. But not always.
+After displaying the Nintendo logo, the built-in [boot ROM](<#Power-Up Sequence>) jumps to the address `$0100`, which should then jump to the actual main program in the cartridge.
+Most commercial games fill this 4-byte area with a [`nop` instruction](https://rgbds.gbdev.io/docs/v0.5.2/gbz80.7/#NOP) followed by a [`jp $0150`](https://rgbds.gbdev.io/docs/v0.5.2/gbz80.7/#JP_n16).
 
 ## 0104-0133 - Nintendo Logo
 
-These bytes define the bitmap of the Nintendo logo that is displayed
-when the Game Boy gets turned on. The hex dump of this bitmap is:
+This area contains a bitmap image that is displayed when the Game Boy is powered on.
+It must match the following (hexadecimal) dump, otherwise [the boot ROM](<#Power-Up Sequence>) won't allow the game to run:
+
 ```
- CE ED 66 66 CC 0D 00 0B 03 73 00 83 00 0C 00 0D
- 00 08 11 1F 88 89 00 0E DC CC 6E E6 DD DD D9 99
- BB BB 67 63 6E 0E EC CC DD DC 99 9F BB B9 33 3E
+CE ED 66 66 CC 0D 00 0B 03 73 00 83 00 0C 00 0D
+00 08 11 1F 88 89 00 0E DC CC 6E E6 DD DD D9 99
+BB BB 67 63 6E 0E EC CC DD DC 99 9F BB B9 33 3E
 ```
-The Game Boy's boot procedure verifies the content of this bitmap
-(after it has displayed it), and LOCKS ITSELF UP if these bytes are
-incorrect. A CGB verifies only the first half ($18 bytes of) the bitmap, but
-others (for example a Game Boy pocket) verify all $30 bytes, as does the
-Game Boy Advance.
+
+The way the pixels are encoded is as follows: ([more visual aid](https://github.com/ISSOtm/gb-bootroms/blob/2dce25910043ce2ad1d1d3691436f2c7aabbda00/src/dmg.asm#L259-L269))
+
+- The bytes `$0104`—`$011B` encode the top half of the logo while the bytes `$011C`–`$0133` encode the bottom half.
+- For each half, each nibble encodes 4 pixels (the MSB corresponds to the leftmost pixel, the LSB to the rightmost); a pixel is lit if the corresponding bit is set.
+- The 4-pixel "groups" are laid out top to bottom, left to right.
+- Finally, the monochrome models upscale the entire thing by a factor of 2 (leading to somewhat chunky pixels).
+
+The Game Boy's boot procedure [first displays the logo and then checks](<#Bypass>) that it matches the dump above.
+If it doesn't, the boot ROM **locks itself up**.
+
+The CGB and later models [only check the top half of the logo](Power_Up_Sequence.html?highlight=half#behavior) (the first `$18` bytes).
 
 ## 0134-0143 - Title
 
-Title of the game in UPPER CASE ASCII. If it is less than 16 characters
-then the remaining bytes are filled with $00 bytes. When inventing the CGB,
-Nintendo has reduced the length of this area to 15 characters, and some
-months later they had the fantastic idea to reduce it to 11 characters
-only. The new meaning of the ex-title bytes is described below.
+These bytes contain the title of the game in upper case ASCII.
+If the title is less than 16 characters long, the remaining bytes should be padded with `$00`s.
+
+Parts of this area actually have a different meaning on later cartridges, reducing the actual title size to 15 (`$0134`–`$0142`) or 11 (`$0134`–`$013E`) characters; see below.
 
 ## 013F-0142 - Manufacturer Code
 
-In older cartridges this area has been part of the Title (see above), in
-newer cartridges this area contains an 4 character uppercase
-manufacturer code. Purpose and Deeper Meaning unknown.
+In older cartridges these bytes were part of the Title (see above).
+In newer cartridges they contain a 4-character manufacturer code (in uppercase ASCII).
+The purpose of the manufactorer code is unknown.
 
 ## 0143 - CGB Flag
 
-In older cartridges this byte has been part of the Title (see above). In
-CGB cartridges the upper bit is used to enable CGB functions. This is
-required, otherwise the CGB switches itself into Non-CGB-Mode. Typical
-values are:
-```
- 80h - Game supports CGB functions, but also works on old Game Boys.
- C0h - Game works on CGB only (physically the same as $80).
-```
-Values with Bit 7 set, and either Bit 2 or 3 set, will switch the
-Game Boy into a special non-CGB-mode called "PGB mode".
+In older cartridges this byte was part of the Title (see above).
+The CGB and later models interpret this byte to decide whether to enable Color mode ("CGB Mode") or to fall back to monochrome compatibility mode ("Non-CGB Mode").
+
+Typical values are:
+
+Value | Meaning
+------|----------------------------------------------------------------------------------------------------
+`$80` | The game supports CGB enhancements, but is backwards compatible with monochrome Game Boys
+`$C0` | The game works on CGB only (the hardware ignores bit 6, so this really functions the same as `$80`)
 
-TODO: research and document PGB modes...
+Values with bit 7 and either bit 2 or 3 set will switch the Game Boy into a special non-CGB-mode called "PGB mode".
+
+::: tip Research needed
+
+The PGB mode is not well researched or documented yet.
+Help is welcome!
+
+:::
 
 ## 0144-0145 - New Licensee Code
 
-Specifies a two-character ASCII licensee code, indicating the company or
-publisher of the game. These two bytes are used in newer games only
-(games that have been released after the SGB has been invented). Older
-games are using the header entry at `$014B` instead.
+This area contains a two-character ASCII "licensee code" indicating the game's publisher.
+It is only meaningful if the [Old Licensee Code](<#014B — Old Licensee Code>) is exactly `$33` (which is the case for essentially all games made after the SGB was released); otherwise, the old code must be considered.
 
 Sample licensee codes:
 
 Code | Publisher
------|-----------
+-----|-------------------------
 `00` | None
 `01` | Nintendo R&D1
 `08` | Capcom
@@ -129,143 +138,141 @@ Code | Publisher
 
 ## 0146 - SGB Flag
 
-Specifies whether the game supports SGB functions, common values are:
-
-- `$00`: No SGB functions (Normal Game Boy or CGB only game)
-- `$03`: Game supports SGB functions
-
-The SGB disables its SGB functions if this byte is set to a value other than `$03`.
+This byte specifies whether the game supports SGB functions.
+The SGB will ignore any [command packets](<#Command Packet Transfers>) if this byte is set to a value other than `$03` (typically `$00`).
 
 ## 0147 - Cartridge Type
 
-Specifies which Memory Bank Controller (if any) is used in the
-cartridge, and if further external hardware exists in the cartridge.
-
-Code | Type
------|------
- $00 | ROM ONLY
- $01 | MBC1
- $02 | MBC1+RAM
- $03 | MBC1+RAM+BATTERY
- $05 | MBC2
- $06 | MBC2+BATTERY
- $08 | ROM+RAM [^rom_ram]
- $09 | ROM+RAM+BATTERY [^rom_ram]
- $0B | MMM01
- $0C | MMM01+RAM
- $0D | MMM01+RAM+BATTERY
- $0F | MBC3+TIMER+BATTERY
- $10 | MBC3+TIMER+RAM+BATTERY [^mbc30]
- $11 | MBC3
- $12 | MBC3+RAM [^mbc30]
- $13 | MBC3+RAM+BATTERY [^mbc30]
- $19 | MBC5
- $1A | MBC5+RAM
- $1B | MBC5+RAM+BATTERY
- $1C | MBC5+RUMBLE
- $1D | MBC5+RUMBLE+RAM
- $1E | MBC5+RUMBLE+RAM+BATTERY
- $20 | MBC6
- $22 | MBC7+SENSOR+RUMBLE+RAM+BATTERY
- $FC | POCKET CAMERA
- $FD | BANDAI TAMA5
- $FE | HuC3
- $FF | HuC1+RAM+BATTERY
+This byte indicates what kind of hardware is present on the cartridge — most notably its [mapper](#MBCs).
+
+Code  | Type
+------|--------------------------------
+`$00` | ROM ONLY
+`$01` | MBC1
+`$02` | MBC1+RAM
+`$03` | MBC1+RAM+BATTERY
+`$05` | MBC2
+`$06` | MBC2+BATTERY
+`$08` | ROM+RAM [^rom_ram]
+`$09` | ROM+RAM+BATTERY [^rom_ram]
+`$0B` | MMM01
+`$0C` | MMM01+RAM
+`$0D` | MMM01+RAM+BATTERY
+`$0F` | MBC3+TIMER+BATTERY
+`$10` | MBC3+TIMER+RAM+BATTERY [^mbc30]
+`$11` | MBC3
+`$12` | MBC3+RAM [^mbc30]
+`$13` | MBC3+RAM+BATTERY [^mbc30]
+`$19` | MBC5
+`$1A` | MBC5+RAM
+`$1B` | MBC5+RAM+BATTERY
+`$1C` | MBC5+RUMBLE
+`$1D` | MBC5+RUMBLE+RAM
+`$1E` | MBC5+RUMBLE+RAM+BATTERY
+`$20` | MBC6
+`$22` | MBC7+SENSOR+RUMBLE+RAM+BATTERY
+`$FC` | POCKET CAMERA
+`$FD` | BANDAI TAMA5
+`$FE` | HuC3
+`$FF` | HuC1+RAM+BATTERY
 
 [^rom_ram]:
-No licensed cartridge makes use of this option. Exact behaviour is unknown.
+No licensed cartridge makes use of this option. The exact behavior is unknown.
 
 [^mbc30]:
-MBC3 with RAM size 64 KByte refers to MBC30, used only in _Pocket Monsters Crystal Version_ for Japan.
+MBC3 with 64 KiB of SRAM refers to MBC30, used only in _Pocket Monsters: Crystal Version_ (the Japanese version of _Pokémon Crystal Version_).
 
 ## 0148 - ROM Size
 
-Specifies the ROM Size of the cartridge. Typically calculated as "N such that 32 KiB
-<< N".
-
-Code | Size      | Amount of banks
------|-----------|-----------------
- $00 |  32 KByte | 2 (No ROM banking)
- $01 |  64 KByte | 4
- $02 | 128 KByte | 8
- $03 | 256 KByte | 16
- $04 | 512 KByte | 32
- $05 |   1 MByte | 64
- $06 |   2 MByte | 128
- $07 |   4 MByte | 256
- $08 |   8 MByte | 512
- $52 | 1.1 MByte | 72 [^weird_rom_sizes]
- $53 | 1.2 MByte | 80 [^weird_rom_sizes]
- $54 | 1.5 MByte | 96 [^weird_rom_sizes]
+This byte indicates how much ROM is present on the cartridge.
+In most cases, the ROM size is given by `32 KiB × (1 << <value>)`:
+
+Value | ROM size  | Number of ROM banks
+------|-----------|----------------------
+`$00` |  32 KiB   | 2 (no banking)
+`$01` |  64 KiB   | 4
+`$02` | 128 KiB   | 8
+`$03` | 256 KiB   | 16
+`$04` | 512 KiB   | 32
+`$05` |   1 MiB   | 64
+`$06` |   2 MiB   | 128
+`$07` |   4 MiB   | 256
+`$08` |   8 MiB   | 512
+`$52` | 1.1 MiB   | 72 [^weird_rom_sizes]
+`$53` | 1.2 MiB   | 80 [^weird_rom_sizes]
+`$54` | 1.5 MiB   | 96 [^weird_rom_sizes]
 
 [^weird_rom_sizes]:
 Only listed in unofficial docs. No cartridges or ROM files using these sizes are known.
-As the other ROM sizes are all powers of 2, these are likely inaccurate. The source for these
-values is unknown.
+As the other ROM sizes are all powers of 2, these are likely inaccurate.
+The source of these values is unknown.
 
 ## 0149 - RAM Size
 
-Specifies the size of the external RAM in the cartridge (if any).
+This byte indicates how much RAM is present on the cartridge, if any.
 
-Code | Size   | Comment
------|--------|---------
- $00 | 0      | No RAM [^mbc2]
- $01 | -      | Unused [^2kib_sram]
- $02 | 8 KB   | 1 bank
- $03 | 32 KB  | 4 banks of 8 KB each
- $04 | 128 KB | 16 banks of 8 KB each
- $05 | 64 KB  | 8 banks of 8 KB each
+If the [cartridge type](<#0147 - Cartridge Type>) does not include "RAM" in its name, this should be set to 0.
+This includes MBC2, since its 512 × 4 bits of memory are built directly into the mapper.
 
-[^mbc2]:
-When using a MBC2 chip, $00 must be specified as the RAM Size, even though
-the MBC2 includes a built-in RAM of 512 x 4 bits.
+Code  | SRAM size | Comment
+------|-----------|-----------------------
+`$00` |   0       | No RAM
+`$01` |   –       | Unused [^2kib_sram]
+`$02` |   8 KiB   |  1 bank
+`$03` |  32 KiB   |  4 banks of 8 KiB each
+`$04` | 128 KiB   | 16 banks of 8 KiB each
+`$05` |  64 KiB   |  8 banks of 8 KiB each
 
 [^2kib_sram]:
-Listed in various unofficial docs as 2KB. However, a 2KB RAM chip was never used in a cartridge.
-The source for this value is unknown.
+Listed in various unofficial docs as 2 KiB.
+However, a 2 KiB RAM chip was never used in a cartridge.
+The source of this value is unknown.
 
-Various "PD" ROMs ("Public Domain" homebrew ROMs generally tagged "(PD)"
-in the filename) are known to use the $01 RAM Size tag, but this is believed
-to have been a mistake with early homebrew tools and the PD ROMs often don't use
-cartridge RAM at all.
+Various "PD" ROMs ("Public Domain" homebrew ROMs, generally tagged with `(PD)` in the filename) are known to use the `$01` RAM Size tag, but this is believed to have been a mistake with early homebrew tools, and the PD ROMs often don't use cartridge RAM at all.
 
 ## 014A - Destination Code
 
-Specifies if this version of the game is supposed to be sold in Japan,
-or anywhere else. Only two values are defined.
+This byte specifies whether this version of the game is intended to be sold in Japan or elsewhere.
 
-- $00: Japanese
-- $01: Non-Japanese
+Only two values are defined:
+
+Code  | Destination
+------|------------------------------
+`$00` | Japan (and possibly overseas)
+`$01` | Overseas only
 
 ## 014B - Old Licensee Code
 
-Specifies the games company/publisher code in range $00-FF. A value of
-$33 signals that the New Licensee Code (in header bytes \$0144-0145) is
-used instead. (Super Game Boy functions won't work if \<\> \$33.) A list
-of licensee codes can be found
-[here](https://raw.githubusercontent.com/gb-archive/salvage/master/txt-files/gbrom.txt).
+This byte is used in older (pre-SGB) cartridges to specify the game's publisher.
+However, the value `$33` indicates that the [New Licensee Code](<#0144-0145 - New Licensee Code>) must be considered instead.
+(The SGB will ignore any [command packets](<#Command Packet Transfers>) unless this value is `$33`.)
+
+Here is [a list of known Old Licensee Codes](https://raw.githubusercontent.com/gb-archive/salvage/master/txt-files/gbrom.txt).
 
 ## 014C - Mask ROM Version number
 
-Specifies the version number of the game. That is usually $00.
+This byte specifies the version number of the game.
+It is usually `$00`.
 
 ## 014D - Header Checksum
 
-Contains an 8 bit checksum across the cartridge header bytes $0134-014C.
-The boot ROM computes `x` as follows:
+This byte contains an 8-bit checksum computed from the cartridge header bytes `$0134`—`$014C`.
+The boot ROM computes the checksum as follows:
 
-```
-x = 0
-i = $0134
-while i <= $014C
-	x = x - [i] - 1
+```c
+uint8_t checksum = 0;
+for (uint16_t address = 0x0134; address <= 0x014C; address++) {
+    checksum = checksum - rom[address] - 1;
+}
 ```
 
-If the byte at $014D does not match the lower 8 bits of `x`, the boot ROM will lock up,
-and the cartridge program **won't run**.
+The boot ROM verifies this checksum.
+If the byte at `$014D` does not match the lower 8 bits of `checksum`, the boot ROM will lock up and the program in the
+cartridge **won't run**.
 
 ## 014E-014F - Global Checksum
 
-Contains a 16 bit checksum (upper byte first) across the whole cartridge
-ROM. Produced by adding all bytes of the cartridge (except for the two
-checksum bytes). The Game Boy doesn't verify this checksum.
+These bytes contain a 16-bit (big-endian) checksum simply computed as the sum of
+all the bytes of the cartridge ROM (except these two checksum bytes).
+
+This checksum is not verified, except by Pokémon Stadium's "GB Tower" emulator (presumably to detect Transfer Pak errors).