gbdev / pandocs

The single, most comprehensive Game Boy technical reference.

Pan Docs

"Pan Docs" is a document started in early 1995, considered the single most comprehensive technical reference to Game Boy available to the public.

This git repository hosts a renewed version of it, mantained in the Markdown format and enjoying renewed community attention.

Go to gbdev.io/pandocs to read the document.

Contributing

Everyone is welcome to contribute opening issues, expressing feedback, adding and improving content or share new findings. Please, check the contributing guidelines for a complete view on how to contribute to this project or read the deploy instructions to run a local copy of Pan Docs.

License

Pan Docs is released into the public domain.

pandocs's Issues

RFC: Create a repo for Pan Docs as a living document.

Pan Docs was as far as I'm concerned in spirit intended to be a living document, updated as time goes by. However, in practice, it has stayed stale at the version last edited in 2001 by nocash. What I'm suggesting is a Github repo in the gbdev organization which contains a document in the same spirit as Pan Docs, but with the ability to continually improve it. It could also be placed in awesome-gbdev's articles directory, however I think it would be an important enough document to warrant its own repo. This repo would be the new "official" location of Pan Docs.

There's currently a version of Pan Docs on my wiki which is being semi-regularly updated by various people. However, I don't feel that this format is in the spirit of the original document, in particular because it's split up to multiple pages by it's very nature.

In particular, the document should be the following:

1. A single page document with internal anchor links cross-referencing between sections as needed. Being a single page is useful because you can easily ctrl-f to find a section you like in a web browser.
2. A terse reference document for developers without too much fluff.
3. Updated with new hardware findings, corrections, improvement of formatting and additions of information currently missing in Pan Docs, for example specification of other MBCs apart from MBC1-MBC3.

Here are some things I'm requesting opinions on:

4. The name. beware has voiced his opinion that the name Pan Docs ought to refer specifically to the version of the document which nocash published in 2001. If this is a concern, I'm suggesting the names Neopandocs or GBdoc to disambiguate it from the original document.
5. The document format. I would suggest storing the document as "source code" of some type which can then be transformed to HTML. (This appears to be what nocash did in his original version, where the document can be generated on the fly from within no$gmb to either HTML or plaintext.) Markdown seems like a potential candidate for such a format, because it is in itself also readable as plaintext, although suggestions are welcome.
6. Should images be used? Simple images could be useful for diagrams in certain parts of the document.

Files with only one revision glitch the github UI (possibly git?)

It seems that exported articles with only one commit on them are bugging the GitHub UI.
E.g. on https://github.com/gbdev/pandocs/blob/master/content/MBC1.md it shows:

0 contributors
Cannot retrieve latest commit at this time.

Clicking on "History" works so I suppose the commit is okay on the git side.
Unfortunately, " Cannot retrieve latest commit at this time" is linked to a number of different problems..

Gray background headers

As suggested by @ISSOtm to potentially fix/improve the situation described in #18 , consider gray banded brackground heading/subheadings, as in nocash docs:

This requires (and thus it's blocked by) #18 consistency in the usage of headings (h1-h4)

Use test ROMs as citations to stated facts

Credit @LIJI32

Why are there commas before h2 elements?

I noticed something while I was casually perusing Pan Docs.

In this CSS file: https://gbdev.io/pandocs/assets/css/0.styles.ba7fe2d2.css

h2 :before{content:",\2009"}

This pseudo-element seems like an odd choice. It makes all the mouse hover-triggered # anchor links on the left side of h2 headers have a comma before them, which looks wrong.

"Infinite Sex" and tobacco references in cheat section

From "Shark_Cheats.md" in the "Gamegenie" folder:

Hexadecimal codes can be then entered for specific games, typically providing things like Infinite Sex, 255 Cigarettes, or Starting directly in Wonderland Level PRO, etc.

The sex and tobacco references sound like Martin "nocash" Korth's brand of humor, as it appears in the cheating devices section of both Martin's copy of Pan Docs and GBATEK. But I'm not sure if this style is what we're going for in our copy.

Reformat "auto comments" in mediawiki revision commits

Description of FF6Ch

I recently learned here from @mattcurrie what the FF6C register is meant to represent in CGB mode. I thought it might be good to know and to document!

The "Object Priority Mode" is referring to bit 0 of $FF6C. This register is set by the CGB boot ROM to toggle between CGB object priority (prioritise by OAM position) and DMG object priority (prioritise by X coordinate):

https://github.com/ISSOtm/gb-bootroms/blob/master/src/cgb.asm#L23

Sprite Priorities and Conflicts is badly written / not fitting the documentation formal style

Feedback by @Bananattack on Discord:

There's some new commentary about certain topics like "Sprite Priorities and Conflicts", that feels much less clear than the original Pan Docs. I think the rules could be spelled out in much more clear and concise way if we plan to rewrite it. There's a bunch of parts added about specific emulators (BGB) that while handy I don't think should be in a reference doc about the hardware. The parenthesized point about z-fighting feels extraneous. The new edit still no longer mentions what "higher priority" means. It could say that entries are decided by their order in the OAM table, and that entries with a lower index have higher priority (the old document actually does mention this, but if you don't know $FExx addresess refer to OAM you may miss it). The basic rules should really be clearly summarized in a few sentences at most, instead of 4 paragraphs like it is now, or potentially some bullet points + elaboration below. If given time I can send an edit that makes this much clearer.

