GBDK 2020 Docs
API Documentation for GBDK 2020
|
The standard Game Boy cartridge with no MBC has a fixed 32K bytes of ROM. In order to make cartridges with larger ROM sizes (to store more code and graphics) MBCs can be used. They allow switching between multiple ROM banks that use the same memory region. Only one of the banks can be selected as active at a given time, while all the other banks are inactive (and so, inaccessible).
Cartridges with no MBC controller are unbanked, they have 32K bytes of fixed ROM space and no switchable banks. For these cartridges the ROM space between 0000h and 7FFFh
can be treated as a single large bank of 32K bytes, or as two contiguous banks of 16K bytes in Bank 0 at 0000h - 3FFFh
and Bank 1 at 4000h to 7FFFh
.
Cartridges with MBCs allow the the Game Boy to work with ROMS up to 8MB in size and with RAM up to 128kB. Each bank is 16K Bytes.
0000h - 3FFFh
. It is usually fixed (unbanked) and cannot be switched out for another bank.4000h to 7FFFh
is used for switching between different ROM banks.See the Pandocs for more details about the individual MBCs and their capabilities.
To assign code and constant data (such as graphics) to a ROM bank and use it:
The ROM and RAM bank for a source file can be set in a couple different ways. Multiple different banks cannot be assigned inside the same source file (unless the __addressmod
method is used), but multiple source files can share the same bank.
If no ROM and RAM bank are speciied for a file then the default _CODE, _BSS and _DATA segments are used.
Ways to set the ROM bank for a Source file
#pragma bank <N>
at the start of a source file. Example (ROM bank 2): #pragma bank 2
-Wf-bo<N>
. Example (ROM bank 2): -Wf-bo2
Note: You can use the UNBANKED
keyword to define a function as unbanked if it resides in a source file which has been assigned a bank.
-Wf-ba<N>
. Example (RAM bank 3): -Wf-bo3
At the link stage this is done with lcc using pass-through switches for makebin.
-Wl-yo<N>
where <N>
is the number of ROM banks. 2, 4, 8, 16, 32, 64, 128, 256, 512-Wl-ya<N>
where <N>
is the number of RAM banks. 2, 4, 8, 16, 32-Wl-yt<N>
where <N>
is the type of MBC cartridge (see below).The following MBC settings are available when using the makebin MBC switch.
Banked functions can be called as follows.
BANKED
keyword. Example: void my_function() BANKED { do stuff }
in a source file which has had it's bank set (see above).__addressmod
keyword (See the banks_new
example project and the SDCC manual for details)Unbanked functions (either in fixed Bank 0, or in an Unbanked ROM with no MBC)
Limitations:
Far pointers include a segment (bank) selector so they are able to point to addresses (functions or data) outside of the current bank (unlike normal pointers which are not bank-aware). A set of macros is provided by GBDK 2020 for working with far pointers.
Warning: Do not call the far pointer function macros from inside interrupt routines (ISRs). The far pointer function macros use a global variable that would not get restored properly if a function called that way was interrupted by another one called the same way. However, they may be called recursively.
See FAR_CALL, TO_FAR_PTR and the banks_farptr
example project.
You can manually switch banks using the SWITCH_ROM_MBC1(), SWITCH_RAM_MBC1(), and other related macros. See banks.c
project for an example.
Note: You can only do a switch_rom_bank call from unbanked _CODE
since otherwise you would switch out the code that was executing. Global routines that will be called without an expectation of bank switching should fit within the limited 16k of unbanked _CODE
.
If a function call is made inside an ISR which changes the bank without restoring it, then the _current_bank variable should be saved and then restored.
For example, instead of this code:
It should be:
The global variable _current_bank is updated automatically when calling SWITCH_ROM_MBC1() and SWITCH_ROM_MBC5, or when a BANKED
function is called.
A ROM bank auto-assignment feature was added in GBDK 2020 4.0.2.
Instead of having to manually specify which bank a source file will reside it, the banks can be assigned automatically to make the best use of space. The bank assignment operates on object files, after compiling/assembling and before linking.
To turn on auto-banking, use the -autobank
argument with lcc
For a source example see the banks_autobank
project.
In the source files you want auto-banked, do the following:
255
: #pragma bank 255
const void __at(255) __bank_<name-for-a-given-source-file>;
. (UINT8)&__bank_<name-for-a-given-source-file
.Example: level_1_map.c
#pragma bank 255 const void __at(255) __bank_level_1_map; const UINT8 my_level_1_map[] = {... some map data here ...};
Accessing that data: main.c
SWITCH_ROM_MBC1( (UINT8)&__bank_level_1_map ); // Do something with my_level_1_map[]
Features and Notes:
Making sure bankpack checks all files:
-ext=
flag and save the auto-banked output to a different extension (such as .rel
) and then pass the modified files to the linker. That way all object files will be processed each time the program is compiled. Recommended: .c and .s -> (compiler) .o -> (bankpack) -> .rel -> (linker) ... -> .gb
Limitations:
A bank overflow during compile/link time (in makebin) is when more code and data are allocated to a ROM bank than it has capacity for. The address for any overflowed data will be incorrect and the data is potentially unreachable since it now resides at the start of a different bank instead of the end of the expected bank.
The current toolchain can only detect and warn (using ihxcheck) when one bank overflows into another bank that has data at its start. It cannot warn if a bank overflows into an empty one. For more complete detection , you can use the third-party romusage tool.
In order to see how much space is used or remains available in a bank, you can use the third-party romusage tool.
There are several projects in the GBDK 2020 examples folder which demonstrate different ways to use banking.
Banks
: A basic banking exampleBanks_new
: Examples of using new bank assignment and calling conventions available in GBDK 2020 and it's updated SDCC version.Banks_farptr
: Using far pointers which have the bank number built into the pointer.Banks_autobank
: Shows how to use the bank auto-assignment feature of in GBDK 2020 4.0.2 or later, instead of having to manually specify which bank a source file will reside it.