git.y1.nz

commit ca3f37f2ec41ebaba2dcd4812b80b2462c5a8560
parent 2fc06c126512cec481e0101a20f37b58d4ddc489
Author: bbbbbr <bbbbbr@users.noreply.github.com>
Date:   Tue, 25 Oct 2022 10:01:52 -0700

Merge pull request #429 from bbbbbr/docs_4_1_0

Docs: MBC5 updates
Diffstat:
M
docs/pages/05_banking_mbcs.md
2
+-
M
gbdk-lib/include/gb/gb.h
37
++++++++++++++++++++++++++++---------
M
gbdk-lib/include/nes/nes.h
10
++++++++--

3 files changed, 37 insertions(+), 12 deletions(-)
diff --git a/docs/pages/05_banking_mbcs.md b/docs/pages/05_banking_mbcs.md
@@ -136,7 +136,7 @@ Source: Pandocs. Additional details available at [Pandocs](https://gbdev.io/pand
 
 1: Max possible size for MBC is shown. When used with generic @ref SWITCH_ROM() the max size may be smaller. For example:
   - The max for MBC1 becomes __Bank 31__ (512K)
-  - The max for MBC5 becomes __Bank 255__(4MB). To use the full size of MBC5 see @ref SWITCH_ROM_MBC5_8M().
+  - The max for MBC5 becomes __Bank 255__ (4MB). To use the full 8MB size of MBC5 see @ref SWITCH_ROM_MBC5_8M().
 
 2: For MBC1 some banks in it's range are unavailable. See pandocs for more details https://gbdev.io/pandocs/MBC1
 
diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h
@@ -457,9 +457,15 @@ extern volatile uint8_t _io_out;
 
 
 
-/** Tracks current active ROM bank @see SWITCH_ROM_MBC1(), SWITCH_ROM_MBC5()
+/** Tracks current active ROM bank
+
+    The active bank number is not tracked by @ref _current_bank when
+    @ref SWITCH_ROM_MBC5_8M is used.
+
     This variable is updated automatically when you call SWITCH_ROM_MBC1 or
-    SWITCH_ROM_MBC5, or call a BANKED function.
+    SWITCH_ROM_MBC5, SWITCH_ROM(), or call a BANKED function.
+
+    @see SWITCH_ROM_MBC1(), SWITCH_ROM_MBC5(), SWITCH_ROM()
 */
 __REG _current_bank;
 #define CURRENT_BANK _current_bank
@@ -519,7 +525,7 @@ __endasm; \
     @param b   ROM bank to switch to
 
     For MBC1 some banks in it's range are unavailable
-    (typically 0x00, 0x20, 0x40, 0x60).
+    (typically 0x20, 0x40, 0x60).
 
     See pandocs for more details https://gbdev.io/pandocs/MBC1
 */
@@ -529,12 +535,15 @@ __endasm; \
 /** Makes default platform MBC switch the active ROM bank
     @param b   ROM bank to switch to (max 255)
 
-    \li When used with MBC1 the max bank is Bank 31
-    \li When used with MBC5 the max bank is Bank 255
-    \li To use the full size of MBC5 see @ref SWITCH_ROM_MBC5_8M()
+    \li When used with MBC1 the max bank is Bank 31 (512K).
+    \li When used with MBC5 the max bank is Bank 255 (4MB).
+    \li To use the full 8MB size of MBC5 see @ref SWITCH_ROM_MBC5_8M().
 
     \li For MBC1 some banks in it's range are unavailable
-    (typically 0x00, 0x20, 0x40, 0x60).
+    (typically 0x20, 0x40, 0x60).
+
+    Note: Using @ref SWITCH_ROM_MBC5_8M() should not be mixed with using
+          @ref SWITCH_ROM_MBC5() and @ref SWITCH_ROM().
 
     @see SWITCH_ROM_MBC1, SWITCH_ROM_MBC5, SWITCH_ROM_MEGADUCK
 */
@@ -582,7 +591,10 @@ __endasm; \
 
     Supports up to ROM bank 255 (4 MB).
 
-    @ref SWITCH_ROM_MBC5_8M may be used if a larger size is needed.
+    @ref SWITCH_ROM_MBC5_8M may be used if the full 8MB size is needed.
+
+    Note: Using @ref SWITCH_ROM_MBC5_8M() should not be mixed with using
+          @ref SWITCH_ROM_MBC5() and @ref SWITCH_ROM().
 
     Note the order used here. Writing the other way around on a MBC1 always selects bank 1
 */
@@ -591,10 +603,17 @@ __endasm; \
   *(volatile uint8_t *)0x3000 = 0, \
   *(volatile uint8_t *)0x2000 = (b)
 
-/** Makes MBC5 to switch the active ROM bank; active bank number is not tracked by _current_bank if you use this macro
+/** Makes MBC5 to switch the active ROM bank using the full 8MB size.
     @see _current_bank
     @param b   ROM bank to switch to
 
+    This is an alternate to @ref SWITCH_ROM_MBC5 which is limited to 4MB.
+
+    Note:
+    \li Banked SDCC calls are not supported if you use this macro.
+    \li The active bank number is not tracked by @ref _current_bank if you use this macro.
+    \li Using @ref SWITCH_ROM_MBC5_8M() should not be mixed with using @ref SWITCH_ROM_MBC5() and @ref SWITCH_ROM().
+
     Note the order used here. Writing the other way around on a MBC1 always selects bank 1
 */
 #define SWITCH_ROM_MBC5_8M(b) \
diff --git a/gbdk-lib/include/nes/nes.h b/gbdk-lib/include/nes/nes.h
@@ -166,9 +166,15 @@ uint8_t get_mode() OLDCALL;
 */
 extern volatile uint16_t sys_time;
 
-/** Tracks current active ROM bank @see SWITCH_ROM_MBC1(), SWITCH_ROM_MBC5()
+/** Tracks current active ROM bank
+
+    The active bank number is not tracked by @ref _current_bank when
+    @ref SWITCH_ROM_MBC5_8M is used.
+
     This variable is updated automatically when you call SWITCH_ROM_MBC1 or
-    SWITCH_ROM_MBC5, or call a BANKED function.
+    SWITCH_ROM_MBC5, SWITCH_ROM(), or call a BANKED function.
+
+    @see SWITCH_ROM_MBC1(), SWITCH_ROM_MBC5(), SWITCH_ROM()
 */
 extern volatile uint8_t _current_bank;
 #define CURRENT_BANK _current_bank

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