gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-30 14:57:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Redefine consistent names for section types, and document the changes.

Browse Source
This commit is contained in:
Anthony J. Bentley
2013-07-31 22:14:31 -06:00
parent 7ab9742299
commit 7770827cce
18 changed files with 145 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
doc/asm.htm
View File

@@ -42,7 +42,7 @@
<h3>Other ways than mnemonics to define data</h3>
<ul>
<li><a href="asm/db.htm">Defining constant data</a>
<li><a href="asm/ds.htm">Declaring variables in a BSS section</a>
<li><a href="asm/ds.htm">Declaring variables in a RAM section</a>
<li><a href="asm/incbin.htm">Including binary files</a>
</ul>
@@ -65,10 +65,7 @@
<li><a href="asm/expr_fix.htm">ATAN</a>
<li><a href="asm/expr_fix.htm">ATAN2</a>
<li><a href="asm/miscfunc.htm">BANK</a>
<li><a href="asm/section.htm">BSS</a>
<li><a href="asm/section.htm">CODE</a>
<li><a href="asm/expr_fix.htm">COS</a>
<li><a href="asm/section.htm">DATA</a>
<li><a href="asm/db.htm">DB</a>
<li><a href="asm/miscfunc.htm">DEF</a>
<li><a href="asm/expr_fix.htm">DIV</a>
@@ -101,6 +98,8 @@
<li><a href="asm/pops.htm">PUSHS</a>
<li><a href="asm/rept.htm">REPT</a>
<li><a href="asm/rs.htm">RB</a>
<li><a href="asm/section.htm">ROM0</a>
<li><a href="asm/section.htm">ROMX</a>
<li><a href="asm/rs.htm">RSRESET</a>
<li><a href="asm/rs.htm">RSSET</a>
<li><a href="asm/rs.htm">RW</a>
@@ -108,6 +107,7 @@
<li><a href="asm/set.htm">SET</a>
<li><a href="asm/shift.htm">SHIFT</a>
<li><a href="asm/expr_fix.htm">SIN</a>
<li><a href="asm/section.htm">SRAM</a>
<li><a href="asm/expr_str.htm">STRCAT</a>
<li><a href="asm/expr_str.htm">STRCMP</a>
<li><a href="asm/expr_str.htm">STRIN</a>
@@ -117,6 +117,8 @@
<li><a href="asm/expr_str.htm">STRUPR</a>
<li><a href="asm/expr_fix.htm">TAN</a>
<li><a href="asm/section.htm">VRAM</a>
<li><a href="asm/section.htm">WRAM0</a>
<li><a href="asm/section.htm">WRAMX</a>
<li><a href="asm/fail.htm">WARN</a>
<li><a href="asm/export.htm">XDEF</a>
<li><a href="asm/export.htm">XREF</a>

4
doc/asm/db.htm
View File

@@ -10,13 +10,13 @@
<p><dfn>DB</dfn> defines a list of bytes that will be stored in the final image. Ideal for tables and text.</p>
<pre>DB 1,2,3,4,"This is a string"</pre>
<p>Alternatively you can use <dfn>DW</dfn> to store a list of words. Strings are not allowed as arguments to DW.</p>
<p>You can also use DB and DW without arguments. This works exactly like “DS 1” and “DS 2” respectively. Consequently DB and DW can be used in a BSS/HRAM/VRAM section.</p>
<p>You can also use DB and DW without arguments. This works exactly like “DS 1” and “DS 2” respectively. Consequently DB and DW can be used in a WRAM0/WRAMX/HRAM/VRAM/SRAM section.</p>
<h1>See also:</h1>
<ul>
<li><a href="expr_int.htm">Integer and Boolean expressions</a>
<li><a href="expr_fix.htm">Fixed-point expressions and functions</a>
<li><a href="expr_str.htm">String expressions, functions and formatting</a>
<li><a href="ds.htm">Declaring variables in a BSS section</a>
<li><a href="ds.htm">Declaring variables in a RAM section</a>
<li><a href="miscfunc.htm">Other functions</a>
</ul>

2
doc/asm/ds.htm
View File

@@ -7,7 +7,7 @@
</head>
<body>
<h1>DS</h1>
<p><dfn>DS</dfn> allocates a number of bytes. The content is undefined. This is the preferred method of allocationg space in a <a href="section.htm">BSS section</a>. You can however also use DB and DW without any arguments.</p>
<p><dfn>DS</dfn> allocates a number of bytes. The content is undefined. This is the preferred method of allocationg space in a <a href="section.htm">RAM section</a>. You can however also use DB and DW without any arguments.</p>
<pre>DS str_SIZEOF ;allocate str_SIZEOF bytes</pre>
<h1>See also:</h1>
<ul>

85
doc/asm/section.htm
View File

