Add CPU mode select register - KEY0

[alloncm]

Add the register description to the CGB Registers page and updated the CGB flag cartridge and the Power Up Sequence with refs to the new register.

This PR mostly uses ISSOtm/gb-bootroms@8513822 as a source for the register description which is based on leaks (hope it is OK).

Edit:

This PR now does not uses leaked documents as a source but acknowledge them as other sections are relaying on them.

Edit 2:

This PR now does not uses leaked documents.

[avivace]

I'd like to avoid basing information on leaks. If those registers have indeed an effect, can't they be tested and documented following a clean-room design?

[nummacway]

I suggest that pandocs describe usable registers. Features requiring hardware manipulation should get their own page.

Under normal circumstances, this register is only writable by putting a value in ROM byte $143. It doesn't have a use that makes sense. If this register gets added, I suggest something like this:

If the highest bit of ROM byte $143 is set in order to enable CGB features, the CGB's BIOS will copy that byte into register $FF4C. This register gets locked when writing to $FF50. Because the CGB's BIOS does write to $FF50, other software cannot write to register $FF43 without BIOS manipulation. If bit 2 is set in said byte, the CGB will be in a hybrid state between DMG and CGB, leaving you with an inaccessible blank palette. Bit 3 is said to have an effect but this effect is unknown. The use of the other bits is unknown as well.

Some more info: https://forums.nesdev.org/viewtopic.php?p=248353&sid=693346db893528869f0907b1d5008897#p248353

[nitro2k01]

I think a true cleanroom process is unlikely to happen here, and I'm not sure it would even be very useful. What would that even mean here? Recruiting a GB programmer who has not seen the leaks, to make a test ROM? This test ROM would then have to run in the boot ROM context, which would require a very specific setup. That's a lot of extra work that I'm not sure would serve much actual (legal) purpose.

I agree however that information should not be copied directly from leaked documents without being tested.

Apart from the leaks, you would also have to consider other sources like...

• The boot ROM. Dumpable from devices you own, but at the same time copyrighted code. It's debatable whether distributing the boot ROM, including in the form of a disassembly that produces the exact binary, is legal. However, I have personally done it for over 10 years, and ISSOtm has published his disassemblies for a while now and neither of us have gotten into trouble so far. Should however probably be legally ok to use as a source for deducing behavior of the hardware.
• The Gameboy Programming Manual. Normally restricted to licensed developers, but nowadays it's widely available.

So for example, by studying the boot ROM disassembly, you can reach the following conclusions:

• Bits 3 and 2 of $FF4C are written value 01 by the boot ROM if you're trying to load a monochrome game, or (principally) 00 if you're trying to load a color compatible game. It's my personal opinion that it would be ok to describe this behavior in Pan Docs. Parroting the notes about PGB mode would not be ok since it's both unverified (nobody has gotten those modes to work and they might not even be implemented in hardware) and the information is essentially copied directly from leaked information. However, I think it would be fair game to add a note like: "It has been speculated based on leaked documents that setting 10 and 11 are related to a special PGB mode for controlling the LCD externally. However, this has not been independently verified."
• As for $FF6C, it can be noted that in the disassembly that this register is written with the value $01 if the game is monochrome. We could combine the behavior of the boot ROM plus this note in the manual to deduce what this bit might do. "Object with lowest OBJ number (DMG mode: Object with lowest x coord.)" This si something that can easily be verified to be a difference between a DMG and GBC game by setting different values in the header and running a test program on a cartridge. Now, we can't know exactly whether it's writing $FF6C or $FF4C that does it, but this is something that could theoretically be tested, and I'm sure someone did verify it at some point.

I think an approach like that would be viable.

Then there's the names. Should we just pretend we don't know the names of these registers? Pan Docs is already filled with register names that were somehow leaked from the programming manual during the console's commercial lifespan. I would expect the register names to be a minor enough detail that it's not actually a legal risk.

Obligatory disclaimer that I'm not a lawyer.

[alloncm]

