Docs: Add warning about reading from VRAM

- Improve doxygen @note styling
- Convert several entries of "Note:" to @note
- Fix incorrect link anchor for mac os security warning in faq
- Add some missing SDCC versions to older release notes

docs/config/github-markdown-theme/doxygen_extra.css

@@ -574,3 +574,10 @@ th,
 table.markdownTable tr:hover {
     background-color: rgb(231, 236, 242);
 }
+
+/* @note styling */
+dl.note {
+    padding-left: 8px !important;
+    border-color: rgba(0, 210, 0, 0.40) !important;
+    background-color: rgba(0, 255, 0, 0.12) !important;
+}

docs/pages/04_coding_guidelines.md

@@ -38,6 +38,17 @@ __Use of @ref toxa_gbtd_gbmb "toxa's updated GBTD/GBMB" is highly recommended.__
 
 If you wish to use the original tools, you must add the `const` keyword every time the graphics are re-exported to C source files.
 
+@anchor best_practice_dont_read_vram
+## Avoid Reading from VRAM
+In general avoid reading from VRAM since that memory is not accessible at all times. If GBDK a API function which reads from VRAM (such as @ref get_bkg_tile_xy()) is called during a video mode when VRAM is not accessible, then that function call will delay until VRAM becomes accessible again. This can cause unnecessary slowdowns when running programs on the Game Boy.
+
+Instead it is better to store things such as map data in general purpose RAM which does not have video mode access limitations.
+
+For more information about video modes and VRAM access see the pan docs:
+
+https://gbdev.io/pandocs/STAT.html#stat-modes
+
+
 
 ## Variables
   - Use 8-bit values as much as possible. They will be much more efficient and compact than 16 and 32 bit types.

docs/pages/06b_supported_consoles.md

@@ -114,6 +114,8 @@ Constants that describe properties of the console hardware are listed below. The
   - @ref DEVICE_SCREEN_MAP_ENTRY_SIZE
   - @ref DEVICE_SPRITE_PX_OFFSET_X, @ref DEVICE_SPRITE_PX_OFFSET_Y
   - @ref DEVICE_SCREEN_PX_WIDTH, @ref DEVICE_SCREEN_PX_HEIGHT
+  - @ref MAX_HARDWARE_SPRITES
+  - @ref HARDWARE_SPRITE_CAN_FLIP_X, @ref HARDWARE_SPRITE_CAN_FLIP_Y
 
 
 # Using <gbdk/...> headers

docs/pages/08_faq.md

@@ -76,7 +76,7 @@
     - This may happen if you have large initialized arrays declared without the `const` keyword. It's important to use the const keyword for read-only data. See @ref const_gbtd_gbmb and @ref const_array_data
     - It can also happen if C source files are `#included` into other C source files, or if there is a very large source file.  <!-- -->  
 
-@anchor faq_error_mbc_size
+@anchor faq_macos_security_warning
   - On macOS, what does `... developer cannot be verified, macOS cannot verify that this app is free from malware` mean?
     - It does not mean that GBDK is malware. It just means the GBDK toolchain binaries are not signed by Apple, so it won't run them without an additional step.
 

docs/pages/09_migrating_new_versions.md

@@ -4,10 +4,10 @@ This section contains information that may be useful to know or important when u
 
 # GBDK-2020 versions
 
-## Porting to GBDK-2020 4.2
+## Porting to GBDK-2020 4.2.0
   - GBDK now requires SDCC 4.3 or higher with GBDK-2020 patches for the the z80 linker
-  - The following new functions replace old ones.
-    - The old functions will continue to work for now, but migration to new versions is strongly encouraged.
+  - The following new functions replace old ones:
+    - While the old functions will continue to work for now, migration to new versions is strongly encouraged
     - vsync(): replaces wait_vbl_done()
     - set_default_palette(): replaces cgb_compatibility()
     - move_metasprite_flipy(): replaces move_metasprite_hflip()

docs/pages/10_release_notes.md

@@ -8,8 +8,7 @@ https://github.com/gbdk-2020/gbdk-2020/releases
 
 ## GBDK-2020 4.2
   2023/x
