GBDK 2020 Docs  4.3.0
API Documentation for GBDK 2020
Migrating to new GBDK Versions

This section contains information that may be useful to know or important when upgrading to a newer GBDK release.

GBDK-2020 versions

Porting to GBDK-2020 4.3.0

  • GBDK now requires ~SDCC 4.4.0 or higher with GBDK-2020 patches for the z80 and NES
  • Changed to new calling convention for printf(), sprintf(), abs()
  • Changed to new SDCC calling convention for set_bkg_tile_xy(), set_win_tile_xy()
  • The SDCC object file format (.o, .rel files) changed from XL3 (24 bit addresses) to XL4 (32 bit addresses)
    • Bankpack now supports both
  • Recommend using:
  • NES set_sprite_palette() now indexes from 0..3 instead of 4..7
  • png2asset:
    • If using either -bpp 1 or -pack_mode 1bpp then the other is auto-enabled
    • Significant bug fixes and changes, check to make sure output is as expected

Porting to GBDK-2020 4.2.0

Porting to GBDK-2020 4.1.1

  • No significant changes required

Porting to GBDK-2020 4.1.0

  • GBDK now requires SDCC 4.2 or higher with GBDK-2020 patches for the z80 linker
  • The default calling convention changed in SDCC 4.2, see Calling Conventions for more details.
    • If you are linking to libraries compiled with an older version of SDCC / GBDK then you may have to recompile them.
    • If there are existing functions written in ASM which receive parameters they should also be reviewed to make sure they work with the new __sdcccall(1) calling convention, or have their header declaration changed to use OLDCALL.
    • If there are existing functions written in ASM which call other functions written in C the callee C function should be declared OLDCALL.
    • Function pointer declarations should be checked to see if they need OLDCALL added to the declaration.
      • Example (add OLDCALL at the end)
      • FROM: typedef void (*someFunc)(uint8_t, uint8_t);
      • TO: typedef void (*someFunc)(uint8_t, uint8_t) OLDCALL;
    • If you are using tools such as rgb2sdas (from hUGETracker/Driver) you may need to edit the resulting .o file and replace -mgbz80 with -msm83 in addition to using OLDCALL
  • The SDCC PORT name for the Game Boy and related clones changed from gbz80 to sm83.
  • The library base path changed from lib/small/asxxxx/ to lib/.
    • For example lib/small/asxxxx/gb becomes lib/gb
  • Allocations for ISR chain lengths were fixed.
    • Now they are VBL: 4 user handlers, LCD: 3 user handlers, SIO/TIM/JOY: 4 user handlers

Porting to GBDK-2020 4.0.6

  • Renamed bgb_emu.h to emu_debug.h and BGB_* functions to EMU_*
    • Aliases for the BGB_* ones and a bgb_emu.h shim are present for backward compatibility, but updating to the new naming is recommended

Porting to GBDK-2020 4.0.5

  • GBDK now requires SDCC 12259 or higher with GBDK-2020 patches
  • Variables in static storage are now initialized to zero per C standard (but remaining WRAM is not cleared)
  • png2asset is the new name for the png2mtspr utility
  • lcc : Changed default output format when not specified from .ihx to .gb (or other active rom extension)
  • The _BSS area is deprecated (use _DATA instead)
  • The _BASE area is renamed to _HOME
  • Variables in static storage are now initialized to zero per C standard (but remaining WRAM is not cleared)
  • itoa(), uitoa(), ltoa(), ultoa() all now require a radix value (base) argument to be passed. On the Game Boy and Analogue Pocket the parameter is required but not utilized.
  • set_bkg_1bit_data has been renamed to set_bkg_1bpp_data
  • The following header files which are now cross platform were moved from gb/ to gbdk/: bcd.h, console.h, far_ptr.h, font.h, gbdecompress.h, gbdk-lib.h, incbin.h, metasprites.h, platform.h, version.h
    • When including them use #include <gbdk/...> instead of #include <gb/>

Porting to GBDK-2020 4.0.4

  • GBDK now requires SDCC 12238 or higher
  • Made sample.h, cgb.h and sgb.h independent from gb.h

Porting to GBDK-2020 4.0.3

  • No significant changes required

Porting to GBDK-2020 4.0.2

  • The default font has been reduced from 256 to 96 characters.
    • Code using special characters may need to be updated.
    • The off-by-1 character index offset was removed for fonts. Old fonts with the offset need to be re-adjusted.

Porting to GBDK-2020 4.0.1

  • Important! : The WRAM memory region is no longer automatically initialized to zeros during startup.
    • Any variables which are declared without being initialized may have indeterminate values instead of 0 on startup. This might reveal previously hidden bugs in your code.
    • Check your code for variables that are not initialized before use.
    • In BGB you can turn on triggering exceptions (options panel) reading from unitialized RAM. This allows for some additional runtime detection of uninitialized vars.
  • In .ihx files, multiple writes to the same ROM address are now warned about using ihxcheck.
  • set_*_tiles() now wrap maps around horizontal and vertical boundaries correctly. Code relying on it not wrapping correctly may be affected.

Porting to GBDK-2020 4.0

  • GBDK now requires SDCC 4.0.3 or higher
  • The old linker link-gbz80 has been REMOVED, the linker sdldgb from SDCC is used.
    • Due to the linker change, there are no longer warnings about multiple writes to the same ROM address.
  • GBDK now generates .ihx files, those are converted to a ROM using makebin (lcc can do this automatically in some use cases)
  • Setting ROM bytes directly with -Wl-yp0x<address>=0x<value> is no longer supported. Instead use makebin flags. For example, use -Wm-yC instead of -Wl-yp0x143=0xC0. See faq_gb_type_header_setting.
  • OAM symbol has been renamed to _shadow_OAM, that allows accessing shadow OAM directly from C code

Porting to GBDK-2020 3.2

  • No significant changes required

Porting to GBDK-2020 3.1.1

  • No significant changes required

Porting to GBDK-2020 3.1

Porting to GBDK-2020 3.0.1

  • LCC was upgraded to use SDCC v4.0. Makefile changes may be required
    • The symbol format changed. To get bgb compatible symbols turn on .noi output (LCC argument: -Wl-j or -debug) and use -Wm-yS
    • ?? Suggested: With LCC argument: -Wa-l (sdasgb:-a All user symbols made global)
    • In SDCC 3.6.0, the default for char changed from signed to unsigned.
      • If you want the old behavior use --fsigned-char.
      • lcc includes --fsigned-char by default
      • Explicit declaration of unsigned vars is encouraged (for example, '15U' instead of '15')
    • .init address has been removed

Historical GBDK versions

GBDK 1.1 to GBDK 2.0

  • Change your int variables to long if they have to be bigger than 255. If they should only contain values between 0 and 255, use an unsigned int.
  • If your application uses the delay function, you'll have to adapt your delay values.
  • Several functions have new names. In particular some of them have been changed to macros (e.g. show_bkg() is now SHOW_BKG).
  • You will probably have to change the name of the header files that you include.