Hi thanks for the constructive comments and the new info about this register (I suspected it gets locked after the boot process ends but couldn't find any info about it).

I agree with @nitro2k01 that a clean room implementation will be hard to implement (maybe just verify that the register is not writable/have effect after the boot ends) considering a boot context is needed.

In retrospective I might gave too much credit to the leak in this PR info then necessary:

• The name of the register also appears in this patent - https://patents.google.com/patent/US6322447B1/en?oq=US6322447bi (so we can infer it from there).
• The values 0 and 1 (for the CGB and DMG modes )can be inferred from the bootrom disassembly (since it uses them) as @nitro2k01 suggested.
• The values for the PGB1/2 modes are the problematic ones and I couldn't find any info about them online aside from the bootrom disassembly source I linked and the Pandocs (but with only vague description, that is also why I edited those places for reference this register) and now @nummacway link which seems like the original forum thread that translated the leaks.

So maybe we can just omit those PGB names (although they already present in other places) and just treat them as unknown?

[aaaaaa123456789]

I don't think there's any value in pretending we don't know stuff we do know, only to openly discuss it just about everywhere else and tell newcomers "yeah, we wrote down unknown, but we just lied".

[SonoSooS]

I don't think it's about lying about not knowing it. Or at least in this case, it is lying about knowing it.

If this info were acquired using any form of "self-resarch", you'd have much more to say about these registers than that was said here, test ROM or not. And even if I didn't know about the existance of this info leaking, I'd be still suspicious about this being copypasted from somewhere, as even if you only tested the four values presented in $FF6C, you'd know that with one of the modes it doesn't seem to even reach $0100, and thus can't even execute a STOP to switch mode. And if somehow a method was found to bypass that, I hope it would be also written down.

[aaaaaa123456789]

I don't think it's about lying about not knowing it. Or at least in this case, it is lying about knowing it.

You know about this information. You're describing it! Anything described here is known, because the messages wouldn't exist if it wasn't. So yes, it is lying about knowing it. You can't simultaneously describe how something works and claim you know nothing about how it works.

[pinobatch]

I think the intent is to keep Pan Docs lawful to distribute even in those jurisdictions whose trade secret law restricts copying ideas (not expression) from a source that someone knows or has reason to know is a leak. As ax6 has told me several times in the gbdev Discord server, not all the world is the United States, or Germany, or Argentina, or Japan. However, we need to keep the law of GitHub's home country at top of mind as long as Pan Docs is hosted on GitHub.

For this reason, I recommend explicitly describing observable behavior, with instructions on how to observe it. Because we don't yet know the behavior of "PGB" modes to an extent that we can rig up a test cart that uses them, we can truthfully describe their behavior as unknown. You could start with wording to this effect:

"This GBC-only register is written by the boot ROM. It has no effect after the game starts. Its behavior is not testable without hardware manipulation."

"When the value at $0143 in the header is at least $80, it controls various aspects of the GBC system, some related to compatibility with original Game Boy games. Values $80 and $C0 are typical, placing the system in ordinary GBC mode. Value X enters a monochrome mode with a blank palette that cannot be changed later. Some values prevent the boot ROM from jumping to $0100 in the first place."

[nummacway]

As I said on Discord, it's save to assume that nocash wrote the notes that he posted in that thread before the leak. Remove the speculation about bit 3 (which is probably even wrong) and you have all information that I think is relevant for Pan Docs.

I don't think there's any value in pretending we don't know stuff we do know, only to openly discuss it just about everywhere else and tell newcomers "yeah, we wrote down unknown, but we just lied".

We don't pretend that we don't know. We really don't know.
Nintendo gave a bit a nickname. That's all we know. That's so little that I round that down to 0.

As pinobatch proposed, we should describe observable behaviour. You might even call it actual behaviour. You cannot (currently) observe what bit 3 does.

[alloncm]

Hi, thanks again everyone for the constructive comments.

I have just pushed new changes based on your suggestions that does not depends on the leaks as a reference.

I have tried not to make big changes in the "power up sequence" and "the cartridge header" sections but they are already using the "PGB mode" terminology.
In order to make it less confusing I have added a new subsection for the register, addressing the speculations about PGB mode and bit 3.

Let me know what you think.

[avivace]

I would move this inside the "research needed" boxes and avoid mentioning where the speculation comes from. I'd make this generic and link from the Research Needed box an issue here on github where we can discuss / contribute to this specific topic

[nummacway]

What's the reason to mention bit 3 at all anyway?

[avivace]

Yeah, exactly, I don't see a reason for it at the moment. We can have the speculation/discussions in a issue and simply link to it

[alloncm]

Since other sections (like the OPRI register) mentions PGB mode with the values activating it I thought it will help to avoid confusion regarding those values.

[alloncm]

Just pushed new changes and opened a new issue addressing most of the comments except for bit 3 so Im not resolving this yet.
Let me know what you think regarding the other sections mentioning PGB mode values.

[SonoSooS]

I think that this should wait some more time. Every few hours we find new information.

What is known for sure:

• $FF4C[3:2] is a field, not separate bits.
  • 0: CGB mode
  • 1: DMG mode
  • 2 and 3 are PGB mode (they indeed work as advertised, the cartridge port does influence the LCD after the STOP, but what doesn't work as advertised, is that I can't get a life out of the CPU after STOP in either of the modes, whereas the same code works fine in CGB and DMG mode (only $143 is changed to change the value copied to $FF4C))
• PGB modes are most likely not intended to be used outside of executing STOP, as IO port protections are nonsensical (rRP works, but palette data registers don't, but also VRAM1 partially works, but OBP0 only kind of works? it's nonsense), so this is most likely indeed meant to be used in a mode, where an external device drives the LCD. I can get colors on the LCD that are not present in the OBJ palette, so it's probably "direct drive".

More meaningful research will probably come a month or so later, unless we have more breakthrough.

[alloncm]

Glad to hear the research is advancing!
Since this PR wont introduce new info about the PGB modes I don't think this should wait,
once the research will be ready we can open a new PR and add the new discovered information.

Also updating that I opened a new issue #581 (like @avivace suggested) to continue the discussions and contributions on this topic.

[avivace]

last grammar fixed then I'd say we can merge

[nummacway]

The change in src/CGB_Registers.md should have mentioned its relationship to $143.

[avivace]

@nummacway could you send a PR?

[nummacway]

Recent Discord discussions concerning GBDev's doc build processes confused me so much that I'm too afraid to edit anything.

[avivace]

@nummacway Ouch. I run locally almost all the gbdev projects weekly and they run perfectly fine.

Let's start from the beginning together, could you try following https://github.com/gbdev/pandocs/blob/master/DEPLOY.md ? Once you git pull, you can also use the Docker option and skip building.

Let me know anything that comes up