git.y1.nz

commit eb04d617a008130dd2a927c88f340fbdc0b753bc
parent dd85665d1caeadde130db5765b8f245a0085140f
Author: bbbbbr <reg+github@roughhousing.com>
Date:   Wed,  8 Sep 2021 20:31:29 -0700

Merge pull request #251 from bbbbbr/docs_4_0_5

Docs: 4.0.5 updates
Diffstat:
M
docs/pages/05_banking_mbcs.md
12
++++++------
M
docs/pages/06b_supported_consoles.md
14
+++++++++++++-
M
gbdk-lib/include/gb/gb.h
10
++++++++++

3 files changed, 29 insertions(+), 7 deletions(-)
diff --git a/docs/pages/05_banking_mbcs.md b/docs/pages/05_banking_mbcs.md
@@ -105,7 +105,7 @@ Banked functions can be called as follows.
   - When defined with the `BANKED` keyword. Example: `void my_function() BANKED { do stuff }` in a source file which has had it's bank set (see above).
   - Using @ref far_pointers
   - When defined with an area set up using the `__addressmod` keyword (See the `banks_new` example project and the SDCC manual for details)
-  - Using @ref SWITCH_ROM_MBC1() (and related functions for other MBCs) to manually switch in the required bank and then call the function.
+  - Using @ref SWITCH_ROM() (and related functions for other MBCs) to manually switch in the required bank and then call the function.
 
 Non-banked functions (either in fixed Bank 0, or in an non-banked ROM with no MBC)
   - May call functions in any bank: __YES__
@@ -138,7 +138,7 @@ See @ref FAR_CALL, @ref TO_FAR_PTR and the `banks_farptr` example project.
 
 
 ## Bank switching
-You can manually switch banks using the @ref SWITCH_ROM_MBC1(), @ref SWITCH_RAM_MBC1(), and other related macros. See `banks.c` project for an example.
+You can manually switch banks using the @ref SWITCH_ROM(), @ref SWITCH_RAM(), and other related macros. See `banks.c` project for an example.
 
 Note: You can only do a switch_rom_bank call from non-banked `_CODE` since otherwise you would switch out the code that was executing. Global routines that will be called without an expectation of bank switching should fit within the limited 16k of non-banked `_CODE`.
 
@@ -168,12 +168,12 @@ void vbl_music_isr(void)
     some_function();
 
     // Now restore the current bank
-    SWITCH_ROM_MBC5(_saved_bank);
+    SWITCH_ROM(_saved_bank);
 }
 ```
 
 ## Currently active bank: _current_bank
-The global variable @ref _current_bank is updated automatically when calling @ref SWITCH_ROM_MBC1() and @ref SWITCH_ROM_MBC5, or when a `BANKED` function is called.
+The global variable @ref _current_bank is updated automatically when calling @ref SWITCH_ROM(), @ref SWITCH_ROM_MBC1() and @ref SWITCH_ROM_MBC5, or when a `BANKED` function is called.
 
 
 
@@ -207,7 +207,7 @@ Accessing that data: main.c
 
       BANKREF_EXTERN(level_1_map)
       ...
-      SWITCH_ROM_MBC1( BANK(level_1_map) );
+      SWITCH_ROM( BANK(level_1_map) );
       // Do something with level_1_map[]
 
 Features and Notes:
@@ -241,7 +241,7 @@ In order to see how much space is used or remains available in a bank, you can u
 
 
 ## Other important notes
-  - The @ref SWITCH_ROM_MBC5 macro is not interrupt-safe. If using less than 256 banks you may always use SWITCH_ROM_MBC1 - that is faster. Even if you use mbc5 hardware chip in the cart.
+  - The @ref SWITCH_ROM_MBC5 macro is not interrupt-safe. If using less than 256 banks you may always use SWITCH_ROM - that is faster. Even if you use mbc5 hardware chip in the cart.
 
 
 # Banking example projects
diff --git a/docs/pages/06b_supported_consoles.md b/docs/pages/06b_supported_consoles.md
@@ -30,7 +30,6 @@ When compiling directly with @ref sdcc use: `-m<port>`, `-D__PORT_<port>` and `-
   - Analogue Pocket
     - @ref lcc : `-mgbz80:ap`
     - port:`gbz80`, plat:`ap`
-    - Note: The Analogue Pocket is functionally identical to the Game Boy / Color, but has a couple altered register flag / address definitions and a different boot logo.
 
   - Sega Master System
     - @ref lcc : `-mz80:sms`
@@ -84,3 +83,16 @@ and
 GBDK includes an number of cross platform example projects. These projects show how to write code that can be compiled and run on multiple different consoles (for example Game Boy and Game Gear) with, in some cases, minimal differences. 
 
 They also show how to build for multiple target consoles with a single build command and `Makefile`. The `Makefile.targets` allows selecting different `port` and `plat` settings when calling the build stages.
+
+# Porting from the Game Boy to the Analogue Pocket
+The Analogue Pocket is (for practical purposes) functionally identical to the Game Boy / Color, but has a couple altered register flag and address definitions and a different boot logo. In order for software to be ported to the Analogue Pocket, or to run on both, the following practices should be used.
+
+## Boot logo
+As long as the target console is @ref docs_consoles_compiling "set during build time" then the correct boot logo will be automatically selected.
+
+## Registers and Flags
+Change these hardwired registers and register flags to use API defined ones.
+   - LCDC register: @ref LCDC_REG or @ref rLCDC
+   - STAT register: @ref STAT_REG or @ref rSTAT
+   - LCDC flags: -> LCDCF_... (example: @ref LCDCF_ON)
+   - STAT flags: -> STATF_... (example: @ref STATF_LYC)
diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h
@@ -448,6 +448,11 @@ __endasm; \
 #define SWITCH_ROM_MBC1(b) \
   _current_bank = (b), *(uint8_t *)0x2000 = (b)
 
+/** Makes MBC1, MBC5 (4M ROMs) and other compatible MBCs switch the active ROM bank
+    @param b   ROM bank to switch to (max 255)
+
+    @see SWITCH_ROM_MBC1, SWITCH_ROM_MBC5
+*/
 #define SWITCH_ROM SWITCH_ROM_MBC1
 
 /** Switches SRAM bank on MBC1 and other compaticle MBCs
@@ -456,6 +461,11 @@ __endasm; \
 #define SWITCH_RAM_MBC1(b) \
   *(uint8_t *)0x4000 = (b)
 
+/** Switches SRAM bank on MBC1 and other compaticle MBCs
+    @param b   SRAM bank to switch to
+
+    @see SWITCH_RAM_MBC1, SWITCH_RAM_MBC5
+*/
 #define SWITCH_RAM SWITCH_RAM_MBC1
 
 /** Enables SRAM on MBC1

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