gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 2fc06c126512cec481e0101a20f37b58d4ddc489 parent 58e177ba92a43fb46e3282ac99150194dec73010 Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Mon, 24 Oct 2022 20:08:20 -0700 Merge pull request #427 from bbbbbr/docs_4_1_0 Docs: 4.1.0: isr handler updates, release notes, MBC updates Diffstat:
| M | docs/pages/05_banking_mbcs.md | 92 | +++++++++++++++++++++++++++++++++++++++++++++++-------------------------------- |
| M | docs/pages/10_release_notes.md | 1 | + |
| M | docs/pages/20_toolchain_settings.md | 3 | ++- |
| M | gbdk-lib/include/gb/gb.h | 20 | ++++++++++++++++++-- |
4 files changed, 76 insertions(+), 40 deletions(-)
diff --git a/docs/pages/05_banking_mbcs.md b/docs/pages/05_banking_mbcs.md @@ -17,10 +17,18 @@ Cartridges with MBCs allow the the Game Boy to work with ROMS up to 8MB in size - Bank `0` of the ROM is located in the region at `0000h - 3FFFh`. It is fixed (non-banked) and cannot be switched out for another bank. - Banks `1 .. N` can be switched into the upper region at `4000h - 7FFFh`. The upper limit for `N` is determined by the MBC used and available cartridge space. - It is not necessary to manually assign Bank `0` for source files, that will happen by default if no bank is specified. - + See the @ref Pandocs for more details about the individual MBCs and their capabilities. +## Recommended MBC type +@anchor Recommended_MBC + +For most projects we recommend __MBC5__. + - The @ref SWITCH_ROM() / ref SWITCH_RAM() macros work with MBC5 (up to ROM bank 255, @ref SWITCH_ROM_MBC5_8M may be used if a larger size is needed). + - __MBC1 is not recommended__. Some banks in it's range are unavailable. See pandocs for more details. https://gbdev.io/pandocs/MBC1 + + ### Bank 0 Size Limit and Overlows When Using MBCs When using MBCs and bank switching the space used in the lower fixed Bank `0` **must be <= 16K bytes**. Otherwise it's data will overflow into Bank `1` and may be overwriten or overwrite other data, and can get switched out when banks are changed. @@ -73,7 +81,7 @@ The MBC settings below are available when using the makebin `-Wl-yt<N>` switch. Source: Pandocs. Additional details available at [Pandocs](https://gbdev.io/pandocs/The_Cartridge_Header.html#0147---cartridge-type "Pandocs") -## MBC Type Chart +# MBC Type Chart ``` 0147: Cartridge type: 0x00: ROM ONLY 0x12: ROM+MBC3+RAM @@ -94,41 +102,51 @@ Source: Pandocs. Additional details available at [Pandocs](https://gbdev.io/pand @anchor mbc_type_chart -| Hex Code | MBC Type | SRAM | BATTERY | RTC | RUMBLE | EXTRA | -| -------- | ------------- | ---- | ------- | --- | ------ | ------ | -| 0x00 | ROM ONLY | | | | | | -| 0x01 | MBC-1 | | | | | | -| 0x02 | MBC-1 | SRAM | | | | | -| 0x03 | MBC-1 | SRAM | BATTERY | | | | -| 0x05 | MBC-2 | | | | | | -| 0x06 | MBC-2 | | BATTERY | | | | -| 0x08 | ROM (1) | SRAM | | | | | -| 0x09 | ROM (1) | SRAM | BATTERY | | | | -| 0x0B | MMM01 | | | | | | -| 0x0C | MMM01 | SRAM | | | | | -| 0x0D | MMM01 | SRAM | BATTERY | | | | -| 0x0F | MBC-3 | | BATTERY | RTC | | | -| 0x10 | MBC-3 (2) | SRAM | BATTERY | RTC | | | -| 0x11 | MBC-3 | | | | | | -| 0x12 | MBC-3 (2) | SRAM | | | | | -| 0x13 | MBC-3 (2) | SRAM | BATTERY | | | | -| 0x19 | MBC-5 | | | | | | -| 0x1A | MBC-5 | SRAM | | | | | -| 0x1B | MBC-5 | SRAM | BATTERY | | | | -| 0x1C | MBC-5 | | | | RUMBLE | | -| 0x1D | MBC-5 | SRAM | | | RUMBLE | | -| 0x1E | MBC-5 | SRAM | BATTERY | | RUMBLE | | -| 0x20 | MBC-6 | | | | | | -| 0x22 | MBC-7 | SRAM | BATTERY | | RUMBLE | SENSOR | -| 0xFC | POCKET CAMERA | | | | | | -| 0xFD | BANDAI TAMA5 | | | | | | -| 0xFE | HuC3 | | | | | | -| 0xFF | HuC1 | SRAM | BATTERY | | | | - - -1: No licensed cartridge makes use of this option. Exact behaviour is unknown. - -2: MBC3 with RAM size 64 KByte refers to MBC30, used only in Pocket Monsters Crystal Version for Japan. +| Hex Code | MBC Type | SRAM | Battery | RTC | Rumble | Extra | Max ROM Size (1)| +| -------- | ------------- | ---- | ------- | --- | ------ | ------ | --------------- | +| 0x00 | ROM ONLY | | | | | | 32 K | +| 0x01 | MBC-1 (2) | | | | | | 2 MB | +| 0x02 | MBC-1 (2) | SRAM | | | | | 2 MB | +| 0x03 | MBC-1 (2) | SRAM | BATTERY | | | | 2 MB | +| 0x05 | MBC-2 | | | | | | 256 K | +| 0x06 | MBC-2 | | BATTERY | | | | 256 K | +| 0x08 | ROM (3) | SRAM | | | | | 32 K | +| 0x09 | ROM (3) | SRAM | BATTERY | | | | 32 K | +| 0x0B | MMM01 | | | | | | 8 MB / N | +| 0x0C | MMM01 | SRAM | | | | | 8 MB / N | +| 0x0D | MMM01 | SRAM | BATTERY | | | | 8 MB / N | +| 0x0F | MBC-3 | | BATTERY | RTC | | | 2 MB | +| 0x10 | MBC-3 (4) | SRAM | BATTERY | RTC | | | 2 MB | +| 0x11 | MBC-3 | | | | | | 2 MB | +| 0x12 | MBC-3 (4) | SRAM | | | | | 2 MB | +| 0x13 | MBC-3 (4) | SRAM | BATTERY | | | | 2 MB | +| 0x19 | MBC-5 | | | | | | 8 MB | +| 0x1A | MBC-5 | SRAM | | | | | 8 MB | +| 0x1B | MBC-5 | SRAM | BATTERY | | | | 8 MB | +| 0x1C | MBC-5 | | | | RUMBLE | | 8 MB | +| 0x1D | MBC-5 | SRAM | | | RUMBLE | | 8 MB | +| 0x1E | MBC-5 | SRAM | BATTERY | | RUMBLE | | 8 MB | +| 0x20 | MBC-6 | | | | | | ~2MB | +| 0x22 | MBC-7 | SRAM | BATTERY | | RUMBLE | SENSOR | 2MB | +| 0xFC | POCKET CAMERA | | | | | | To Do | +| 0xFD | BANDAI TAMA5 | | | | | | To Do | +| 0xFE | HuC3 | | | RTC | | | To Do | +| 0xFF | HuC1 | SRAM | BATTERY | | | IR | To Do | + + +1: Max possible size for MBC is shown. When used with generic @ref SWITCH_ROM() the max size may be smaller. For example: + - The max for MBC1 becomes __Bank 31__ (512K) + - The max for MBC5 becomes __Bank 255__(4MB). To use the full size of MBC5 see @ref SWITCH_ROM_MBC5_8M(). + +2: For MBC1 some banks in it's range are unavailable. See pandocs for more details https://gbdev.io/pandocs/MBC1 + +3: No licensed cartridge makes use of this option. Exact behaviour is unknown. + +4: MBC3 with RAM size 64 KByte refers to MBC30, used only in Pocket Monsters Crystal Version for Japan. + + + + ## Getting Bank Numbers diff --git a/docs/pages/10_release_notes.md b/docs/pages/10_release_notes.md @@ -52,6 +52,7 @@ https://github.com/gbdk-2020/gbdk-2020/releases - Fixed `Warning: File read size didn't match expected` - @ref lcc "lcc" - When `-autobank` is specified `lcc` will automatically add `-yoA` for @ref makebin if no `-yo*` entry is present + - Fixed broken `-E` Preprocess only flag - @ref utility_makecom "makecom" - Added `makecom` for post-processing msxdos binary - @ref makebin diff --git a/docs/pages/20_toolchain_settings.md b/docs/pages/20_toolchain_settings.md @@ -12,7 +12,8 @@ -dn set switch statement density to `n' -debug Turns on --debug for compiler, -y (.cdb) and -j (.noi) for linker -Dname -Dname=def define the preprocessor symbol `name' --E run only the preprocessor on the named C programs and unsuffixed files +-E only run preprocessor on named .c and .h files files -> stdout +--save-preproc Use with -E for output to *.i files instead of stdout -g produce symbol table information for debuggers -help or -? print this message -Idir add `dir' to the beginning of the list of #include directories diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -517,6 +517,11 @@ __endasm; \ /** Makes MBC1 and other compatible MBCs switch the active ROM bank @param b ROM bank to switch to + + For MBC1 some banks in it's range are unavailable + (typically 0x00, 0x20, 0x40, 0x60). + + See pandocs for more details https://gbdev.io/pandocs/MBC1 */ #define SWITCH_ROM_MBC1(b) \ _current_bank = (b), *(volatile uint8_t *)0x2000 = (b) @@ -524,6 +529,13 @@ __endasm; \ /** Makes default platform MBC switch the active ROM bank @param b ROM bank to switch to (max 255) + \li When used with MBC1 the max bank is Bank 31 + \li When used with MBC5 the max bank is Bank 255 + \li To use the full size of MBC5 see @ref SWITCH_ROM_MBC5_8M() + + \li For MBC1 some banks in it's range are unavailable + (typically 0x00, 0x20, 0x40, 0x60). + @see SWITCH_ROM_MBC1, SWITCH_ROM_MBC5, SWITCH_ROM_MEGADUCK */ #if defined(__TARGET_duck) @@ -565,8 +577,12 @@ __endasm; \ #define SWITCH_4_32_MODE_MBC1 \ *(volatile uint8_t *)0x6000 = 0x01 -/** Makes MBC5 switch to the active ROM bank; only 4M roms are supported, @see SWITCH_ROM_MBC5_8M() - @param b ROM bank to switch to +/** Makes MBC5 switch to the active ROM bank + @param b ROM bank to switch to (max 255) + + Supports up to ROM bank 255 (4 MB). + + @ref SWITCH_ROM_MBC5_8M may be used if a larger size is needed. Note the order used here. Writing the other way around on a MBC1 always selects bank 1 */
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.