@@ -8,47 +8,54 @@
<body>
<h1>SECTION</h1>
<p>Before you can start writing code you must define a section. This tells the assembler what kind of data follows and if it is code where to put it.</p>
<pre>SECTION "CoolStuff",CODE</pre>
<pre>SECTION "CoolStuff",ROMX</pre>
<p>This switches to the section called <b>"CoolStuff"</b> (or creates it if it doesn't already exits) and it defines it as a code section. All sections within a sourcefile must be identified by a <em>unique</em> name.</p>
<table>
<caption>Section types</caption>
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Function</th>
</tr>
</thead>
<tr>
<td>CODE</td>
<td>A code section. The linker decides where to put this. For the Gameboy it also decides which bank to put it in except #0 (the HOME bank).</td>
</tr>
<tr>
<td>DATA</td>
<td>Really just a synonym for CODE.</td>
</tr>
<tr>
<td>BSS</td>
<td>This section is for variables. For the Gameboy it will be placed where the Gameboy RAM is.</td>
</tr>
<tr>
<td>HOME</td>
<td>Gameboy ONLY: A code section that will be placed in Gameboy bank #0.</td>
</tr>
<tr>
<td>VRAM</td>
<td>Gameboy ONLY: This section is for allocating VRAM and will be placed where the Gameboy VRAM is.</td>
</tr>
<tr>
<td>HRAM</td>
<td>Gameboy ONLY: This section is for allocating variables in the high RAM area ($FF80-$FFFE) and will be placed there. Suggested by Jens Ch. Restemeier. NOTE WELL: if you use this method of allocating HRAM the assembler will NOT choose the short addressingmode in the LD instruction because the actual address calculation is done by the linker! If you find this undesirable you can use <a href="rs.htm">RSSET/RB/RW</a> instead or use the LDIO mnemonic. The address calculation is then done by the assembler.</td>
</tr>
</table>
<p>Possible section types are as follows:
<dl>
<dt>ROM0</dt>
<dd>A ROM section. Mapped to memory at $0000–$3fff.</dd>
<dt>ROMX</dt>
<dd>A banked ROM section. Mapped to memory at $4000–$7fff. Valid banks range from 1 to 511.</dd>
<dt>VRAM</dt>
<dd>A banked video RAM section. Mapped to memory at $8000–$9fff. Can only allocate memory, not fill it. Valid banks range from 0 to 1.</dd>
<dt>SRAM</dt>
<dd>A banked external (save) RAM section. Mapped to memory at $a000–$bfff. Can only allocate memory, not fill it. Valid banks range from 0 to 3.</dd>
<dt>WRAM0</dt>
<dd>A general-purpose RAM section. Mapped to memory at $c000–$cfff. Can only allocate memory, not fill it.</dd>
<dt>WRAMX</dt>
<dd>A banked general-purpose RAM section. Mapped to memory at $d000–$dfff. Can only allocate memory, not fill it. Valid banks range from 1 to 7.</dd>
<dt>HRAM</dt>
<dd>A high RAM section. Mapped to memory at $ff80–$fffe. Can only allocate memory, not fill it. NOTE WELL: if you use this method of allocating HRAM the assembler will NOT choose the short addressingmode in the LD instruction because the actual address calculation is done by the linker! If you find this undesirable you can use <a href="rs.htm">RSSET/RB/RW</a> instead or use the LDIO mnemonic. The address calculation is then done by the assembler.</dd>
</dl>
<p>The following deprecated section names are aliases for some of the above sections:
<dl>
<dt>HOME</dt>
<dd>Alias for ROM0.</dd>
<dt>CODE</dt>
<dt>DATA</dt>
<dd>Alias for ROMX.</dd>
<dt>BSS</dt>
<dd>Alias for WRAM0.</dd>
</dl>
<p>Due to quite a lot of emails requesting an ORG directive you can now add an address to the sectiontype for the Gameboy:</p>
<pre>SECTION "CoolStuff",HOME[$1234]</pre>
<p>This will force the section to address $1234. This also works with the other sectiontypes. For CODE/DATA sections the linker will then place the section in any bank at the address you specify. If you also want to specify the bank you can do:</p>
<pre>SECTION "CoolStuff",DATA[$4567],BANK[3]</pre>
<pre>SECTION "CoolStuff",ROM0[$1234]</pre>
<p>This will force the section to address $1234. This also works with the other sectiontypes. For ROMX sections the linker will then place the section in any bank at the address you specify. If you also want to specify the bank you can do:</p>
<pre>SECTION "CoolStuff",ROMX[$4567],BANK[3]</pre>
<p>And if you only want to force the section into a certain bank, and not it's position within the bank, that's also possible:</p>
<pre>SECTION "CoolStuff",CODE,BANK[7]</pre>
<pre>SECTION "CoolStuff",ROMX,BANK[7]</pre>
<p><strong>HINT:</strong> If you think this is a lot of typing for doing a simple ORG type thing you can quite easily write an intelligent macro (called ORG for example) that uses <a href="expr_str.htm">\@</a> for the sectionname and determines correct sectiontype etc as arguments for SECTION</p>
<h1>See also:</h1>
<ul>
@@ -58,6 +65,6 @@
<li><a href="pops.htm">POPS and PUSHS:</a> The section stack.
</ul>
<hr>
<p>Last updated <EFBFBD>18 July 1997 by <a href="mailto:surfsmurf@matilde.demon.co.uk">Carsten Sorensen</a></p>
<p>Last updated 18 July 1997 by <a href="mailto:surfsmurf@matilde.demon.co.uk">Carsten Sorensen</a></p>
</body>
</html>

17
doc/link.htm
View File

@@ -104,27 +104,14 @@
<p>A line starting with # is ignored.
<p>If you use libraries they will only be included if one of the objects actually reference them. This works on a SECTION level and not on a module level. This means that when you write libraries you can put each subroutine in its own SECTION so only the relevant bits are included.
<h2 id="operationtg">Operation for Gameboy (-tg)</h2>
<p><a href="asm.htm#sections">Sections</a> created with <b>HOME</b> in the assembler are placed in the GB bank #0 (the fixed bank $0000-$3FFF) in the order they are loaded from the objectfiles specified in the linkfile. So you want the first file in the linkfile to contain your header. <b>CODE/DATA</b> sections are placed in <em>any bank other than #0</em>. This means you have absolutely <em>no</em> control over which sections goes where. This insures minimal slack (unused bytes) at the end of each bank in the image.
<p><a href="asm.htm#sections">Sections</a> created with <b>ROM0</b> in the assembler are placed in the GB bank #0 (the fixed bank $0000-$3FFF) in the order they are loaded from the objectfiles specified in the linkfile. So you want the first file in the linkfile to contain your header. <b>ROMX</b> sections are placed in <em>any bank other than #0</em>. This means you have absolutely <em>no</em> control over which sections goes where. This insures minimal slack (unused bytes) at the end of each bank in the image.
<p>Currently the linker doesn't calculate the GB checksums.
You must use <a href="fix.htm">RGBFix</a> to do this.
<h3 id="smallmode">Operation for Gameboy small mode (-ts)</h3>
<p>Small mode forces all <b>DATA/CODE</b> sections to be of type <b>HOME</b> and increases the <b>HOME</b> section size from 16kB to 32kB. This also means that <b>CODE/DATA/HOME</b> sections are written to the final image in the order you have specified in the linkfile.
<p>Small mode forces all <b>ROMX</b> sections to be of type <b>ROM0</b> and increases the <b>ROM0</b> section size from 16kB to 32kB. This also means that <b>ROM0/ROMX</b> sections are written to the final image in the order you have specified on the command line.
<p>Currently the linker doesn't calculate the GB checksums. You must use <a href="fix.htm">RGBFix</a> to do this.
<h2 id="psion2">Operation for Psion2 relocatable modules (-tp)</h2>
<p>This is a fileformat for the Psion2 that allows you to load your code into where ever there's any free space. The only sections types allowed are <b>HOME, DATA and BSS</b>. All CODE and DATA sections are written to the output file in the order specified in the linkfile. The BSS are actually then expanded to DATA sections filled with zeroes and appended. This might change later.
<p>The file looks like this (all values are big endian):
<pre>
LONG NumberOfDataBytes
REPT NumberOfDataBytes
DB x
ENDR
LONG NumberOfPatches
REPT NumberOfPatches
LONG x ; A value to add to the word at address x in the code
ENDR
</pre>
<hr>
<p>Last updated 08 October 1997 by <a href="mailto:surfsmurf@matilde.demon.co.uk">Carsten Sorensen</a></p>
</body>

10
doc/rgb0.htm
View File

@@ -50,10 +50,10 @@
REPT NumberOfSections
LONG Size ;Size in bytes of this section
BYTE Type ;0 = BSS
BYTE Type ;0 = WRAM0
;1 = VRAM
;2 = CODE
;3 = HOME
;2 = ROMX
;3 = ROM0
;4 = HRAM
LONG Org ;Only present in RGB1. Address to fix this
;section at. -1 if the linker should
@@ -61,8 +61,8 @@
LONG Bank ;Only present in RGB1. Bank to load this
;section into. -1 if the linker should
;decide (normal operation). This field is
;only valid for CODE sections.
IF Type==CODE || Type==HOME
;only valid for ROMX sections.
IF Type==ROMX || Type==ROM0
BYTE Data[Size]
LONG NumberOfPatches