Cleanup of MBC1 docs (#312)

* Cleanup of MBC1 docs

* Remove 2 kB RAM size

* Review feedback

Co-authored-by: Eldred Habert <[email protected]>

Co-authored-by: Eldred Habert <[email protected]>

Author: TheThief

src/MBC1.md

@@ -7,6 +7,11 @@ work similarly, so it is relatively easy to upgrade a program from one
 MBC chip to another - or to make it compatible with several different
 types of MBCs.
 
+In its default configuration, MBC1 supports up to 512 KiB ROM with up to 32 KiB of banked RAM.
+Some cartridges wire the MBC differently, where the 2-bit RAM banking register is wired as an extension of the ROM banking register (instead of to RAM) in order to support up to 2 MiB ROM, at the cost of only supporting a fixed 8 kiB of cartridge RAM.
+All MBC1 cartridges with 1 MiB of ROM or more use this alternate wiring.
+Also see the note on MBC1M multi-game compilation carts below.
+
 Note that the memory in range 0000-7FFF is used both for reading from
 ROM and writing to the MBCs Control Registers.
 
@@ -15,65 +20,71 @@ ROM and writing to the MBCs Control Registers.
 ### 0000-3FFF - ROM Bank X0 (Read Only)
 
 This area normally contains the first 16 KiB (bank 00) of the cartridge
-ROM. Can contain banks $20/$40/$60 in mode 1 (see below), or banks $10/$20/$30
-in mode 1 for a 1MB MBC1 multi-cart (see below).
+ROM.
+
+In 1 MiB and larger cartridges (that use the 2-bit second banking register for extended ROM banking), entering mode 1 (see below) will allow that second banking register to apply to reads from this region in addition to the regular 4000-7FFF banked region, resulting in accessing banks $20/$40/$60 for regular large ROM carts, or banks $10/$20/$30 for an MBC1M multi-cart (see note below).
 
 ### 4000-7FFF - ROM Bank 01-7F (Read Only)
 
-This area may contain any of the further 16 KiB banks of the ROM. Cannot
-address any banks where the main ROM banking register would be $00, which
-usually means banks $00/$20/$40/$60. Instead, it automatically maps to 1 bank
-higher ($01/$21/$41/$61).
+This area may contain any of the further 16 KiB banks of the ROM. If the main 5-bit ROM banking register is 0, it reads the bank as if it was set to 1.
+
+For 1 MiB+ ROM, this means any bank that is possible to accessible via the 0000-3FFF region is not accessible in this region. i.e. banks $00/$20/$40/$60 in regular large ROM carts, or banks $00/$01/$20/$30 in MBC1m multi-game compilation carts. Instead, it automatically maps to 1 bank
+higher ($01/$21/$41/$61 or $01/$11/$21/$31 respectively).
 
 ### A000-BFFF - RAM Bank 00-03, if any (Read/Write)
 
-This area is used to address external RAM in the cartridge (if any).
-External RAM is often battery-backed, allowing for the storage of game data while the Game Boy is turned off, or if the
-cartridge is removed from the Game Boy. Available RAM sizes are: 2 KiB
-(at $A000-$A7FF), 8 KiB (at $A000-$BFFF) and 32 KiB (in form of four 8K
-banks at $A000-$BFFF).
+This area is used to address external RAM in the cartridge (if any). The RAM is only accessible if RAM is enabled, otherwise reads return open bus values (often $FF, but not guaranteed) and writes are ignored.
+
+Available RAM sizes are 8 KiB (at $A000-$BFFF) and 32 KiB (in form of four 8K banks at $A000-$BFFF). 32 kiB is only available in cartridges with ROM <= 512 kiB.
+
+External RAM is often battery-backed, allowing for the storage of game data while the Game Boy is turned off, or if the cartridge is removed from the Game Boy. External RAM is no slower than the Game Boy's internal RAM, so many games use part of the external RAM as extra working RAM, even if they use another part of it for battery-backed saves.
 
 ## Registers
 
+All of the MBC1 registers default to 00h on power-up, which for the "ROM Bank Number" register is _treated as_ 01h.
+
 ### 0000-1FFF - RAM Enable (Write Only)
 
 Before external RAM can be read or written, it must be enabled by
-writing to this address space. It is recommended to disable external RAM
-after accessing it, in order to protect its contents from corruption during
-power down of the Game Boy. Usually the following values are used:
+writing $A to this address space.
+Any value with $A in the lower 4 bits enables the RAM attached to the MBC and any
+other value disables the RAM. It is unknown why $A is the value used to enable RAM.
 
 ```
-00h  Disable RAM (default)
-0Ah  Enable RAM
+$00  Disable RAM (default)
+$0A  Enable RAM
 ```
 
-Practically any value with 0Ah in the lower 4 bits enables RAM and any
-other value disables RAM. RAM is automatically disabled when the gameboy
-is powered off. It is unknown why Ah is the value used to enable RAM.
+It is recommended to disable external RAM
+after accessing it, in order to protect its contents from corruption during
+power down of the Game Boy or removal of the cartridge. Once the cartridge has _completely_ lost power from the Game Boy, the RAM is automatically disabled to protect it.
 
 ### 2000-3FFF - ROM Bank Number (Write Only)
 
-This 5-bit register (range $01-$1F) selects the ROM bank number. Higher
-bits are discarded - $E1 (binary ~~111~~00001) would select bank $01.
+This 5-bit register (range $01-$1F) selects the ROM bank number for the 4000-7FFF region. Higher
+bits are discarded - writing $E1 (binary ~~111~~00001) to this register
+would select bank $01.
+
+If this register is set to $00, it behaves as if it is set to $01. This means you cannot duplicate bank $00 into both the 0000-3FFF and 4000-7FFF ranges by setting this register to $00.
+
 If the ROM Bank Number is set to a higher value than the number of banks
 in the cart, the bank number is masked to the required number of bits.
 e.g. a 256 KiB cart only needs a 4-bit bank number to address all of its
 16 banks, so this register is masked to 4 bits. The upper bit would be
-ignored.
+ignored for bank selection.
+
+Even with smaller ROMs that use less than 5 bits for bank selection, the full 5-bit register is still compared for the bank 00->01 translation logic. As a result if the ROM is 256 kiB or smaller, it _is_ possible to map bank 0 to the 4000-7FFF region - by setting the 5th bit to 1 it will prevent the 00->01 translation (which looks at the full 5-bit register, and sees the value $10, not $00), while the bits actually used for bank selection (4, in this example) are all 0, so bank $00 is selected.
 
 On larger carts which need a >5 bit bank number, the secondary banking
 register at 4000-5FFF is used to supply an additional 2 bits for the
 effective bank number:
-`Selected ROM Bank = (Secondary Bank << 5) + ROM Bank`.
-
-The ROM Bank Number defaults to 01 at power-on. When 00 is written,
-the MBC translates that to bank 01 also. Not being able to select bank
-00 isn't normally a problem, because bank 00h is usually mapped to the
-0000-3FFF range. But on large carts (using the secondary banking register
-to specify the upper ROM Bank bits), the same happens for banks $20, $40,
-and $60, as this register would need to be 00 for those addresses. Any
+`Selected ROM Bank = (Secondary Bank << 5) + ROM Bank`.[^MBC1M_banking]
+
+[^MBC1M_banking]: MBC1M has a different formula, see below
+
+These additional two bits are ignored for the bank 00->01 translation. This causes a problem - attempting to access banks 20h, 40h, and 60h only set bits in the upper 2-bit register, with the lower 5-bit register set to 00. As a result, any
 attempt to address these ROM Banks will select Bank $21, $41 and $61
-instead. The only way to access banks $20, $40 or $60 is to enter mode 1,
+instead. The only way to access banks $20, $40 or $60 at all is to enter mode 1,
 which remaps the 0000-3FFF range. This has its own problems for game
 developers as that range contains interrupt handlers, so it's usually only
 used in multi-game compilation carts (see below).
@@ -93,39 +104,88 @@ applied to bits 4-5 of the ROM bank number and the top bit of the main
 
 This 1-bit register selects between the two MBC1 banking modes, controlling
 the behaviour of the secondary 2-bit banking register (above). If the cart
-is not large enough to use the 2-bit register (<= 8 KiB RAM / <= 512 KiB ROM)
+is not large enough to use the 2-bit register (<= 8 KiB RAM and <= 512 KiB ROM)
 this mode select has no observable effect. The program may freely switch
 between the two modes at any time.
 
 ```
-00 = Simple ROM Banking Mode (default)
+00 = Simple Banking Mode (default)
+     0000-3FFF and A000-BFFF locked to bank 0 of ROM/RAM
 01 = RAM Banking Mode / Advanced ROM Banking Mode
+     0000-3FFF and A000-BFFF can be bank-switched via the 4000-5FFF bank register
 ```
 
-In mode 0, the 2-bit secondary banking register can only affect the
-4000-7FFF banked ROM area. If the cart is a "small ROM"/"large RAM" cart
-(< 1 MiB ROM, > 8 KiB RAM) then 4000-7FFF is unaffected by this register anyway,
-so the practical effect is that RAM banking is disabled and A000-BFFF is
-locked to only be able to access bank 0 of RAM, with the 2-bit secondary
-banking register entirely ignored.
+Technically, the MBC1 has AND gates between the both bank registers and the second highest bit of the address. This is intended to cause accesses to the 0000-3FFF region (which has that addess bit set to 0) to treat both registers as always 0, so that only bank 0 is accessible through this address.
 
-In mode 1, the behaviour differs depending on whether the current cart is
-a "large RAM" cart (> 8 KiB RAM) or "large ROM" cart (1 MB or larger). For
-large RAM carts, switching to mode 1 enables RAM banking and (if RAM is
-enabled) immediately switches the A000-BFFF RAM area to the bank selected
-by the 2-bit secondary banking register.
+However, when the second bank register is connected to RAM, this has the side effect of also locking RAM to bank 0, as the RAM address space (A000-BFFF) _also_ has the second highest address bit set to 0.
+
+Setting the mode to 1 disables these AND gates, allowing the two-bit register to switch the selected bank in both these regions.
+
+## Addressing diagrams
+
+The following diagrams show how the address within the ROM/RAM chips are calculated from the accessed address and banking registers
+
+### 0000-3FFF
+
+In mode 0:
+
+```
+Bits: 20 19 18 17 16 15 14 13 12 .. 01 00
+      \___/ \____________/ \____________/
+        |          |            \----------- From Game Boy address
+        |          \------------------------ Always 0
+        \----------------------------------- Always 0
+```
+
+In mode 1:
+
+```
+Bits: 20 19 18 17 16 15 14 13 12 .. 01 00
+      \___/ \____________/ \____________/
+        |          |            \----------- From Game Boy address
+        |          \------------------------ Always 0
+        \----------------------------------- As 4000-5FFF bank register
+```
 
-For "large ROM" carts, mode 1 has the 4000-7FFF banked ROM area behave the
-same as mode 0, but additionally the "unbankable" "bank 0" area 0000-3FFF
-is now also affected by the 2-bit secondary banking register, meaning it
-can now be switched between banks $00, $20, $40 and $60. These banks are
-inaccessible in mode 0 - they cannot be mapped to the 4000-7FFF banked ROM
-area.
+### 4000-7FFF
 
-### Note for 1 MB Multi-Game Compilation Carts
+Regardless of mode:
 
-Also known as MBC1m, these carts have an alternative wiring, that ignores
-the top bit of the main ROM banking register (making it a 4-bit register)
+```
+                              /------------- In a smaller cart, only the needed
+                              |              bits are used (e.g 128kiB uses 17)
+                  /---------------------\
+Bits: 20 19 18 17 16 15 14 13 12 .. 01 00
+      \___/ \____________/ \____________/
+        |          |            \----------- From Game Boy address
+        |          \------------------------ As 2000-3FFF bank register
+        \----------------------------------- As 4000-5FFF bank register
+```
+
+### A000-BFFF
+
+In mode 0:
+
+```
+Bits: 14 13 12 .. 01 00
+      \___/ \_________/
+        |        \-------- From Game Boy address
+        \----------------- Always 0
+```
+
+In mode 1:
+
+```
+Bits: 14 13 12 .. 01 00
+      \___/ \_________/
+        |        \-------- From Game Boy address
+        \----------------- As 4000-5FFF bank register
+```
+
+## "MBC1M" 1 MiB Multi-Game Compilation Carts
+
+Known as MBC1M, these carts have an alternative wiring, that ignores
+the top bit of the main ROM banking register (making it effectively a 4-bit register for banking, though the full 5 bit register is still used for 00->01 translation)
 and applies the 2-bit register to bits 4-5 of the bank number (instead of
 the usual bits 5-6). This means that in mode 1 the 2-bit register selects
 banks $00, $10, $20, or $30, rather than the usual $00, $20, $40 or $60.
@@ -144,6 +204,33 @@ having duplicate content in banks $10-$1F (dupe of $00-$0F) and banks $30-$3F
 There is a known bad dump of the Mortal Kombat I & II collection around.
 
 An "MBC1M" compilation cart ROM can be converted into a regular MBC1 ROM
-by increasing the ROM size to 2MB and duplicating each sub-rom - 00-0Fh
+by increasing the ROM size to 2 MiB and duplicating each sub-rom - $00-$0F
 duplicated into $10-$1F, the original $10-$1F placed in $20-$2F and
 duplicated into $30-$3F and so on.
+
+## MBC1M addressing diagrams:
+
+### 0000-3FFF
+
+(In mode 1)
+
+```
+Bits: 19 18    17 16 15 14 13 12 .. 01 00
+      \___/ \____________/ \____________/
+        |          |            \----------- From Game Boy address
+        |          \------------------------ Always 0
+        \----------------------------------- As 4000-5FFF bank register
+```
+
+### 4000-7FFF
+
+Regardless of mode:
+
+```
+Bits: 19 18    17 16 15 14 13 12 .. 01 00
+      \___/ \____________/ \____________/
+        |          |            \----------- From Game Boy address
+        |          \------------------------ As 2000-3FFF bank register
+        |                                       (only 4 bits used)
+        \----------------------------------- As 4000-5FFF bank register
+```