git.y1.nz

commit 1e1a7cc415d22937c07c5bb238494f74e526e636
parent 9fd48a77a93e2a409cb166c214fbdc1d32d2c26d
Author: bbbbbr <bbbbbr@users.noreply.github.com>
Date:   Thu, 30 Oct 2025 03:07:13 -0700

Docs: explanation of new dataseg pragma and sfr for HRAM vars (#827)


Diffstat:
M
docs/pages/05_banking_mbcs.md
1
+
M
docs/pages/06_toolchain.md
14
++++++++++++++
M
gbdk-lib/examples/gb/hram/hram_data.c
10
++++++++++

3 files changed, 25 insertions(+), 0 deletions(-)
diff --git a/docs/pages/05_banking_mbcs.md b/docs/pages/05_banking_mbcs.md
@@ -62,6 +62,7 @@ Note: You can use the `NONBANKED` keyword to define a function as non-banked if 
 
 
 ## Setting the RAM bank for a Source file
+  - `#pragma dataseg DATA_<N>` at the start of a source file. Example (Cartridge SRAM bank 3): `#pragma bank 3`
   - Using the lcc switch for Cartridge SRAM bank `-Wf-ba<N>`. Example (Cartridge SRAM bank 3): `-Wf-ba3`
 
 
diff --git a/docs/pages/06_toolchain.md b/docs/pages/06_toolchain.md
@@ -20,6 +20,20 @@ For data types and special C keywords, see @ref file_asm_sm83_types_h "asm/sm83/
 
 Also see the SDCC manual (scroll down a little on the linked page): http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.1
 
+## Using variables in High RAM on the Game Boy
+The High RAM (`_HRAM`) address space is at `0xFF80 - 0xFFFE`. It is eight bit addressable using the `ldh` opcodes which allow for more efficient read and write access.
+
+There are two main ways variables can be placed into High RAM
+- Using the `SFR` keyword
+  - For example: `SFR my_hram_variable;`
+  - Variables will be allocated in the `_HRAM` area
+  - They will be treated as 8-bit unsigned
+  - The compiler will automatically tag the variable as `volatile`
+  - The codegen will try to optimize them with `ldh` access
+- Using the `dataseg` pragma
+  - For example: `#pragma dataseg HRAM` followed by `unsigned char my_dataseg_var;`
+  - The codegen **will not** try to optimize them with `ldh` access
+
 
 @anchor toolchain_changing_important_addresses 
 # Changing Important Addresses
diff --git a/gbdk-lib/examples/gb/hram/hram_data.c b/gbdk-lib/examples/gb/hram/hram_data.c
@@ -1,3 +1,13 @@
 #include <gbdk/platform.h>
 
+
+// Declaring a variable as SFR means:
+//
+// It will be allocated in the High RAM (_HRAM area) address space
+// of the Game Boy sm83 CPU (0xFF80 - 0xFFFE). This address space
+// is eight bit addressable using the "ldh" opcodes, which allow
+// for more efficient read and write access.
+//
+// The variable will be treated as 8 bit unsigned.
+
 SFR my_hram_variable;
 

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