From 67d62465fec55676adc381c4e66ece69dca1ea9b Mon Sep 17 00:00:00 2001 From: alloncm Date: Thu, 5 Dec 2024 20:23:49 +0200 Subject: [PATCH 1/5] Add CPU mode select register - KEY0 Add the register decription to the CGB Registers page and updated the CGB flag cartrigde and the Power Up Sequence with refs to the new register PGB mode remains a mystery --- src/CGB_Registers.md | 23 ++++++++++++++++++++++- src/Power_Up_Sequence.md | 4 +++- src/The_Cartridge_Header.md | 9 +-------- 3 files changed, 26 insertions(+), 10 deletions(-) diff --git a/src/CGB_Registers.md b/src/CGB_Registers.md index c6ea289c..d000de42 100644 --- a/src/CGB_Registers.md +++ b/src/CGB_Registers.md @@ -219,13 +219,34 @@ ON/OFF pulses (length 10us ON, 17.5us OFF each) instead of a permanent 880us LED ON signal. Even though being generally CGB compatible, the GBA does not include an infra-red port. +### FF4C — KEY0 (CGB Mode only): CPU mode select + +This register is not officaly documented and this info have been gathered from leaks ([translated here](https://github.com/ISSOtm/gb-bootroms/commit/8513822a812ad9153b1618490d504c212ed61ed2)) + +{{#bits 8 > + "KEY0" 3-2:"CPU mode" +}} + +CPU mode can be one of those 2 bits values: +- 0 - CGB mode (for execution of CGB supporting cartridges) +- 1 - DMG mode (for execution of DMG exclusive cartridges) +- 2 - PGB1 mode +- 3 - PGB2 mode + +:::tip Research needed + +The PGB mode is not well researched or documented yet. +Help is welcome! + +::: + ### FF6C — OPRI (CGB Mode only): Object priority mode This register serves as a flag for which object priority mode to use. While the DMG prioritizes objects by x-coordinate, the CGB prioritizes them by location in OAM. This flag is set by the CGB bios after checking the game's CGB compatibility. -OPRI has an effect if a PGB value (`0xX8`, `0xXC`) is written to KEY0 but STOP hasn't been executed yet, and the write takes effect instantly. +OPRI has an effect if a PGB value (`0xX8`, `0xXC`) is written to [KEY0](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) but STOP hasn't been executed yet, and the write takes effect instantly. :::warning TO BE VERIFIED diff --git a/src/Power_Up_Sequence.md b/src/Power_Up_Sequence.md index f7716922..28048175 100644 --- a/src/Power_Up_Sequence.md +++ b/src/Power_Up_Sequence.md @@ -86,7 +86,9 @@ Then, like the monochrome boot ROMs, the header logo is checked *from the buffer For unknown reasons, however, only the first half of the logo is checked, despite the full logo being present in the HRAM buffer. Finally, the boot ROM fades all BG palettes to white, and sets the hardware to compatibility mode. -If [the CGB compatibility byte](<#0143 — CGB flag>) indicates CGB compatibility, the byte is written directly to `KEY0` ($FF4C), potentially enabling PGB mode; otherwise, $04 is written to `KEY0` (enabling DMG compatibility mode in the CPU), $01 is written to [`OPRI`](<#FF6C — OPRI (CGB Mode only): Object priority mode>) (enabling [DMG OBJ priority](<#Object Priority and Conflicts>)), and the [compatibility palettes](<#Compatibility palettes>) are written. +If [the CGB compatibility byte](<#0143 — CGB flag>) indicates CGB compatibility, the byte is written directly to [`KEY0`](<#FF4C — KEY0 (CGB Mode only): CPU mode select>), +potentially enabling PGB mode; otherwise, $04 is written to `KEY0` (enabling DMG compatibility mode in the CPU), +$01 is written to [`OPRI`](<#FF6C — OPRI (CGB Mode only): Object priority mode>) (enabling [DMG OBJ priority](<#Object Priority and Conflicts>)), and the [compatibility palettes](<#Compatibility palettes>) are written. Additionally, the DMG logo tilemap is written [if the compatibility requests it](<#Compatibility palettes>). Like all other boot ROMs, the last thing the color boot ROMs do is hand off execution at the same time as they unmap themselves, though they write $11 instead of $01 or $FF. diff --git a/src/The_Cartridge_Header.md b/src/The_Cartridge_Header.md index 6a1d64c9..58fc647e 100644 --- a/src/The_Cartridge_Header.md +++ b/src/The_Cartridge_Header.md @@ -56,14 +56,7 @@ 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`) -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! - -::: +Setting bit 7 will trigger a write of bits 2-3 to [KEY0](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) which sets the CPU mode. ## 0144–0145 — New licensee code From 4642155684577e535c4f91b44a3a33b4d4741e1e Mon Sep 17 00:00:00 2001 From: alloncm Date: Sun, 8 Dec 2024 18:31:13 +0200 Subject: [PATCH 2/5] Remove the leaked info reference and try to make PGB mode references less confusing --- src/CGB_Registers.md | 26 ++++++++++++++++---------- src/Power_Up_Sequence.md | 4 ++-- src/The_Cartridge_Header.md | 2 +- 3 files changed, 19 insertions(+), 13 deletions(-) diff --git a/src/CGB_Registers.md b/src/CGB_Registers.md index d000de42..b4e3c66f 100644 --- a/src/CGB_Registers.md +++ b/src/CGB_Registers.md @@ -221,22 +221,28 @@ does not include an infra-red port. ### FF4C — KEY0 (CGB Mode only): CPU mode select -This register is not officaly documented and this info have been gathered from leaks ([translated here](https://github.com/ISSOtm/gb-bootroms/commit/8513822a812ad9153b1618490d504c212ed61ed2)) +This GBC-only register (which is not officaly documented) is written only by the CGB boot ROM, +as it gets locked after the bootrom finish execution (by a write to the [BANK register](<#Monochrome models (DMG0, DMG, MGB)>)). + +Once it is locked, the behavior of the system can't be changed without a reset (This behavior can be observed using [this test ROM](https://github.com/alloncm/MagenTests?tab=readme-ov-file#key0-cpu-mode-register-lock-after-boot)). + +As a result of the above most of the behavior is not directly testable without hardware manipulation. +Even though we can't test it's behavior directly we can inspect the disassembly of the CGB bootrom and infer the following: {{#bits 8 > - "KEY0" 3-2:"CPU mode" + "KEY0" 2:"DMG compatibility mode" }} -CPU mode can be one of those 2 bits values: -- 0 - CGB mode (for execution of CGB supporting cartridges) -- 1 - DMG mode (for execution of DMG exclusive cartridges) -- 2 - PGB1 mode -- 3 - PGB2 mode +- **DMG compatibility mode**: `0` = Disabled (full CGB mode, for regular CGB cartridges), `1` = Enabled (for DMG only cartridges) + +#### Bit 3 and "PGB mode" + +It has been speculated based on leaked documents that setting bit 3 is related to a special mode called "PGB" for controlling the LCD externally. +However, this has not been independently verified. :::tip Research needed -The PGB mode is not well researched or documented yet. -Help is welcome! +Bit 3 and the "PGB mode" are not well researched or documented yet, any help is welcome! ::: @@ -246,7 +252,7 @@ This register serves as a flag for which object priority mode to use. While the DMG prioritizes objects by x-coordinate, the CGB prioritizes them by location in OAM. This flag is set by the CGB bios after checking the game's CGB compatibility. -OPRI has an effect if a PGB value (`0xX8`, `0xXC`) is written to [KEY0](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) but STOP hasn't been executed yet, and the write takes effect instantly. +OPRI has an effect if a [PGB](<#Bit 3 and "PGB mode">) value (`0xX8`, `0xXC`) is written to [KEY0](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) but STOP hasn't been executed yet, and the write takes effect instantly. :::warning TO BE VERIFIED diff --git a/src/Power_Up_Sequence.md b/src/Power_Up_Sequence.md index 28048175..7c136f95 100644 --- a/src/Power_Up_Sequence.md +++ b/src/Power_Up_Sequence.md @@ -86,8 +86,8 @@ Then, like the monochrome boot ROMs, the header logo is checked *from the buffer For unknown reasons, however, only the first half of the logo is checked, despite the full logo being present in the HRAM buffer. Finally, the boot ROM fades all BG palettes to white, and sets the hardware to compatibility mode. -If [the CGB compatibility byte](<#0143 — CGB flag>) indicates CGB compatibility, the byte is written directly to [`KEY0`](<#FF4C — KEY0 (CGB Mode only): CPU mode select>), -potentially enabling PGB mode; otherwise, $04 is written to `KEY0` (enabling DMG compatibility mode in the CPU), +If [the CGB compatibility byte](<#0143 — CGB flag>) indicates CGB compatibility, the byte is written directly to [`KEY0`](<#FF4C — KEY0 (CGB Mode only): CPU mode select>), potentially [enabling "PGB mode"](<#Bit 3 and "PGB mode">); +otherwise, $04 is written to [`KEY0`](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) (enabling DMG compatibility mode in the CPU), $01 is written to [`OPRI`](<#FF6C — OPRI (CGB Mode only): Object priority mode>) (enabling [DMG OBJ priority](<#Object Priority and Conflicts>)), and the [compatibility palettes](<#Compatibility palettes>) are written. Additionally, the DMG logo tilemap is written [if the compatibility requests it](<#Compatibility palettes>). diff --git a/src/The_Cartridge_Header.md b/src/The_Cartridge_Header.md index 58fc647e..8fd3ef0c 100644 --- a/src/The_Cartridge_Header.md +++ b/src/The_Cartridge_Header.md @@ -56,7 +56,7 @@ 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`) -Setting bit 7 will trigger a write of bits 2-3 to [KEY0](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) which sets the CPU mode. +Setting bit 7 will trigger a write of this register value to [KEY0 register](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) which sets the CPU mode. ## 0144–0145 — New licensee code From eb4675c18fdd98a6269f55fb29ea78d96f54fd95 Mon Sep 17 00:00:00 2001 From: alloncm Date: Mon, 9 Dec 2024 15:09:22 +0200 Subject: [PATCH 3/5] Review fixes Move the pgb mode brief to the research needed box and add a link to a new issue regarding this topic --- src/CGB_Registers.md | 12 ++++++------ src/Power_Up_Sequence.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/CGB_Registers.md b/src/CGB_Registers.md index b4e3c66f..1ad66a05 100644 --- a/src/CGB_Registers.md +++ b/src/CGB_Registers.md @@ -235,14 +235,14 @@ Even though we can't test it's behavior directly we can inspect the disassembly - **DMG compatibility mode**: `0` = Disabled (full CGB mode, for regular CGB cartridges), `1` = Enabled (for DMG only cartridges) -#### Bit 3 and "PGB mode" - -It has been speculated based on leaked documents that setting bit 3 is related to a special mode called "PGB" for controlling the LCD externally. -However, this has not been independently verified. +#### PGB mode :::tip Research needed -Bit 3 and the "PGB mode" are not well researched or documented yet, any help is welcome! +It has been speculated that setting bit 3 is related to a special mode called "PGB" for controlling the LCD externally. +However, this has not been independently verified. + +This mode is not well researched nor documented yet, you are welcome to help [here!](https://github.com/gbdev/pandocs/issues/581) ::: @@ -252,7 +252,7 @@ This register serves as a flag for which object priority mode to use. While the DMG prioritizes objects by x-coordinate, the CGB prioritizes them by location in OAM. This flag is set by the CGB bios after checking the game's CGB compatibility. -OPRI has an effect if a [PGB](<#Bit 3 and "PGB mode">) value (`0xX8`, `0xXC`) is written to [KEY0](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) but STOP hasn't been executed yet, and the write takes effect instantly. +OPRI has an effect if a [PGB](<#PGB mode>) value (`0xX8`, `0xXC`) is written to [KEY0](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) but STOP hasn't been executed yet, and the write takes effect instantly. :::warning TO BE VERIFIED diff --git a/src/Power_Up_Sequence.md b/src/Power_Up_Sequence.md index 7c136f95..648e6bee 100644 --- a/src/Power_Up_Sequence.md +++ b/src/Power_Up_Sequence.md @@ -86,7 +86,7 @@ Then, like the monochrome boot ROMs, the header logo is checked *from the buffer For unknown reasons, however, only the first half of the logo is checked, despite the full logo being present in the HRAM buffer. Finally, the boot ROM fades all BG palettes to white, and sets the hardware to compatibility mode. -If [the CGB compatibility byte](<#0143 — CGB flag>) indicates CGB compatibility, the byte is written directly to [`KEY0`](<#FF4C — KEY0 (CGB Mode only): CPU mode select>), potentially [enabling "PGB mode"](<#Bit 3 and "PGB mode">); +If [the CGB compatibility byte](<#0143 — CGB flag>) indicates CGB compatibility, the byte is written directly to [`KEY0`](<#FF4C — KEY0 (CGB Mode only): CPU mode select>), potentially [enabling "PGB mode"](<#PGB mode>); otherwise, $04 is written to [`KEY0`](<#FF4C — KEY0 (CGB Mode only): CPU mode select>) (enabling DMG compatibility mode in the CPU), $01 is written to [`OPRI`](<#FF6C — OPRI (CGB Mode only): Object priority mode>) (enabling [DMG OBJ priority](<#Object Priority and Conflicts>)), and the [compatibility palettes](<#Compatibility palettes>) are written. Additionally, the DMG logo tilemap is written [if the compatibility requests it](<#Compatibility palettes>). From aa89c49f2d111a19c99ff2c16cb9901ec1297ca2 Mon Sep 17 00:00:00 2001 From: Antonio Vivace Date: Tue, 10 Dec 2024 00:36:02 +0100 Subject: [PATCH 4/5] Update src/CGB_Registers.md --- src/CGB_Registers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/CGB_Registers.md b/src/CGB_Registers.md index 1ad66a05..404dbf0a 100644 --- a/src/CGB_Registers.md +++ b/src/CGB_Registers.md @@ -221,7 +221,7 @@ does not include an infra-red port. ### FF4C — KEY0 (CGB Mode only): CPU mode select -This GBC-only register (which is not officaly documented) is written only by the CGB boot ROM, +This GBC-only register (which is not officially documented) is written only by the CGB boot ROM, as it gets locked after the bootrom finish execution (by a write to the [BANK register](<#Monochrome models (DMG0, DMG, MGB)>)). Once it is locked, the behavior of the system can't be changed without a reset (This behavior can be observed using [this test ROM](https://github.com/alloncm/MagenTests?tab=readme-ov-file#key0-cpu-mode-register-lock-after-boot)). From c86ae7e1e0ede657bad8816c08bf5f657a1675d5 Mon Sep 17 00:00:00 2001 From: alloncm Date: Fri, 20 Dec 2024 18:04:15 +0200 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Antonio Vivace --- src/CGB_Registers.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/CGB_Registers.md b/src/CGB_Registers.md index 404dbf0a..321bf680 100644 --- a/src/CGB_Registers.md +++ b/src/CGB_Registers.md @@ -224,10 +224,10 @@ does not include an infra-red port. This GBC-only register (which is not officially documented) is written only by the CGB boot ROM, as it gets locked after the bootrom finish execution (by a write to the [BANK register](<#Monochrome models (DMG0, DMG, MGB)>)). -Once it is locked, the behavior of the system can't be changed without a reset (This behavior can be observed using [this test ROM](https://github.com/alloncm/MagenTests?tab=readme-ov-file#key0-cpu-mode-register-lock-after-boot)). +Once it is locked, the behavior of the system can't be changed without a reset (this behavior can be observed using [this test ROM](https://github.com/alloncm/MagenTests?tab=readme-ov-file#key0-cpu-mode-register-lock-after-boot)). As a result of the above most of the behavior is not directly testable without hardware manipulation. -Even though we can't test it's behavior directly we can inspect the disassembly of the CGB bootrom and infer the following: +Even though we can't test its behavior directly we can inspect the disassembly of the CGB bootrom and infer the following: {{#bits 8 > "KEY0" 2:"DMG compatibility mode" @@ -240,7 +240,6 @@ Even though we can't test it's behavior directly we can inspect the disassembly :::tip Research needed It has been speculated that setting bit 3 is related to a special mode called "PGB" for controlling the LCD externally. -However, this has not been independently verified. This mode is not well researched nor documented yet, you are welcome to help [here!](https://github.com/gbdev/pandocs/issues/581)