-  - SDCC Compiler
-    - Updated to SDCC 14..TODO..
+  - Includes SDCC version 14...TODO... with GBDK-2020 patches for Z80 and NES
     - ([Patched SDCC Builds](https://github.com/gbdk-2020/gbdk-2020-sdcc/releases) with support for Sega GG/SMS and the Nintendo NES are used. See the [github workflow](https://github.com/gbdk-2020/gbdk-2020-sdcc/tree/main/.github/workflows) for details
   - Library
     - Added: set_bkg_attributes(), set_bkg_submap_attributes()
@@ -62,11 +61,13 @@ https://github.com/gbdk-2020/gbdk-2020/releases
 
 ## GBDK-2020 4.1.1
   2022/11
+  - Includes SDCC version 13350 with GBDK-2020 patches for Z80
   - Library
     - Fixed @ref RGB() and @ref RGB8() macros
 
 ## GBDK-2020 4.1.0
   2022/10
+  - Includes SDCC version 13350 with GBDK-2020 patches for Z80
   - Known Issues
     - The `compile.bat` batch files for Windows use the an incalid `-p` option for `mkdir`
   - Building GBDK
@@ -139,6 +140,7 @@ https://github.com/gbdk-2020/gbdk-2020/releases
 
 ## GBDK-2020 4.0.6
   2022/02
+  - Includes SDCC version 12539 with GBDK-2020 patches for Z80
   - Building GBDK
     - Changed to target older version of macOS (10.10) when building for better compatibility
   - Platforms

gbdk-lib/include/gb/gb.h

@@ -220,7 +220,7 @@ void remove_JOY(int_handler h);
     called via the GBDK ISR dispatcher which makes
     the extra function attributes unecessary.
 
-    Note: The default GBDK VBL is installed automatically.
+    @note The default GBDK VBL is installed automatically.
 
     @see ISR_VECTOR()
 */
@@ -531,7 +531,7 @@ __endasm; \
     \li For MBC1 some banks in it's range are unavailable
     (typically 0x20, 0x40, 0x60).
 
-    Note: Using @ref SWITCH_ROM_MBC5_8M() should not be mixed with using
+    @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
@@ -589,7 +589,7 @@ __endasm; \
 
     @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
+    @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
@@ -653,7 +653,7 @@ uint8_t joypad(void) PRESERVES_REGS(b, c, h, l);
     Normally only used for checking one key, but it will
     support many, even J_LEFT at the same time as J_RIGHT. :)
 
-    Note: Checks in a loop that doesn't HALT at all, so the CPU
+    @note Checks in a loop that doesn't HALT at all, so the CPU
     will be maxed out until this call returns.
     @see joypad
     @see J_START, J_SELECT, J_A, J_B, J_UP, J_DOWN, J_LEFT, J_RIGHT
@@ -662,7 +662,7 @@ uint8_t waitpad(uint8_t mask) PRESERVES_REGS(b, c, h, l);
 
 /** Waits for the directional pad and all buttons to be released.
 
-    Note: Checks in a loop that doesn't HALT at all, so the CPU
+    @note Checks in a loop that doesn't HALT at all, so the CPU
     will be maxed out until this call returns.
 */
 void waitpadup(void) PRESERVES_REGS(a, b, c, d, e, h, l);
@@ -735,8 +735,8 @@ inline void disable_interrupts(void) PRESERVES_REGS(a, b, c, d, e, h, l) {
     register IO to flags.
     @param flags	A logical OR of *_IFLAGS
 
-    @note: This disables and then re-enables interrupts so it
-           must be used outside of a critical section.
+    @note This disables and then re-enables interrupts so it
+          must be used outside of a critical section.
 
     @see enable_interrupts(), disable_interrupts()
     @see VBL_IFLAG, LCD_IFLAG, TIM_IFLAG, SIO_IFLAG, JOY_IFLAG
@@ -874,9 +874,13 @@ void set_vram_byte(uint8_t * addr, uint8_t v) OLDCALL PRESERVES_REGS(b, c);
 
 /**
  * Get byte from vram at given memory location
- *
  * @param addr address to read from
  * @return read value
+
+    @note In general **avoid reading from VRAM**
+          since that memory is not accessible at all times.
+          See @ref best_practice_dont_read_vram "coding guidelines"
+          for more details.
  */
 uint8_t get_vram_byte(uint8_t * addr) PRESERVES_REGS(b, c, h, l);
 
@@ -937,7 +941,7 @@ inline void set_1bpp_colors(uint8_t fgcolor, uint8_t bgcolor) {
     Writes __nb_tiles__ tiles to VRAM starting at __first_tile__, tile data
     is sourced from __data__. Each Tile is 16 bytes in size (8x8 pixels, 2 bits-per-pixel).
 
-    Note: Sprite Tiles 128-255 share the same memory region as Background Tiles 128-255.
+    @note Sprite Tiles 128-255 share the same memory region as Background Tiles 128-255.
 
     GBC only: @ref VBK_REG determines which bank of Background tile patterns are written to.
     \li VBK_REG = @ref VBK_BANK_0 indicates the first bank
@@ -974,6 +978,11 @@ void set_bkg_1bpp_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data
     @param nb_tiles    Number of Tiles to read
     @param data        Pointer to destination buffer for Tile Pattern data
 
+    @note In general **avoid reading from VRAM**
+          since that memory is not accessible at all times.
+          See @ref best_practice_dont_read_vram "coding guidelines"
+          for more details.
+
     Copies __nb_tiles__ tiles from VRAM starting at __first_tile__, Tile data
     is copied into __data__.
 
@@ -1006,7 +1015,7 @@ void get_bkg_data(uint8_t first_tile, uint8_t nb_tiles, uint8_t *data) OLDCALL P
     Writes that exceed coordinate 31 on the x or y axis will wrap around to
     the Left and Top edges.
 
-    Note: Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table.
+    @note Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table.
 
     GBC only: @ref VBK_REG determines whether Tile Numbers or Tile Attributes get set.
     \li VBK_REG = @ref VBK_TILES Tile Numbers are written
@@ -1260,6 +1269,10 @@ inline void set_bkg_submap_attributes(uint8_t x, uint8_t y, uint8_t w, uint8_t h
     @param h      Height of area to copy in tiles. Range 0 - 31
     @param tiles  Pointer to destination buffer for Tile Map data
 
+    @note In general **avoid reading from VRAM**
+          since that memory is not accessible at all times.
+          See @ref best_practice_dont_read_vram "coding guidelines"
+          for more details.
 
     Entries are copied into __tiles__ from the Background Tile Map starting at
     __x__, __y__ reading across for __w__ tiles and down for __h__ tiles.
@@ -1287,7 +1300,14 @@ uint8_t * set_bkg_tile_xy(uint8_t x, uint8_t y, uint8_t t) OLDCALL PRESERVES_REG
  * Get single tile t on background layer at x,y
  * @param x X-coordinate
  * @param y Y-coordinate
+
  * @return returns tile index
+
+    @note In general **avoid reading from VRAM**
+      since that memory is not accessible at all times.
+      See @ref best_practice_dont_read_vram "coding guidelines"
+      for more details.
+
  */
 uint8_t get_bkg_tile_xy(uint8_t x, uint8_t y) OLDCALL PRESERVES_REGS(b, c);
 
@@ -1373,6 +1393,11 @@ void set_win_1bpp_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data
     @param nb_tiles    Number of Tiles to read
     @param data        Pointer to destination buffer for Tile Pattern Data
 
+    @note In general **avoid reading from VRAM**
+          since that memory is not accessible at all times.
+          See @ref best_practice_dont_read_vram "coding guidelines"
+          for more details.
+
     This is the same as @ref get_bkg_data, since the Window Layer and
     Background Layer share the same Tile pattern data.
 
@@ -1402,7 +1427,7 @@ void get_win_data(uint8_t first_tile, uint8_t nb_tiles, uint8_t *data) OLDCALL P
     Writes that exceed coordinate 31 on the x or y axis will wrap around to
     the Left and Top edges.
 
-    Note: Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table.
+    @note Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table.
 
     GBC only: @ref VBK_REG determines whether Tile Numbers or Tile Attributes get set.
     \li VBK_REG = @ref VBK_TILES Tile Numbers are written
@@ -1523,6 +1548,11 @@ inline void set_win_based_submap(uint8_t x, uint8_t y, uint8_t w, uint8_t h, con
     @param h      Height of area to copy in tiles. Range 0 - 31
     @param tiles  Pointer to destination buffer for Tile Map data
 
+    @note In general **avoid reading from VRAM**
+          since that memory is not accessible at all times.
+          See @ref best_practice_dont_read_vram "coding guidelines"
+          for more details.
+
     Entries are copied into __tiles__ from the Window Tile Map starting at
     __x__, __y__ reading across for __w__ tiles and down for __h__ tiles.
 
@@ -1550,7 +1580,12 @@ uint8_t * set_win_tile_xy(uint8_t x, uint8_t y, uint8_t t) OLDCALL PRESERVES_REG
  * @param x X-coordinate
  * @param y Y-coordinate
  * @return returns the tile index
- */
+
+    @note In general **avoid reading from VRAM**
+          since that memory is not accessible at all times.
+          See @ref best_practice_dont_read_vram "coding guidelines"
+          for more details.
+*/
 uint8_t get_win_tile_xy(uint8_t x, uint8_t y) OLDCALL PRESERVES_REGS(b, c);
 
 
@@ -1594,7 +1629,7 @@ inline void scroll_win(int8_t x, int8_t y) {
     Writes __nb_tiles__ tiles to VRAM starting at __first_tile__, tile data
     is sourced from __data__. Each Tile is 16 bytes in size (8x8 pixels, 2 bits-per-pixel).
 
-    Note: Sprite Tiles 128-255 share the same memory region as Background Tiles 128-255.
+    @note Sprite Tiles 128-255 share the same memory region as Background Tiles 128-255.
 
     GBC only: @ref VBK_REG determines which bank of Background tile patterns are written to.
     \li VBK_REG = @ref VBK_BANK_0 indicates the first bank
@@ -1629,6 +1664,11 @@ void set_sprite_1bpp_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *d
     @param nb_tiles    Number of tiles to read
     @param data        Pointer to destination buffer for Tile Pattern data
 
+    @note In general **avoid reading from VRAM**
+          since that memory is not accessible at all times.
+          See @ref best_practice_dont_read_vram "coding guidelines"
+          for more details.
+
     Copies __nb_tiles__ tiles from VRAM starting at __first_tile__, tile data
     is copied into __data__.
 
@@ -1839,6 +1879,11 @@ void set_data(uint8_t *vram_addr, const uint8_t *data, uint16_t len);
     @param data      Pointer to destination buffer
     @param len       Number of bytes to copy
 
+    @note In general **avoid reading from VRAM**
+          since that memory is not accessible at all times.
+          See @ref best_practice_dont_read_vram "coding guidelines"
+          for more details.
+
     Copies __len__ bytes from VRAM starting at __vram_addr__ into a buffer at __data__.
 
     GBC only: @ref VBK_REG determines which bank of Background tile patterns are written to.
@@ -1912,6 +1957,11 @@ void set_tile_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data, ui
     @param vram_addr Pointer to source VRAM Address
     @param tiles     Pointer to destination buffer for Tile Map data
 
+    @note In general **avoid reading from VRAM**
+          since that memory is not accessible at all times.
+          See @ref best_practice_dont_read_vram "coding guidelines"
+          for more details.
+
     Entries are copied into __tiles__ from the Background Tile Map starting at
     __x__, __y__ reading across for __w__ tiles and down for __h__ tiles.
 
@@ -1952,14 +2002,14 @@ inline void set_native_tile_data(uint16_t first_tile, uint8_t nb_tiles, const ui
 /** Initializes the entire Window Tile Map with Tile Number __c__
     @param c   Tile number to fill with
 
-    Note: This function avoids writes during modes 2 & 3
+    @note This function avoids writes during modes 2 & 3
 */
 void init_win(uint8_t c) OLDCALL PRESERVES_REGS(b, c);
 
 /** Initializes the entire Background Tile Map with Tile Number __c__
     @param c   Tile number to fill with
 
-    Note: This function avoids writes during modes 2 & 3
+    @note This function avoids writes during modes 2 & 3
 */
 void init_bkg(uint8_t c) OLDCALL PRESERVES_REGS(b, c);
 
@@ -1968,7 +2018,7 @@ void init_bkg(uint8_t c) OLDCALL PRESERVES_REGS(b, c);
     @param c   Tile number to fill with
     @param n   Size of memory region (in bytes) to fill
 
-    Note: This function avoids writes during modes 2 & 3
+    @note This function avoids writes during modes 2 & 3
 */
 void vmemset (void *s, uint8_t c, size_t n) OLDCALL PRESERVES_REGS(b, c);