git.y1.nz

commit d800011859af9b5dc47395bf4590aec2b3809a7d
parent 4acad8b1f61a71f23f5e75a351d3b2b3a24ac525
Author: bbbbbr <bbbbbr@users.noreply.github.com>
Date:   Thu, 28 Jul 2022 01:24:42 -0700

Merge pull request #392 from bbbbbr/docs_4_1_0

Docs: Updates for number of installable interrupt handlers
Diffstat:
M
docs/pages/03_using_gbdk.md
4
++--
M
gbdk-lib/include/gb/gb.h
30
++++++++++++++++++++++++------

2 files changed, 26 insertions(+), 8 deletions(-)
diff --git a/docs/pages/03_using_gbdk.md b/docs/pages/03_using_gbdk.md
@@ -4,7 +4,7 @@
 # Interrupts
 Interrupts allow execution to jump to a different part of your code as soon as an external event occurs - for example the LCD entering the vertical blank period, serial data arriving or the timer reaching its end count. For an example see the irq.c sample project.
 
-Interrupts in GBDK are handled using the functions @ref disable_interrupts(), @ref enable_interrupts(), @ref set_interrupts(uint8_t ier) and the interrupt service routine (ISR) linkers @ref add_VBL(), @ref add_TIM, @ref add_LCD, @ref add_SIO and @ref add_JOY which add interrupt handlers for the vertical blank, timer, LCD, serial link and joypad interrupts respectively.
+Interrupts in GBDK are handled using the functions @ref disable_interrupts(), @ref enable_interrupts(), @ref set_interrupts(uint8_t ier) and the interrupt service routine (ISR) linkers @ref add_VBL(), @ref add_TIM, @ref add_low_priority_TIM, @ref add_LCD, @ref add_SIO and @ref add_JOY which add interrupt handlers for the vertical blank, timer, LCD, serial link and joypad interrupts respectively.
 
 Since an interrupt can occur at any time an Interrupt Service Request (ISR) cannot take any arguments or return anything. Its only way of communicating with the greater program is through the global variables. When interacting with those shared ISR global variables from main code outside the interrupt, it is a good idea to wrap them in a `critical {}` section in case the interrupt occurs and modifies the variable while it is being used.
 
@@ -26,7 +26,7 @@ The GameBoy hardware can generate 5 types of interrupts. Custom Interrupt Servic
     - Example project: `lcd_isr_wobble`
 
   - TIM : Timer overflow
-    - See @ref add_TIM() and @ref remove_TIM()
+    - See @ref add_TIM() (or @ref add_low_priority_TIM() ) and @ref remove_TIM()
     - Example project: `tim`
 
   - SIO : Serial Link I/O transfer end
diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h
@@ -203,9 +203,8 @@ void remove_JOY(int_handler h) OLDCALL;
     @param h  The handler to be called whenever a V-blank
     interrupt occurs.
 
-    Up to 4 handlers may be added, with the last added being
-    called last.  If the @ref remove_VBL function is to be called,
-    only three may be added.
+    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
@@ -221,6 +220,9 @@ void add_VBL(int_handler h) OLDCALL;
     Called when the LCD interrupt occurs, which is normally
     when @ref LY_REG == @ref LYC_REG.
 
+    Up to 3 handlers may be added, with the last added
+    being called last.
+
     There are various reasons for this interrupt to occur
     as described by the @ref STAT_REG register ($FF41). One very
     popular reason is to indicate to the user when the
@@ -229,7 +231,11 @@ void add_VBL(int_handler h) OLDCALL;
     @ref SCX_REG / @ref SCY_REG registers ($FF43/$FF42) to perform
     special video effects.
 
-    @see add_VBL
+    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
 */
 void add_LCD(int_handler h) OLDCALL;
 
@@ -240,13 +246,16 @@ void add_LCD(int_handler h) OLDCALL;
     This interrupt occurs when the @ref TIMA_REG
     register ($FF05) changes from $FF to $00.
 
+    Up to 4 handlers may be added, with the last added
+    being called last.
+
     @see add_VBL
     @see set_interrupts() with TIM_IFLAG
 */
 void add_TIM(int_handler h) OLDCALL;
 
-/** Adds a timer interrupt handler, that could be 
-    interrupted by the other interrupts, 
+/** Adds a timer interrupt handler, that could be
+    interrupted by the other interrupts,
     as well as itself, if it runs too slow.
 
     Can not be used together with @ref add_TIM
@@ -254,6 +263,9 @@ void add_TIM(int_handler h) OLDCALL;
     This interrupt occurs when the @ref TIMA_REG
     register ($FF05) changes from $FF to $00.
 
+    Up to 4 handlers may be added, with the last added
+    being called last.
+
     @see add_VBL
     @see set_interrupts() with TIM_IFLAG
 */
@@ -264,6 +276,9 @@ void add_low_priority_TIM(int_handler h) OLDCALL;
     This interrupt occurs when a serial transfer has
     completed on the game link port.
 
+    Up to 4 handlers may be added, with the last added
+    being called last.
+
     @see send_byte, receive_byte(), add_VBL()
     @see set_interrupts() with SIO_IFLAG
 */
@@ -279,6 +294,9 @@ void add_SIO(int_handler h) OLDCALL;
     or more times for every button press and one or more
     times for every button release.
 
+    Up to 4 handlers may be added, with the last added
+    being called last.
+
     @see joypad(), add_VBL()
 */
 void add_JOY(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.