gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit b63baa52ae9219eb1b055b20cc2557bf7b463640 parent b96ad9e01e9731047e702174c0dfcd141df19e69 Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Tue, 2 May 2023 00:50:24 -0700 Merge pull request #491 from bbbbbr/docs_4_2_0 Docs: more updates for 4.2.0 Diffstat:
| M | docs/pages/03_using_gbdk.md | 61 | +++++++++++++++++++++++++++++++++---------------------------- |
| M | docs/pages/04_coding_guidelines.md | 1 | + |
| M | docs/pages/06b_supported_consoles.md | 4 | ++-- |
| M | docs/pages/08_faq.md | 6 | +++++- |
| M | docs/pages/09_migrating_new_versions.md | 3 | ++- |
| M | gbdk-lib/examples/gb/sgb_border/Readme.md | 10 | ++++++++++ |
| M | gbdk-lib/examples/gb/sgb_pong/sgb_pong.c | 7 | +++++-- |
| M | gbdk-lib/include/gb/hardware.h | 2 | +- |
| M | gbdk-lib/include/gb/metasprites.h | 4 | ++-- |
| M | gbdk-lib/include/gb/sgb.h | 7 | ++++++- |
| M | gbdk-lib/include/rand.h | 6 | +++--- |
11 files changed, 70 insertions(+), 41 deletions(-)
diff --git a/docs/pages/03_using_gbdk.md b/docs/pages/03_using_gbdk.md @@ -101,9 +101,14 @@ The second approach is slightly more efficient. Both approaches are demonstrated # Mixing C and Assembly -You can mix C and assembly (ASM) in two ways as described below. For additional detail see the @ref links_sdcc_docs. +_The following is primarily oriented toward the Game Boy and related clones (sm83 devices), other targets such as sms/gg may vary._ + +You can mix C and assembly (ASM) in two ways as described below. +- For additional detail see the @ref links_sdcc_docs and @ref sdcc_calling_convention "SDCC Calling Conventions". ## Inline ASM within C source files +- The optional `NAKED` keyword may be used to indicate that the funtion setup and return should have no handling done by the compiler, and will instead be handled entirely by user code. +- If the entire function preserves some registers the optional `PRESERVES_REGS` keyword may be used as additional hinting for the compiler. For example `PRESERVES_REGS(b, c)`. By default it is assumed by the compiler that no registers are preserved. Example: @@ -122,25 +127,22 @@ Another Example: ## In Separate ASM files -@todo This is from GBDK 2.x docs, verify it with GBDK-2020 and modern SDCC - It is possible to assemble and link files written in ASM alongside files written in C. - A C identifier `i` will be called `_i` in assembly. - - Results are always returned into the `DE` register. - - Parameters are passed on the stack (starting at `SP+2` because the return address is also saved on the stack). + - Parameters will be passed, registers saved and results returned in a manner based on the @ref sdcc_calling_convention "SDCC Calling Convention" used and how the function is declared. - Assembly identifiers are exported using the `.globl` directive. - - You can access GameBoy hardware registers using `_reg_0xXX` where `XX` is the register number (see `sound.c` for an example). - - Registers must be preserved across function calls (you must store them at function begin, and restore them at the end), except `HL` (and `DE` when the function returns a result). + - See global.s for examples of hardware register deginitions. Here is an example of how to mix assembly with C: `main.c` + uint16_t add(uint16_t, uint16_t); + main() { - int16_t i; - int16_t add(int16_t, int16_t); + uint16_t i; i = add(1, 3); } @@ -148,25 +150,28 @@ Here is an example of how to mix assembly with C: `add.s` .globl _add - _add: ; int16_t add(int16_t a, int16_t b) - ; There is no register to save: - ; BC is not used - ; DE is the return register - ; HL needs never to be saved - LDA HL,2(SP) - LD E,(HL) ; Get a in DE - INC HL - LD D,(HL) - INC HL - LD A,(HL) ; Get b in HL - INC HL - LD H,(HL) - LD L,A - ADD HL,DE ; Add DE to HL - LD D,H - LD E,L - ; There is no register to restore - RET ; Return result in DE + + .area _CODE + _add: ; uint16_t add(uint16_t First, uint16_t Second) + ; + ; In this particular example there is no use and modification of the stack + ; No need to save and restore registers + ; + ; For calling convention __sdcccall(1) + ; - first 16 bit param is passed in DE + ; - second 16 bit param is passed in BC + + ; Load Second Parameter ("Second") into HL + ld l, c + ld h, b + + ; Add Parameters "Second" + "First" + add hl, de + + ; Return result in BC + ld c, l + ld b, h + ret ; 16 bit values are returned in BC # Including binary files in C source with incbin diff --git a/docs/pages/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -271,6 +271,7 @@ The use of segments/areas for code, data and variables is more noticeable in ass @anchor sdcc_calling_convention ## Calling convention +_The following is primarily oriented toward the Game Boy and related clones (sm83 devices), other targets such as sms/gg may vary._ SDCC in common with almost all C compilers prepends a `_` to any function names. For example the function `printf(...)` begins at the label `_printf::.` Note that all functions are declared global. diff --git a/docs/pages/06b_supported_consoles.md b/docs/pages/06b_supported_consoles.md @@ -207,10 +207,10 @@ These are some of the main hardware differences between the Regular Game Boy and - Serial Link: Additional Speeds 2KB/s, 32KB/s, 64KB/s - IR Port - Sprites: - - 2 x 256 banks of tile patterns (2x as many) (typically upper 256 shared with background) + - 2 banks x 256 tile patterns (2x as many) (typically upper 128 of each bank shared with background) - 8 x 4 color palettes in CGB mode (BGR-555 per color, 32768 color choices) - Background: - - 2 x 256 banks of tile patterns (2x as many) (typically upper 256 shared with sprites) + - 2 banks x 256 tile patterns (2x as many) (typically upper 128 of each bank shared with sprites) - Second map bank for tile attributes (color, flipping/mirroring, priority, bank) - 8 x 4 color palettes in CGB mode (BGR-555 per color, 32768 color choices)) - BG and Window master priority diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md @@ -53,7 +53,11 @@ - What do these kinds of warnings / errors mean? `WARNING: possibly wrote twice at addr 4000 (93->3E)` `Warning: Write from one bank spans into the next. 7ff7 -> 8016 (bank 1 -> 2)` - - You may have a overflow in one of your ROM banks. If there is more data allocated to a bank than it can hold it then will spill over into the next bank. The warnings are generated by @ref ihxcheck during conversion of an .ihx file into a ROM file. + - You may have a overflow in one of your ROM banks. If there is more data allocated to a bank than it can hold it then will spill over into the next bank. + + A common problem is when there is too much data in ROM0 (the lower 16K unbanked region) and it spills over into ROM1 (the first upper 16K banked region). Make sure ROM0 has 16K or less in it. + + The warnings are generated by @ref ihxcheck during conversion of an .ihx file into a ROM file. See the section @ref docs_rombanking_mbcs for more details about how banks work and what their size is. You may want to use a tool such as @ref romusage to calculate the amount of free and used space. <!-- --> diff --git a/docs/pages/09_migrating_new_versions.md b/docs/pages/09_migrating_new_versions.md @@ -6,7 +6,8 @@ This section contains information that may be useful to know or important when u ## Porting to GBDK-2020 4.2 - GBDK now requires SDCC 4.3 or higher with GBDK-2020 patches for the the z80 linker - - The following new functions replace old ones. The old functions will continue to work for now, but migration to new versions is strongly encouraged. + - The following new functions replace old ones. + - The old functions will continue to work for now, but migration to new versions is strongly encouraged. - vsync(): replaces wait_vbl_done() - set_default_palette(): replaces cgb_compatibility() - move_metasprite_flipy(): replaces move_metasprite_hflip() diff --git a/gbdk-lib/examples/gb/sgb_border/Readme.md b/gbdk-lib/examples/gb/sgb_border/Readme.md @@ -13,3 +13,13 @@ png2asset is used for converting the border. * https://gbdev.io/pandocs/SGB_Functions.html * https://gbdev.io/pandocs/SGB_Color_Palettes.html +When using the SGB with a PAL SNES, a delay should be added just after program startup such as: + +``` + // Wait 4 frames + // For PAL SNES this delay is required on startup + for (uint8_t i = 4; i != 0; i--) wait_vbl_done(); +``` + + + diff --git a/gbdk-lib/examples/gb/sgb_pong/sgb_pong.c b/gbdk-lib/examples/gb/sgb_pong/sgb_pong.c @@ -66,6 +66,10 @@ void main(void) { // show bkg and sprites SHOW_BKG; SHOW_SPRITES; + // Wait 4 frames + // For SGB on PAL SNES this delay is required on startup, otherwise borders don't show up + for (uint8_t i = 4; i != 0; i--) vsync(); + // init 2 joypads if (joypad_init(2, &joypads) != 2) { printf(" This program must\n be executed on\n Super GameBoy"); @@ -141,4 +145,4 @@ void main(void) { // wait for VBlank to slow down everything vsync(); } -} - +} diff --git a/gbdk-lib/include/gb/hardware.h b/gbdk-lib/include/gb/hardware.h @@ -369,7 +369,7 @@ __REG OCPS_REG; /**< OBJ color palette specification */ #define OCPSF_AUTOINC 0b10000000 __REG OCPD_REG; /**< OBJ color palette data */ #define rOCPD OCPD_REG -__REG SVBK_REG; /**< WRAM bank */ +__REG SVBK_REG; /**< Selects the WRAM upper region bank (CGB Only). WRAM Banking is NOT officially supported in GBDK and SDCC. The stack must be moved and other special care taken. */ #define rSVBK SVBK_REG #define rSMBK SVBK_REG diff --git a/gbdk-lib/include/gb/metasprites.h b/gbdk-lib/include/gb/metasprites.h @@ -118,9 +118,9 @@ static void __hide_metasprite(uint8_t id); /** Hides all hardware sprites in range from <= X < to @param from start OAM index - @param to finish OAM index + @param to finish OAM index (must be <= MAX_HARDWARE_SPRITES) - @see hide_sprite + @see hide_sprite, MAX_HARDWARE_SPRITES */ void hide_sprites_range(UINT8 from, UINT8 to); diff --git a/gbdk-lib/include/gb/sgb.h b/gbdk-lib/include/gb/sgb.h @@ -36,7 +36,12 @@ #define SGB_OBJ_TRN 0x18U /**< SGB Command: Transfer OBJ attributes to SNES OAM memory */ -/** Returns a non-null value if running on Super GameBoy */ +/** Returns a non-zero value if running on a Super GameBoy + + Since sgb_check() uses @ref sgb_transfer(), the same + delay at startup requirement applies to ensure correct + operation on PAL SNES. See @ref sgb_transfer() for details. + * */ uint8_t sgb_check(void) OLDCALL PRESERVES_REGS(b, c); /** Transfer a SGB packet diff --git a/gbdk-lib/include/rand.h b/gbdk-lib/include/rand.h @@ -51,13 +51,13 @@ extern uint16_t __rand_seed; @ref initrand() should be used to initialize the random number generator before using rand() */ -uint8_t rand() OLDCALL; +uint8_t rand(void) OLDCALL; /** Returns a random word (16 bit) value. @ref initrand() should be used to initialize the random number generator before using rand() */ -uint16_t randw() OLDCALL; +uint16_t randw(void) OLDCALL; /** Random generator using the linear lagged additive method @@ -78,6 +78,6 @@ void initarand(uint16_t seed) Z88DK_FASTCALL; @ref initarand() should be used to initialize the random number generator before using arand() */ -uint8_t arand() OLDCALL; +uint8_t arand(void) OLDCALL; #endif
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.