Differences

This shows you the differences between two versions of the page.

--- wswan:guide:memory_management [2024/12/27 19:43] – asie
+++ wswan:guide:memory_management [2025/08/15 10:33] (current) – [Advanced section names] asie
@@ Line 6: / Line 6: @@
   * The combined segmentation and banking benefits from a ROM layouting scheme which takes it into account.
-===== Addressing RAM and ROM =====
+===== Addressing RAM and ROM in C =====
 In a C environment, by default, //near// pointers are utilized - they're smaller and faster to use, but they can only point to the program's default //data segment// - for all ''wswan'' targets, this is the console's internal RAM (IRAM).
@@ Line 13: / Line 13: @@
 <code C>
-// The variable below will be stored in IRAM, even if it's declared const.
+// The variable below will be stored in IRAM, even if it's declared as read-only (const).
 static const uint16_t table_iram[] = {0, 1, 2, 3};
-// The variable below will now be stored in ROM instead of IRAM.
+// The variable below will now be stored in ROM instead of IRAM, as it is read-only and far.
 static const uint16_t __far table[] = {0, 1, 2, 3};
+// As will this one, except it's not static, so you can reference it in a .h file...
+const uint16_t __far global_table[] = {0, 1, 2, 3};
+// ... like so.
+extern const uint16_t __far global_table[];
 void process_table_iram(uint16_t *tbl); // This function can accept pointers to IRAM only.
@@ Line 33: / Line 39: @@
   * ''%%__wf_iram%%'' - points to IRAM on every subtarget.
-===== Placing in specific memory locations =====
+===== Addressing RAM and ROM in assembly =====
+The linker places code and data in RAM and ROM using sections. These sections are used by default by the C compiler:
+  * ''.fartext'' - far code, last 768 KiB of ROM
+  * ''.farrodata'' - far read-only data, last 768 KiB of ROM
+  * ''.text'' - code, RAM
+  * ''.rodata'', ''.data'' - data, RAM
+  * ''.bss'' - zero-filled data, RAM
+Note that these act as prefixes - ''.text.a'' and ''.text.b'' will both be placed in RAM. This matters in particular for far code/data - ''.fartext.a'' and ''.fartext.b'' will both be placed in the last 768 KIB of ROM, but are allowed to use different 64 KiB segments to do so.
+To address RAM and ROM in assembly, one can use these very same sections manually.
+<code>
+.section .fartext.my_rom_code_segment, "ax"
+.section .farrodata.my_rom_data_segment, "a"
+.section .text.my_ram_code, "ax"
+.section .data.my_ram_data, "aw"
+</code>
+The quoted component at the end, like ''"ax"'', contains the ELF flags for a given section. These are not optional! The most useful ones are:
+  * ''a'' - section is allocated in RAM/ROM; if not used, the binary may end up not containing the data at all!
+  * ''w'' - section is writable
+  * ''x'' - section is executable
+  * ''R'' - section is retained, even if not used by any code
+All section flags are listed in [[https://wonderful.asie.pl/doc/binutils-ia16/as.html#Section-Name-Substitutions|the assembler manual]].
-By default, as discussed above, the following types of code and data will be placed into the following locations by the linker:
+===== Advanced section names =====
-  * Code (''.fartext'' section) and read-only data marked ''%%__wf_rom%%'' or ''%%__far%%'' (''.farrodata'' section) - the last 768 KiB "linear" bank of ROM,
+What if you want to place your code or data in a specific area of RAM? On the WonderSwan, especially the Color model, there are [[https://ws.nesdev.org/wiki/Memory_map#Internal|many restrictions]] as to where or with what alignment certain types of data (screen tables, tiles, audio wavetables) may be placed. Alternatively, what if you want to place your code/data in a manually bankable area of ROM?
-  * Data without such a modifier (''.rodata'', ''.data'' sections) - console IRAM.
-However, on the WonderSwan, especially the Color model, there are [[https://ws.nesdev.org/wiki/Memory_map#Internal|many restrictions]] as to where or with what alignment certain types of data (screen tables, tiles, audio wavetables) may be placed. For this reason, Wonderful's linking scheme has been extended to allow a special section name format. For example:
+To make this possible, Wonderful's linking approach has been extended to allow special section name patterns to be used. For example:
 <code C>
@@ Line 72: / Line 105: @@
 with the following optional arguments:
-  * **bank index** - the index of a bank, padded to the top of ROM.
+  * **bank index** - the index of a bank, in hexadecimal, padded to the top of ROM. For example, ''.rom0_f'' always refers to the final bank, even if the ROM has more than 16 banks.
-  * **offset** - the absolute offset within a bank or memory location.
+  * **offset** - the absolute offset within a bank or memory location, in hexademical. For example, ''.rom0_ffff_1234'' would place at location ''0x..FFFF1234'' in the cartridge image.
 Note that the linker requires //distinct// section names to place things separately: in other banks, memory locations, or for garbage collection. One can use ''.'' after the prefix to specify an unique name.