gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit afaf5de9c75e8b754b0c9971e285bde9b157e42a parent 48cd4b361338f8e5eacecb1f43f62af26feb4357 Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Mon, 17 Oct 2022 00:49:02 -0700 Merge pull request #424 from bbbbbr/docs_4_1_0 Docs: isr handler updates + some release notes Diffstat:
| M | docs/pages/10_release_notes.md | 2 | +- |
| M | gbdk-lib/include/asm/mos6502/types.h | 20 | +++++++++++--------- |
| M | gbdk-lib/include/asm/sm83/types.h | 20 | +++++++++++--------- |
| M | gbdk-lib/include/asm/z80/types.h | 20 | +++++++++++--------- |
| M | gbdk-lib/include/gb/gb.h | 37 | ++++++++++++++++++++++++++++--------- |
5 files changed, 62 insertions(+), 37 deletions(-)
diff --git a/docs/pages/10_release_notes.md b/docs/pages/10_release_notes.md @@ -37,7 +37,7 @@ https://github.com/gbdk-2020/gbdk-2020/releases - Added `-metasprites_only`: Export metasprite descriptors only - Added `-source_tileset`: Use source tileset image with common tiles - Added `-keep_duplicate_tiles`: Do not remove duplicate tiles - - Added `-bin`: Export to binary format + - Added `-bin`: Export to binary format (includes header files) - Added `-transposed`: Export transposed (column-by-column instead of row-by-row) - Added basic MSXDOS support - Added 1bpp packing mode (BPP1) diff --git a/gbdk-lib/include/asm/mos6502/types.h b/gbdk-lib/include/asm/mos6502/types.h @@ -15,12 +15,13 @@ #define BANKED /**< Currently a no-op for mos6502 target. */ #define REENTRANT __reentrant /**< Needed for mos6502 target when functions take too many parameters. */ -/** Use to create a block of of code which should execute with interrupts temporarily turned off. +/** Use to create a block of code which should execute with interrupts temporarily turned off. - __Do not__ use @ref CRITICAL and @ref INTERRUPT attributes for a - function added via add_VBL() (or LCD, etc). The attributes - are only required when constructing a bare jump from the - interrupt vector itself. + __Do not__ use the function definition attributes + @ref CRITICAL and @ref INTERRUPT when declaring + ISR functions added via add_VBL() (or LCD, etc). + These attributes are only required when constructing + a bare jump from the interrupt vector itself. @see enable_interrupts, disable_interrupts */ @@ -28,10 +29,11 @@ /** Indicate to the compiler the function will be used as an interrupt handler. - __Do not__ use @ref CRITICAL and @ref INTERRUPT attributes for a - function added via add_VBL() (or LCD, etc). The attributes - are only required when constructing a bare jump from the - interrupt vector itself. + __Do not__ use the function definition attributes + @ref CRITICAL and @ref INTERRUPT when declaring + ISR functions added via add_VBL() (or LCD, etc). + These attributes are only required when constructing + a bare jump from the interrupt vector itself. @see ISR_VECTOR(), ISR_NESTED_VECTOR() */ diff --git a/gbdk-lib/include/asm/sm83/types.h b/gbdk-lib/include/asm/sm83/types.h @@ -15,12 +15,13 @@ #define BANKED __banked /**< The function will use banked sdcc calls, and is placed in the bank selected by it's source file (or compiler switches). */ #define REENTRANT /**< Needed for mos6502 target when functions take too many parameters. */ -/** Use to create a block of of code which should execute with interrupts temporarily turned off. +/** Use to create a block of code which should execute with interrupts temporarily turned off. - __Do not__ use @ref CRITICAL and @ref INTERRUPT attributes for a - function added via add_VBL() (or LCD, etc). The attributes - are only required when constructing a bare jump from the - interrupt vector itself. + __Do not__ use the function definition attributes + @ref CRITICAL and @ref INTERRUPT when declaring + ISR functions added via add_VBL() (or LCD, etc). + These attributes are only required when constructing + a bare jump from the interrupt vector itself. @see enable_interrupts, disable_interrupts */ @@ -28,10 +29,11 @@ /** Indicate to the compiler the function will be used as an interrupt handler. - __Do not__ use @ref CRITICAL and @ref INTERRUPT attributes for a - function added via add_VBL() (or LCD, etc). The attributes - are only required when constructing a bare jump from the - interrupt vector itself. + __Do not__ use the function definition attributes + @ref CRITICAL and @ref INTERRUPT when declaring + ISR functions added via add_VBL() (or LCD, etc). + These attributes are only required when constructing + a bare jump from the interrupt vector itself. @see ISR_VECTOR(), ISR_NESTED_VECTOR() */ diff --git a/gbdk-lib/include/asm/z80/types.h b/gbdk-lib/include/asm/z80/types.h @@ -18,12 +18,13 @@ #define BANKED __banked /**< The function will use banked sdcc calls, and is placed in the bank selected by it's source file (or compiler switches). */ #define REENTRANT /**< Needed for mos6502 target when functions take too many parameters. */ -/** Use to create a block of of code which should execute with interrupts temporarily turned off. +/** Use to create a block of code which should execute with interrupts temporarily turned off. - __Do not__ use @ref CRITICAL and @ref INTERRUPT attributes for a - function added via add_VBL() (or LCD, etc). The attributes - are only required when constructing a bare jump from the - interrupt vector itself. + __Do not__ use the function definition attributes + @ref CRITICAL and @ref INTERRUPT when declaring + ISR functions added via add_VBL() (or LCD, etc). + These attributes are only required when constructing + a bare jump from the interrupt vector itself. @see enable_interrupts, disable_interrupts */ @@ -31,10 +32,11 @@ /** Indicate to the compiler the function will be used as an interrupt handler. - __Do not__ use @ref CRITICAL and @ref INTERRUPT attributes for a - function added via add_VBL() (or LCD, etc). The attributes - are only required when constructing a bare jump from the - interrupt vector itself. + __Do not__ use the function definition attributes + @ref CRITICAL and @ref INTERRUPT when declaring + ISR functions added via add_VBL() (or LCD, etc). + These attributes are only required when constructing + a bare jump from the interrupt vector itself. */ #define INTERRUPT __interrupt diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -198,7 +198,7 @@ void remove_SIO(int_handler h) OLDCALL; */ void remove_JOY(int_handler h) OLDCALL; -/** Adds a V-blank interrupt handler. +/** Adds a Vertical Blanking interrupt handler. @param h The handler to be called whenever a V-blank interrupt occurs. @@ -206,12 +206,20 @@ void remove_JOY(int_handler h) OLDCALL; Up to 4 handlers may be added, with the last added being called last. - Do not use @ref CRITICAL and @ref INTERRUPT attributes for a - function added via add_VBL() (or LCD, etc). The attributes - are only required when constructing a bare jump from the - interrupt vector itself. + __Do not__ use the function definition attributes + @ref CRITICAL and @ref INTERRUPT when declaring + ISR functions added via add_VBL() (or LCD, etc). + Those attributes are only required when constructing + a bare jump from the interrupt vector itself (such as + with @ref ISR_VECTOR()). - Note: The default VBL is installed automatically. + ISR handlers added using add_VBL()/etc are instead + called via the GBDK ISR dispatcher which makes + the extra function attributes unecessary. + + Note: The default GBDK VBL is installed automatically. + + @see ISR_VECTOR() */ void add_VBL(int_handler h) OLDCALL; @@ -230,12 +238,23 @@ void add_VBL(int_handler h) OLDCALL; This can be useful for dynamically controlling the @ref SCX_REG / @ref SCY_REG registers ($FF43/$FF42) to perform special video effects. + + __Do not__ use the function definition attributes + @ref CRITICAL and @ref INTERRUPT when declaring + ISR functions added via add_VBL() (or LCD, etc). + Those attributes are only required when constructing + a bare jump from the interrupt vector itself (such as + with @ref ISR_VECTOR()). + + ISR handlers added using add_VBL()/etc are instead + called via the GBDK ISR dispatcher which makes + the extra function attributes unecessary. If this ISR is to be called once per each scanline then make sure that the time it takes to execute is less than the duration of a scanline. - @see add_VBL, nowait_int_handler + @see add_VBL, nowait_int_handler, ISR_VECTOR() */ void add_LCD(int_handler h) OLDCALL; @@ -250,7 +269,7 @@ void add_LCD(int_handler h) OLDCALL; being called last. @see add_VBL - @see set_interrupts() with TIM_IFLAG + @see set_interrupts() with TIM_IFLAG, ISR_VECTOR() */ void add_TIM(int_handler h) OLDCALL; @@ -267,7 +286,7 @@ void add_TIM(int_handler h) OLDCALL; being called last. @see add_VBL - @see set_interrupts() with TIM_IFLAG + @see set_interrupts() with TIM_IFLAG, ISR_VECTOR() */ void add_low_priority_TIM(int_handler h) OLDCALL;
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.