git.y1.nz

commit 0d3278bf5cad68b5933f5ec8d2a967d715d2abd4
parent d1af95e3cd63baf3b30a5c847b01be76b4bbae0a
Author: bbbbbr <reg+github@roughhousing.com>
Date:   Wed,  8 Sep 2021 17:13:38 -0700

Merge pull request #249 from bbbbbr/docs_4_0_5

Docs: ISR_VECTOR() and related
Diffstat:
M
docs/pages/03_using_gbdk.md
2
++
M
gbdk-lib/include/gb/isr.h
55
+++++++++++++++++++++++++++++++++++++++++--------------

2 files changed, 43 insertions(+), 14 deletions(-)
diff --git a/docs/pages/03_using_gbdk.md b/docs/pages/03_using_gbdk.md
@@ -54,6 +54,8 @@ If you want to use your own Interrupt Dispatcher instead of the GBDK chained dis
   - Exception: the VBL dispatcher will always be linked in at compile time.
   - For the SIO interrupt, also do not make any standard SIO calls to avoid having it's dispatcher installed.
 
+Then @ref ISR_VECTOR() or @ref ISR_NESTED_VECTOR() can be used to easily install a custom ISR handler.
+
 ## Returning from Interrupts and STAT mode
 By default when an Interrupt handler completes and is ready to exit it will check STAT_REG and only return at the BEGINNING of either LCD Mode 0 or Mode 1. This helps prevent graphical glitches caused when an ISR interrupts a graphics operation in one mode but returns in a different mode for which that graphics operation is not allowed.
 
diff --git a/gbdk-lib/include/gb/isr.h b/gbdk-lib/include/gb/isr.h
@@ -1,7 +1,10 @@
 /** @file gb/isr.h
-    
-    Allows constructing of raw ISR vectors. 
 
+    Macros for creating raw interrupt service routines (ISRs)
+    which do not use the default GBDK ISR dispatcher.
+
+    Handlers installed this way will have less overhead than
+    ones which use the GBDK ISR dispatcher.
 */
 #ifndef _ISR_H_INCLUDE_
 #define _ISR_H_INCLUDE_
@@ -9,21 +12,41 @@
 #include <stdint.h>
 
 // #define VECTOR_VBL     0x40 // you can not define raw vector for VBlank interrupt
-#define VECTOR_STAT    0x48
-#define VECTOR_TIMER   0x50
-#define VECTOR_SERIAL  0x58
-#define VECTOR_JOYPAD  0x60
+#define VECTOR_STAT    0x48  /** Address for the STAT interrupt vector */
+#define VECTOR_TIMER   0x50  /** Address for the TIMER interrupt vector */
+#define VECTOR_SERIAL  0x58  /** Address for the SERIAL interrupt vector */
+#define VECTOR_JOYPAD  0x60  /** Address for the JOYPAD interrupt vector */
 
 typedef struct isr_vector_t {
     uint8_t opcode;
     void * func;
 } isr_vector_t;
 
-/** Creates the interrupt vector at the given address for the raw interrupt service routrine
-    
-    @param ADDR address of the vector
+/** Creates an interrupt vector at the given address for a raw
+    interrupt service routine (which does not use the GBDK ISR dispatcher)
+
+    @param ADDR   Address of the interrupt vector, any of: @ref VECTOR_STAT, @ref VECTOR_TIMER, @ref VECTOR_SERIAL, @ref VECTOR_JOYPAD
+    @param FUNC   ISR function supplied by the user
+
+    This cannot be used with the VBLANK interrupt.
+
+    Do not use this in combination with interrupt installers
+    that rely on the default GBDK ISR dispatcher such as
+    @ref add_TIM(), @ref remove_TIM()
+    (and the same for all other interrupts).
+
+    Example:
+    \code{.c}
+    #include <gb/isr.h>
 
-    @param FUNC ISR function
+    void TimerISR() __critical __interrupt {
+    // some ISR code here
+    }
+
+    ISR_VECTOR(VECTOR_TIMER, TimerISR)
+    \endcode
+
+    @see ISR_NESTED_VECTOR, set_interrupts
 */
 #define ISR_VECTOR(ADDR, FUNC) \
 static const isr_vector_t __at((ADDR)) __ISR_ ## ADDR = {0xc3, (void *)&(FUNC)};
@@ -33,11 +56,15 @@ typedef struct isr_nested_vector_t {
     void * func;
 } isr_nested_vector_t;
 
-/** Creates the interrupt vector at the given address for the raw interrupt service routrine allowing nested inteerupts
-    
-    @param ADDR address of the vector
+/** Creates an interrupt vector at the given address for a raw
+    interrupt service routine allowing nested interrupts
+
+    @param ADDR   Address of the interrupt vector, any of: @ref VECTOR_STAT, @ref VECTOR_TIMER, @ref VECTOR_SERIAL, @ref VECTOR_JOYPAD
+    @param FUNC   ISR function
+
+    This cannot be used with the VBLANK interrupt
 
-    @param FUNC ISR function
+    @see ISR_VECTOR
 */
 #define ISR_NESTED_VECTOR(ADDR, FUNC) \
 static const isr_nested_vector_t __at((ADDR)) __ISR_ ## ADDR = {{0xfb, 0xc3}, (void *)&(FUNC)};

This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.