git.y1.nz

commit e5ecda0178c70682d19271db45e1a80b0ab8cff2
parent 2925ae2fd8f7c0c348a85260d207debf3fd2bf12
Author: bbbbbr <reg+github@roughhousing.com>
Date:   Fri, 10 Sep 2021 21:38:27 -0700

Merge pull request #257 from bbbbbr/docs_4_0_5

Docs: updates for 4.0.5
Diffstat:
M
docs/pages/03_using_gbdk.md
2
+-
M
docs/pages/05_banking_mbcs.md
4
++--
M
docs/pages/06_toolchain.md
4
----
M
docs/pages/docs_index.md
4
++--
M
gbdk-lib/include/asm/gbz80/types.h
25
+++++++++++++++++++++++--
M
gbdk-lib/include/gb/gb.h
22
++++++++++++++++------

6 files changed, 44 insertions(+), 17 deletions(-)
diff --git a/docs/pages/03_using_gbdk.md b/docs/pages/03_using_gbdk.md
@@ -54,7 +54,7 @@ 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.
+Then, @ref ISR_VECTOR() or @ref ISR_NESTED_VECTOR() can be used to 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/docs/pages/05_banking_mbcs.md b/docs/pages/05_banking_mbcs.md
@@ -90,10 +90,10 @@ The bank number for a banked function, variable or source file can be stored and
 
 @anchor banked_keywords
 ### BANKED/NONBANKED keywords
-- `BANKED`: 
+- @ref BANKED:
   - The function will use banked sdcc calls
   - Placed in the bank selected by it's source file (or compiler switches)
-- `NONBANKED`:
+- @ref NONBANKED:
   - Placed in the non-banked lower 16K region (bank 0), regardless of the bank selected by it's source file.
 - `<not-specified>`:
   - The function does not use sdcc banked calls (`near` instead of `far`)
diff --git a/docs/pages/06_toolchain.md b/docs/pages/06_toolchain.md
@@ -154,10 +154,6 @@ Unless an alternative output is specified the given object files are updated wit
 - Must be called after compiling/assembling and before linking
 - Arguments can be passed to it through @ref lcc using `-Wb-<argument>`
 
-Limitations
-- `__banked` functions cannot be called from within the same source file they are declared in.
-- With data it is easier, because if you access data from the code in the same bank you don’t need to switch the bank (access to `__bank_*` symbol).
-
 
 @anchor sdldgb
 ## sdldgb
diff --git a/docs/pages/docs_index.md b/docs/pages/docs_index.md
@@ -44,9 +44,9 @@ GBDK is freeware. Most of the tooling code is under the GPL. The runtime librari
 
 # Historical Info and Links
 
-Original work on GBDK (pre-2020) was by:
+Work on the original GBDK (pre-2020) was by:
 
-Pascal Felber, Lars Malmborg, Michael Hope (and others)
+Pascal Felber, Lars Malmborg, Michael Hope, David Galloway (djmips), and others.
 
 
 The following is from the original GBDK documentation:
diff --git a/gbdk-lib/include/asm/gbz80/types.h b/gbdk-lib/include/asm/gbz80/types.h
@@ -9,9 +9,30 @@
   #error gbz80 only.
 #endif
 
-#define NONBANKED		__nonbanked
-#define BANKED			__banked
+#define NONBANKED		__nonbanked  /**< Placed in the non-banked lower 16K region (bank 0), regardless of the bank selected by it's source file. */
+#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). */
+
+/**  Use to create a block of 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.
+
+    @see enable_interrupts, disable_interrupts
+*/
+
 #define CRITICAL		__critical
+
+/**  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.
+
+    @see ISR_VECTOR(), ISR_NESTED_VECTOR()
+*/
 #define INTERRUPT		__interrupt
 
 /** Signed eight bit.
diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h
@@ -205,7 +205,7 @@ void remove_JOY(int_handler h) NONBANKED;
     called last.  If the @ref remove_VBL function is to be called,
     only three may be added.
 
-    Do not use '__critical' and '__interrupt' attributes for a
+    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.
@@ -280,7 +280,7 @@ void add_JOY(int_handler h) NONBANKED;
 
     Example:
     \code{.c}
-    __critical {
+    CRITICAL {
         add_SIO(nowait_int_handler); // Disable wait on VRAM state before returning from SIO interrupt
     }
     \endcode
@@ -621,18 +621,28 @@ void joypad_ex(joypads_t * joypads) __preserves_regs(b, c);
 
 
 /** Enables unmasked interrupts
-    @see disable_interrupts, set_interrupts
+
+    @note Use @ref CRITICAL {...} instead for creating a block of
+          of code which should execute with interrupts  temporarily
+          turned off.
+
+    @see disable_interrupts, set_interrupts, CRITICAL
 */
 inline void enable_interrupts(void) __preserves_regs(a, b, c, d, e, h, l) {
     __asm__("ei");
 }
 
-/** Disables interrupts.
+/** Disables interrupts
+
+    @note Use @ref CRITICAL {...} instead for creating a block of
+          of code which should execute with interrupts  temporarily
+          turned off.
 
     This function may be called as many times as you like;
-    however the first call to enable_interrupts will re-enable
+    however the first call to @ref enable_interrupts will re-enable
     them.
-    @see enable_interrupts, set_interrupts
+
+    @see enable_interrupts, set_interrupts, CRITICAL
 */
 inline void disable_interrupts(void) __preserves_regs(a, b, c, d, e, h, l) {
     __asm__("di");

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