New suggested convention for formatting numbers, units and prefixes

Inspired by PR #54 I would like to suggest the following guidelines for how to write numbers and units:

1. These conventions should be documented near the top of the document, as needed.
2. Use the binary prefix ki (kibi) prefix when referring to 1024, and Mi (mebi) prefix when referring to 1024*1024. (Feel free to argue against this point, however. Note: binary prefixes are currently almost not used.)
3. Capitalize prefixes according to either SI or IEC standards: kilo=k, mega=M, kibi=ki, mebi=Mi. (Note: currently, kilo is fairly consistently capitalized (K) across the document.)
4. Abbreviate bytes as B when used with a prefix. Spell out bits as bits, even when used with a prefix to avoid ambiguity. (Note: currently byte is fairly consistently written as a full word.)
5. Find a suitable prefix or suffix to use for hexadecimal numbers. I'm undecided which format should be used, but I'm personally leaning toward standardizing on $ prefix which is used by RGBDS. But either way, let's decide on one and stick with it. (Note: currently it's a mix between Martin's convention of the suffix h, assembler centrix $, c-centrix 0x, and even sometimes x formatted as multiplication sign in running text, which to me just looks very wrong.)
6. To prevent clutter, don't use a prefix for hex numbers when it's clear from the context that a number is hexadecimal. For example addresses and lists of opcodes. In those cases, zero pad, even for smaller number. (Eg: 0000-3FFF instead of 0-3FFF. Note: Currently the document pretty much follows this guideline.)
7. Put a space between numbers and their unit. (Note: Currently, memory sizes are often written as 4KB or similar.)
8. Decimal numbers should be written with a decimal point instead of a comma. (I'm only bringing this up because the physical screen sizes are currently written with a decimal comma.)
9. Binary numbers: I suspect that it's sufficiently clear from context when a binary number is used. But when/if a prefix is needed, I suggest %, which is what RGBDS is using.

Feel free to discuss or add more suggestions in case I've forgotten some corner case.

Bad formatting on VRAM + OAM accessibility

Feedback by @Bananattack on Discord:

Some new notes about the VRAM + OAM accessibility make the main points about into a bolded heading, and rehash information the about STAT modes directly underneath - I think this makes it harder to read and navigate, and I think it would be clearer to list the STAT modes in one place, and just make a mention that the accessibility windows are referring to the STAT modes listed elsewhere. I think it's better to list information once and reference it, than repeat things and increase the potential for misinterpretation, or errors

Issues related to work in #59

Some more points about the work merged in #59 , raised by @ISSOtm :

For example, "this is a ROM and SRAM" is very much unclear
[11:01 PM]
There is at least one sentence beginning without uppercase
[11:02 PM]
The first line of "Echo RAM" is too long and confusing
[11:03 PM]
The IO reg table is still redundant
[11:03 PM]
The part about "returning" from FExx should mention that reads return $FF, and that writes are ignored as well

Multiple packages deprecated

When running npm install inside render, the user will get warned that chokidar 2 will break on node v14+.

The suggested fix is to update to chokidar 3. I've not tested this, and I've not looked into any of the code to see what this may or may not effect. I merely created this issue to bring it to someone's attention to look at any needed code revisions (I've got 0 node.js experience right now or I'd volunteer to do it myself).

Edit:
Will update with all the warnings.

Edit 2:

Deprecated with updates:
chokidar - will break in node v14
request - request/request#3142
urix - https://github.com/lydell/urix#deprecated
resolve-url - https://github.com/lydell/resolve-url#deprecated

No longer supported
har-valider 5.1.5
mkdirp 0.3.0 - API change with v1.x

Security issues:
fsevents v1.x - will break in node v14, is using insecure binaries.

That is as far as I get. npm fails with the error:
"Unexpected end of JSON input while parsing near '....15.1'',''eslint-config' and I can not continue getting the requirements at this point.

Citation style

We need to figure out how to cite references and how to list them.
Ideally, we'd want something similar to the LaTeX way, but I'm not sure we could plug that into markdown files without messing up the "plain vanilla" syntax

Link ports on different SGB models?

On "Separating between SGB and SGB2":

Reportedly, some SGB models include link ports (just like handheld gameboy) (my own SGB does not have such an port), possibly this feature is available in SGB2-type models only ???

404 when clicking "A list of licensee codes can be found here."

under 14B the cartridge header

Timing of several operations missing from LCD modes diagram

We need an updated version of https://gbdev.io/pandocs/imgs/game-boy-lcd-refresh-diagram.png with the following requirements:

• SVG
• More condense content / less large layout
• Move the timing examples in another figure

Multiline codeblocks have been exported as single lines

Headings are hard to discern

I'm finding it hard to tell whenever I'm moving into a new section, both because the difference in size between them isn't very clear, and because the different types of headings seem to be used inconsistently. This makes it hard for me to skim the document and find the right section.

Game Boy printer contents

There is this note, left on the Game Boy printer wiki page:

(Details and pictures , need to be copied here)

@furrtek Do you think we can translate the graphs on your website from french to english? Do you have the source/a way to regenerate them?

E.g.

Toggling SLCDC.1 mid-scanline effects

On SLCDC.1 - OBJ Display Enable:

Note: toggling mid-scanline might have funky results on DMG? Investigation needed.

Do we have any info on this?

Adding current version to exported files?

Would it be possible to add some kind of version stamp to exported files? I don't know what would be easiest or best, but for example date+commit hash or an auto-incrementing version number.

Convert Vuepress custom containers

We need a script that pattern matches Vuepress custom containers, the syntax generating the info/error/warning boxes and converts them in plain text/latex/... to keep the markdown files agnostic and not tied not one tool

See #7

Game Boy Printer conversion ignored rowspan

Three fields in the Game Boy Printer packet format are two bytes in length: "Magic bytes", "Length of data", and "Checksum". The table in the old version used colspan="2" to expand "Description" and "Size" to span two columns of "GB to Printer" and "Printer to GB". The conversion was transposed to look better on narrow screens of handheld computers: columns became rows, and rows became columns. It could have used rowspan="2" to expand them, or it could have taken both of the byte values in one cell. But instead, they are misaligned, with the second byte of each field pushing the following fields down a row.

• "Magic bytes" should be "$88, $33" and "Command" should be "See below", but the conversion has "Command" set to "$33" and "Compression flag" set to "See below".
• "Length of data" should be "LSB, MSB", but the conversion has "Command-specific data" set to "LSB" and "Checksum" set to "MSB".
• "Checksum" should be "LSB, MSB", but the conversion has "Status" set to "LSB" and the second half of the field cut off the end of the table.

Mistake for NR52

I am working on a disassembled Pokemon game and came across the following

.ch1_rest
    ldh a, [rNR52]
    and %10001110 ; ch1 off
    ldh [rNR52], a
    ld hl, rNR10
    call ClearChannel
    ret 

If bit 0-3 are read only, how is this possible?
I looked at the technical reference: [removed] and bit 0-3 are actually read/write.

Slower SGB/gameboy timings when on 50Hz SNES?

On "SGB System Clock":

Also, I think that I've heard that SNES models which use a 50Hz display refresh rate (rather than 60Hz) are resulting in respectively slower SGB/gameboy timings ???

I think this is true, do we have detailed info/sources?

Remove personal considerations / investigations

Make the statements impersonal and maybe use a different style when investigating an unknown behaviour?

E.g. https://github.com/gbdev/pandocs/blob/0e60f72f08423d11207c9a7814d2ef4df1c30089/content/SGB_Functions.md#separating-between-sgb-and-sgb2

Proof readings, typos fixing

Duplicate pages

The entire "Pan Docs" wiki category has been exported, but it seems that (e.g.) MBC1 is more updated on the more general Memory Bank Controllers page

Mediawiki Export requirement.txt wrong?

pandocs/mediawiki-exporter/requirements.txt

Lines 1 to 2 in 6c8e2ff

	untangle==1.1.1
	xmltodict==0.12.0

I don't see untangle being used by the Python script (and it look like it would be redundant to xmltodict anyway). The requirements are also missing pypandoc.

Failing to commit

Sometimes, the script is giving "nothing to commit" but I can't track down the Issue.. E.g. revisions 160 and 179 are having this behaviour

Empty sidebar?

Remove the sidebar if we don't plan on using it

Explain the document target

Pandocs is usually targeted at homebrew developers, while Gekkio's GB-CTR is more interesting for emulator developers. It may be worth mentioning this at the start of the document

VGA_versus_CGB broken image

https://gbdev.io/pandocs/VGA_versus_CGB.png gives 404

Documentation style guidelines

Some guidelines on the style we should adopt/apply suggested by @Bananattack :

• use consistent formatting;
• any new information / rewrites should be written clearer than the original;
• keep things concise and short;
• don't repeat information like register/mode descriptions, reference/backlink to existing information instead;
• present things as clear rules/definitions first, then explain or elaborate after.

Related issues:
#55

Registers formatting

Feedback by @Bananattack on Discord:

Hmm, I noticed the formatting for registers on the new pandocs is a funky right now:

1. It's currently inconsistent about whether a hardware register lists its hex address, a symbolic name, or its descriptive "full name". It should probably do all 3, in the order of "hex address - symbolic name - full name"
2. LCDC is missing its hex address, and is only called LCD Controller Register in the header.
3. Hexadecimal values should probably start with a $ to more clearly call out the numeric base.
4. The convention for indicating read/write of a register is inconsistent, sometimes it's (R/W), sometimes it's (Read/Write)

@endrift 's gbdoc (https://github.com/mgba-emu/gbdoc/blob/gh-pages/index.md#mmio) has a very nice way of documenting registers

PDF export

Dan Docs

Dan Docs documents more obscure Game Boy hardware.
It is rendered from here https://github.com/shonumi/shonumi.github.io/blob/master/dandocs.html, which in turns comes from GBE docs : https://github.com/shonumi/gbe-plus/blob/master/src/docs/technical/dandocs.html, manually converted to HTML from the TXT files in the same folder, like this one: https://github.com/shonumi/gbe-plus/blob/master/src/docs/technical/Mobile_Adapter_GB.txt

We could script something to automatically render those TXT as MD and then have our new Pan Docs website render an updated (an in sync with Shonumi/GBE docs) version of Dan Docs.

Dan Docs is public domain, but the author, @shonumi mentioned:

There may be an issue with some disassembly from Zok Zok Heroes (which I've been meaning to address).

Viewport is too "cramped"

The current combination of font size and viewport width seems rather extreme to me, yielding nice views like this on my current laptop:

This is definitely... readable, and in my opinion would be well-fit for a blog or some piece of recreational writing, but when reading technical documentation I value being able to fit more on my screen, both to minimize scrolling and to better locate myself in the document.

Text really doesn't need to be as huge.

Use of single or double quotes

E.g. in CGB Registers

Links are broken

Everything is broken :)
Wiki links and internal (anchor) links must be cleaned up and updated.
Some external links needs to be fixed, too.

Anchor links not working in Chromium based browsers

Links to headers like https://gbdev.io/pandocs/#vram-background-maps seem to work in Firefox but not in Chrome

MBC1 description has an open sentence

Under "6000-7FFF - Banking Mode Select (Write Only)" in the MBC1 Control Registers section there is an open sentence, "For large ROM carts, the".

Syntax highlighting in Code Blocks - GBZ80

Syntax highlighting is provided by Prism. Here's an example of language definition (6502 Assembly) for it.

It should be trivial to produce something similar for the RGBDS/GBZ80 style assembly

@ISSOtm worked on something similar for highlight.js - imo we should just convert that language file in the format PrimJS requires.

Usage of Vuepress' Custom Containers

Example:

Vuepress plugin: https://vuepress.github.io/en/plugins/container/#render

MBC1 & MBC6 titles broken

Titles for MBC1 and MBC6 are broken in the PDF export.

ToC depth

We need to revision and possibily rethink how deep is the ToC, since it provides the main way to navigate the document.

From a comment on Discord:

Yeah, I think that is a key issue in finding info quicky. The video section has only 1 main header but contains a lot of information in subheaders.

Toggling LCDC.5 mid-scanline effects

On "LCDC.5 - Window Display Enable"

This bit controls whether the window shall be displayed or not. (TODO : what happens when toggling this mid-scanline ?) This bit is overridden on DMG by bit 0 if that bit is reset.

z80 vs "gbz80"

http://www.z80.info/z80gboy.txt

Mention the author, too (references)

Document the GBC approval process

Following gbdev/awesome-gbdev#197, we may want to rewrite that part of the manual in pandocs