ref: 80170eb6ebedd5bee9df32433ee0da21a14a3178
parent: bdad1499fe326fb0b76717255b32026494c7daa0
author: ISSOtm <[email protected]>
date: Fri Apr 3 08:03:59 EDT 2020
Regenerate man page HTML renders
--- a/docs/gbz80.7.html
+++ b/docs/gbz80.7.html
@@ -8,8 +8,10 @@
SPDX-License-Identifier: MIT
-->
<head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+ <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
<title>GBZ80(7)</title>
</head>
<body>
@@ -24,18 +26,18 @@
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">gbz80</code> —
-<div class="Nd">CPU opcode reference</div>
+<span class="Nd">CPU opcode reference</span>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-This is the list of opcodes supported by <a class="Xr">rgbasm(1)</a>, including
+This is the list of opcodes supported by <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, including
a short description, the number of bytes needed to encode them and the number
of CPU cycles at 1MHz (or 2MHz in GBC dual speed mode) needed to complete
them.
<p class="Pp">Note: All arithmetic/logic operations that use register
<b class="Sy">A</b> as destination can omit the destination as it is assumed
- it's register <b class="Sy">A</b>. The following two lines have the same
- effect:</p>
+ to be register <b class="Sy">A</b> by default. The following two lines have
+ the same effect:</p>
<div class="Bd Pp Bd-indent">
<pre>
OR A,B
@@ -59,8 +61,7 @@
<dt><var class="Ar">n16</var></dt>
<dd>16-bit integer constant.</dd>
<dt><var class="Ar">e8</var></dt>
- <dd>8-bit offset (<code class="Fl">-</code><b class="Sy">128</b> to
- <b class="Sy">127</b>).</dd>
+ <dd>8-bit offset (<b class="Sy">-128</b> to <b class="Sy">127</b>).</dd>
<dt><var class="Ar">u3</var></dt>
<dd>3-bit unsigned integer constant (<b class="Sy">0</b> to
<b class="Sy">7</b>).</dd>
@@ -67,18 +68,18 @@
<dt><var class="Ar">cc</var></dt>
<dd>Condition codes:
<dl class="Bl-tag Bl-compact">
- <dt><b class="Sy">Z</b>:</dt>
+ <dt><b class="Sy">Z</b></dt>
<dd>Execute if Z is set.</dd>
- <dt><b class="Sy">NZ</b>:</dt>
+ <dt><b class="Sy">NZ</b></dt>
<dd>Execute if Z is not set.</dd>
- <dt><b class="Sy">C</b>:</dt>
+ <dt><b class="Sy">C</b></dt>
<dd>Execute if C is set.</dd>
- <dt><b class="Sy">NC</b>:</dt>
+ <dt><b class="Sy">NC</b></dt>
<dd>Execute if C is not set.</dd>
</dl>
</dd>
<dt><var class="Ar">vec</var></dt>
- <dd>One of the <var class="Ar">RST</var> vectors (<b class="Sy">0x00</b>,
+ <dd>One of the <b class="Sy">RST</b> vectors (<b class="Sy">0x00</b>,
<b class="Sy">0x08</b>, <b class="Sy">0x10</b>, <b class="Sy">0x18</b>,
<b class="Sy">0x20</b>, <b class="Sy">0x28</b>, <b class="Sy">0x30</b> and
<b class="Sy">0x38</b>).</dd>
@@ -245,25 +246,25 @@
<dd></dd>
<dt><a class="Sx" href="#LD__n16_,A">LD [n16],A</a></dt>
<dd></dd>
- <dt><a class="Sx" href="#LD__$FF00+n8_,A">LD [$FF00+n8],A</a></dt>
+ <dt><a class="Sx" href="#LDH__n16_,A">LDH [n16],A</a></dt>
<dd></dd>
- <dt><a class="Sx" href="#LD__$FF00+C_,A">LD [$FF00+C],A</a></dt>
+ <dt><a class="Sx" href="#LDH__C_,A">LDH [C],A</a></dt>
<dd></dd>
<dt><a class="Sx" href="#LD_A,_r16_">LD A,[r16]</a></dt>
<dd></dd>
<dt><a class="Sx" href="#LD_A,_n16_">LD A,[n16]</a></dt>
<dd></dd>
- <dt><a class="Sx" href="#LD_A,_$FF00+n8_">LD A,[$FF00+n8]</a></dt>
+ <dt><a class="Sx" href="#LDH_A,_n16_">LDH A,[n16]</a></dt>
<dd></dd>
- <dt><a class="Sx" href="#LD_A,_$FF00+C_">LD A,[$FF00+C]</a></dt>
+ <dt><a class="Sx" href="#LDH_A,_C_">LDH A,[C]</a></dt>
<dd></dd>
- <dt><a class="Sx" href="#LD__HL+_,A">LD [HL+],A</a></dt>
+ <dt><a class="Sx" href="#LD__HLI_,A">LD [HLI],A</a></dt>
<dd></dd>
- <dt><a class="Sx" href="#LD__HL-_,A">LD [HL-],A</a></dt>
+ <dt><a class="Sx" href="#LD__HLD_,A">LD [HLD],A</a></dt>
<dd></dd>
- <dt><a class="Sx" href="#LD_A,_HL+_">LD A,[HL+]</a></dt>
+ <dt><a class="Sx" href="#LD_A,_HLI_">LD A,[HLI]</a></dt>
<dd></dd>
- <dt><a class="Sx" href="#LD_A,_HL-_">LD A,[HL-]</a></dt>
+ <dt><a class="Sx" href="#LD_A,_HLD_">LD A,[HLD]</a></dt>
<dd></dd>
</dl>
</section>
@@ -361,17 +362,21 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: Set if overflow from bit 3.</li>
- <li><b class="Sy">C</b>: Set if overflow from bit 7.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if overflow from bit 3.</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set if overflow from bit 7.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="ADC_A,_HL_"><a class="permalink" href="#ADC_A,_HL_">ADC
A,[HL]</a></h2>
-Add the value pointed by <b class="Sy">HL</b> plus the carry flag to
+Add the byte pointed to by <b class="Sy">HL</b> plus the carry flag to
<b class="Sy">A</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
@@ -393,17 +398,21 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: Set if overflow from bit 3.</li>
- <li><b class="Sy">C</b>: Set if overflow from bit 7.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if overflow from bit 3.</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set if overflow from bit 7.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="ADD_A,_HL_"><a class="permalink" href="#ADD_A,_HL_">ADD
A,[HL]</a></h2>
-Add the value pointed by <b class="Sy">HL</b> to <b class="Sy">A</b>.
+Add the byte pointed to by <b class="Sy">HL</b> to <b class="Sy">A</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: See <a class="Sx" href="#ADD_A,r8">ADD A,r8</a></p>
@@ -423,11 +432,14 @@
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: Set if overflow from bit 11.</li>
- <li><b class="Sy">C</b>: Set if overflow from bit 15.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if overflow from bit 11.</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set if overflow from bit 15.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="ADD_HL,SP"><a class="permalink" href="#ADD_HL,SP">ADD
@@ -444,12 +456,16 @@
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: 0</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: Set if overflow from bit 3.</li>
- <li><b class="Sy">C</b>: Set if overflow from bit 7.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if overflow from bit 3.</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set if overflow from bit 7.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="AND_A,r8"><a class="permalink" href="#AND_A,r8">AND
@@ -459,17 +475,21 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 1</li>
- <li><b class="Sy">C</b>: 0</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>1</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>0</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="AND_A,_HL_"><a class="permalink" href="#AND_A,_HL_">AND
A,[HL]</a></h2>
-Bitwise AND between the value pointed by <b class="Sy">HL</b> and
+Bitwise AND between the byte pointed to by <b class="Sy">HL</b> and
<b class="Sy">A</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
@@ -492,11 +512,14 @@
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if the selected bit is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 1</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if the selected bit is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>1</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="BIT_u3,_HL_"><a class="permalink" href="#BIT_u3,_HL_">BIT
@@ -510,7 +533,10 @@
<section class="Ss">
<h2 class="Ss" id="CALL_n16"><a class="permalink" href="#CALL_n16">CALL
n16</a></h2>
-Call address <var class="Ar">n16</var>.
+Call address <var class="Ar">n16</var>. This pushes the address of the
+ instruction after the <b class="Sy">CALL</b> on the stack, such that
+ <a class="Sx" href="#RET">RET</a> can pop it later; then, it executes an
+ implicit <a class="Sx" href="#JP_n16">JP n16</a>.
<p class="Pp">Cycles: 6</p>
<p class="Pp">Bytes: 3</p>
<p class="Pp">Flags: None affected.</p>
@@ -520,7 +546,7 @@
cc,n16</a></h2>
Call address <var class="Ar">n16</var> if condition <var class="Ar">cc</var> is
met.
-<p class="Pp">Cycles: 6/3</p>
+<p class="Pp">Cycles: 6 taken / 3 untaken</p>
<p class="Pp">Bytes: 3</p>
<p class="Pp">Flags: None affected.</p>
</section>
@@ -530,33 +556,41 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Complemented.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Inverted.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="CP_A,r8"><a class="permalink" href="#CP_A,r8">CP
A,r8</a></h2>
Subtract the value in <var class="Ar">r8</var> from <b class="Sy">A</b> and set
- flags accordingly, but don't store the result.
+ flags accordingly, but don't store the result. This is useful for ComParing
+ values.
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 1</li>
- <li><b class="Sy">H</b>: Set if no borrow from bit 4.</li>
- <li><b class="Sy">C</b>: Set if no borrow (set if <var class="Ar">r8</var>
- > <b class="Sy">A</b>).</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>1</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if borrow from bit 4.</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set if borrow (i.e. if <var class="Ar">r8</var> >
+ <b class="Sy">A</b>).</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="CP_A,_HL_"><a class="permalink" href="#CP_A,_HL_">CP
A,[HL]</a></h2>
-Subtract the value pointed by <b class="Sy">HL</b> from <b class="Sy">A</b> and
- set flags accordingly, but don't store the result.
+Subtract the byte pointed to by <b class="Sy">HL</b> from <b class="Sy">A</b>
+ and set flags accordingly, but don't store the result.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: See <a class="Sx" href="#CP_A,r8">CP A,r8</a></p>
@@ -572,27 +606,32 @@
</section>
<section class="Ss">
<h2 class="Ss" id="CPL"><a class="permalink" href="#CPL">CPL</a></h2>
-Complement accumulator (<b class="Sy">A</b> = <b class="Sy">~A</b>).
+ComPLement accumulator (<b class="Sy">A</b> = <b class="Sy">~A</b>).
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">N</b>: 1</li>
- <li><b class="Sy">H</b>: 1</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">N</b></dt>
+ <dd>1</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>1</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="DAA"><a class="permalink" href="#DAA">DAA</a></h2>
-Decimal adjust register A to get a correct BCD representation after an
+Decimal Adjust Accumulator to get a correct BCD representation after an
arithmetic instruction.
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set or reset depending on the operation.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set or reset depending on the operation.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="DEC_r8"><a class="permalink" href="#DEC_r8">DEC r8</a></h2>
@@ -600,16 +639,19 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 1</li>
- <li><b class="Sy">H</b>: Set if no borrow from bit 4.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>1</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if borrow from bit 4.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="DEC__HL_"><a class="permalink" href="#DEC__HL_">DEC
[HL]</a></h2>
-Decrement the value pointed by <b class="Sy">HL</b> by 1.
+Decrement the byte pointed to by <b class="Sy">HL</b> by 1.
<p class="Pp">Cycles: 3</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: See <a class="Sx" href="#DEC_r8">DEC r8</a></p>
@@ -631,7 +673,7 @@
</section>
<section class="Ss">
<h2 class="Ss" id="DI"><a class="permalink" href="#DI">DI</a></h2>
-Disable Interrupts.
+Disable Interrupts by clearing the <b class="Sy">IME</b> flag.
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -638,7 +680,8 @@
</section>
<section class="Ss">
<h2 class="Ss" id="EI"><a class="permalink" href="#EI">EI</a></h2>
-Enable Interrupts.
+Enable Interrupts by setting the <b class="Sy">IME</b> flag. The flag is only
+ set <i class="Em">after</i> the instruction following <b class="Sy">EI</b>.
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -645,7 +688,30 @@
</section>
<section class="Ss">
<h2 class="Ss" id="HALT"><a class="permalink" href="#HALT">HALT</a></h2>
-Enter CPU low power mode.
+Enter CPU low-power consumption mode until an interrupt occurs. The exact
+ behavior of this instruction depends on the state of the <b class="Sy">IME</b>
+ flag.
+<dl class="Bl-tag">
+ <dt><b class="Sy">IME</b> <span class="No">set</span></dt>
+ <dd>The CPU enters low-power mode until <i class="Em">after</i> an interrupt
+ is about to be serviced. The handler is executed normally, and the CPU
+ resumes execution after the <code class="Ic">HALT</code> when that
+ returns.</dd>
+ <dt><b class="Sy">IME</b> <span class="No">not set</span></dt>
+ <dd>The behavior depends on whether an interrupt is pending (i.e.
+ ‘<code class="Li">[IE] & [IF]</code>’ is non-zero).
+ <dl class="Bl-tag">
+ <dt>None pending</dt>
+ <dd>As soon as an interrupt becomes pending, the CPU resumes execution.
+ This is like the above, except that the handler is
+ <i class="Em">not</i> called.</dd>
+ <dt>Some pending</dt>
+ <dd>The CPU continues execution after the <code class="Ic">HALT</code>,
+ but the byte after it is read twice in a row (<b class="Sy">PC</b> is
+ not incremented, due to a hardware bug).</dd>
+ </dl>
+ </dd>
+</dl>
<p class="Pp">Cycles: -</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -656,16 +722,19 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: Set if overflow from bit 3.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if overflow from bit 3.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="INC__HL_"><a class="permalink" href="#INC__HL_">INC
[HL]</a></h2>
-Increment the value pointed by <b class="Sy">HL</b> by 1.
+Increment the byte pointed to by <b class="Sy">HL</b> by 1.
<p class="Pp">Cycles: 3</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: See <a class="Sx" href="#INC_r8">INC r8</a></p>
@@ -687,7 +756,8 @@
</section>
<section class="Ss">
<h2 class="Ss" id="JP_n16"><a class="permalink" href="#JP_n16">JP n16</a></h2>
-Absolute jump to address <var class="Ar">n16</var>.
+Jump to address <var class="Ar">n16</var>; effectively, store
+ <var class="Ar">n16</var> into <b class="Sy">PC</b>.
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 3</p>
<p class="Pp">Flags: None affected.</p>
@@ -695,16 +765,16 @@
<section class="Ss">
<h2 class="Ss" id="JP_cc,n16"><a class="permalink" href="#JP_cc,n16">JP
cc,n16</a></h2>
-Absolute jump to address <var class="Ar">n16</var> if condition
- <var class="Ar">cc</var> is met.
-<p class="Pp">Cycles: 4/3</p>
+Jump to address <var class="Ar">n16</var> if condition <var class="Ar">cc</var>
+ is met.
+<p class="Pp">Cycles: 4 taken / 3 untaken</p>
<p class="Pp">Bytes: 3</p>
<p class="Pp">Flags: None affected.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="JP_HL"><a class="permalink" href="#JP_HL">JP HL</a></h2>
-Jump to address in <b class="Sy">HL</b>, that is, load <b class="Sy">PC</b> with
- value in register <b class="Sy">HL</b>.
+Jump to address in <b class="Sy">HL</b>; effectively, load <b class="Sy">PC</b>
+ with value in register <b class="Sy">HL</b>.
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -711,7 +781,9 @@
</section>
<section class="Ss">
<h2 class="Ss" id="JR_e8"><a class="permalink" href="#JR_e8">JR e8</a></h2>
-Relative jump by adding <var class="Ar">e8</var> to the current address.
+Relative Jump by adding <var class="Ar">e8</var> to the address of the
+ instruction following the <b class="Sy">JR</b>. To clarify, an operand of 0 is
+ equivalent to no jumping.
<p class="Pp">Cycles: 3</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags: None affected.</p>
@@ -719,9 +791,9 @@
<section class="Ss">
<h2 class="Ss" id="JR_cc,e8"><a class="permalink" href="#JR_cc,e8">JR
cc,e8</a></h2>
-Relative jump by adding <var class="Ar">e8</var> to the current address if
+Relative Jump by adding <var class="Ar">e8</var> to the current address if
condition <var class="Ar">cc</var> is met.
-<p class="Pp">Cycles: 3/2</p>
+<p class="Pp">Cycles: 3 taken / 2 untaken</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags: None affected.</p>
</section>
@@ -728,7 +800,7 @@
<section class="Ss">
<h2 class="Ss" id="LD_r8,r8"><a class="permalink" href="#LD_r8,r8">LD
r8,r8</a></h2>
-Store value in register on the right into register on the left.
+Load (copy) value in register on the right into register on the left.
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -752,8 +824,8 @@
<section class="Ss">
<h2 class="Ss" id="LD__HL_,r8"><a class="permalink" href="#LD__HL_,r8">LD
[HL],r8</a></h2>
-Store value in register <var class="Ar">r8</var> into byte pointed by register
- <b class="Sy">HL</b>.
+Store value in register <var class="Ar">r8</var> into byte pointed to by
+ register <b class="Sy">HL</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -761,7 +833,7 @@
<section class="Ss">
<h2 class="Ss" id="LD__HL_,n8"><a class="permalink" href="#LD__HL_,n8">LD
[HL],n8</a></h2>
-Store value <var class="Ar">n8</var> into byte pointed by register
+Store value <var class="Ar">n8</var> into byte pointed to by register
<b class="Sy">HL</b>.
<p class="Pp">Cycles: 3</p>
<p class="Pp">Bytes: 2</p>
@@ -770,8 +842,8 @@
<section class="Ss">
<h2 class="Ss" id="LD_r8,_HL_"><a class="permalink" href="#LD_r8,_HL_">LD
r8,[HL]</a></h2>
-Load value into register <var class="Ar">r8</var> from byte pointed by register
- <b class="Sy">HL</b>.
+Load value into register <var class="Ar">r8</var> from byte pointed to by
+ register <b class="Sy">HL</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -779,7 +851,7 @@
<section class="Ss">
<h2 class="Ss" id="LD__r16_,A"><a class="permalink" href="#LD__r16_,A">LD
[r16],A</a></h2>
-Store value in register <b class="Sy">A</b> into address pointed by register
+Store value in register <b class="Sy">A</b> into byte pointed to by register
<var class="Ar">r16</var>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
@@ -788,7 +860,7 @@
<section class="Ss">
<h2 class="Ss" id="LD__n16_,A"><a class="permalink" href="#LD__n16_,A">LD
[n16],A</a></h2>
-Store value in register <b class="Sy">A</b> into address
+Store value in register <b class="Sy">A</b> into byte at address
<var class="Ar">n16</var>.
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 3</p>
@@ -795,27 +867,34 @@
<p class="Pp">Flags: None affected.</p>
</section>
<section class="Ss">
-<h2 class="Ss" id="LD__$FF00+n8_,A"><a class="permalink" href="#LD__$FF00+n8_,A">LD
- [$FF00+n8],A</a></h2>
-Store value in register <b class="Sy">A</b> into high RAM or I/O registers.
-<p class="Pp">The following synonym forces this encoding: <b class="Sy">LDH
- [$FF00+n8],A</b></p>
+<h2 class="Ss" id="LDH__n16_,A"><a class="permalink" href="#LDH__n16_,A">LDH
+ [n16],A</a></h2>
+Store value in register <b class="Sy">A</b> into byte at address
+ <var class="Ar">n16</var>, provided it is between
+ <span class="Ad">$FF00</span> and <span class="Ad">$FFFF</span>.
<p class="Pp">Cycles: 3</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags: None affected.</p>
+<p class="Pp">This is sometimes written as ‘<code class="Li">ldio [n16],
+ a</code>’, or ‘<code class="Li">ld [$ff00+n8],
+ a</code>’.</p>
</section>
<section class="Ss">
-<h2 class="Ss" id="LD__$FF00+C_,A"><a class="permalink" href="#LD__$FF00+C_,A">LD
- [$FF00+C],A</a></h2>
-Store value in register <b class="Sy">A</b> into high RAM or I/O registers.
+<h2 class="Ss" id="LDH__C_,A"><a class="permalink" href="#LDH__C_,A">LDH
+ [C],A</a></h2>
+Store value in register <b class="Sy">A</b> into byte at address
+ <span class="Ad">$FF00+C</span>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
+<p class="Pp">This is sometimes written as ‘<code class="Li">ldio [c],
+ a</code>’, or ‘<code class="Li">ld [$ff00+c],
+ a</code>’.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="LD_A,_r16_"><a class="permalink" href="#LD_A,_r16_">LD
A,[r16]</a></h2>
-Load value in register <b class="Sy">A</b> from address pointed by register
+Load value in register <b class="Sy">A</b> from byte pointed to by register
<var class="Ar">r16</var>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
@@ -824,7 +903,7 @@
<section class="Ss">
<h2 class="Ss" id="LD_A,_n16_"><a class="permalink" href="#LD_A,_n16_">LD
A,[n16]</a></h2>
-Load value in register <b class="Sy">A</b> from address
+Load value in register <b class="Sy">A</b> from byte at address
<var class="Ar">n16</var>.
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 3</p>
@@ -831,55 +910,62 @@
<p class="Pp">Flags: None affected.</p>
</section>
<section class="Ss">
-<h2 class="Ss" id="LD_A,_$FF00+n8_"><a class="permalink" href="#LD_A,_$FF00+n8_">LD
- A,[$FF00+n8]</a></h2>
-Load value in register <b class="Sy">A</b> from high RAM or I/O registers.
-<p class="Pp">The following synonym forces this encoding: <b class="Sy">LDH
- A,[$FF00+n8]</b></p>
+<h2 class="Ss" id="LDH_A,_n16_"><a class="permalink" href="#LDH_A,_n16_">LDH
+ A,[n16]</a></h2>
+Load value in register <b class="Sy">A</b> from byte at address
+ <var class="Ar">n16</var>, provided it is between
+ <span class="Ad">$FF00</span> and <span class="Ad">$FFFF</span>.
<p class="Pp">Cycles: 3</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags: None affected.</p>
+<p class="Pp">This is sometimes written as ‘<code class="Li">ldio a,
+ [n16]</code>’, or ‘<code class="Li">ld a,
+ [$ff00+n8]</code>’.</p>
</section>
<section class="Ss">
-<h2 class="Ss" id="LD_A,_$FF00+C_"><a class="permalink" href="#LD_A,_$FF00+C_">LD
- A,[$FF00+C]</a></h2>
-Load value in register <b class="Sy">A</b> from high RAM or I/O registers.
+<h2 class="Ss" id="LDH_A,_C_"><a class="permalink" href="#LDH_A,_C_">LDH
+ A,[C]</a></h2>
+Load value in register <b class="Sy">A</b> from byte at address
+ <span class="Ad">$FF00+c</span>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
+<p class="Pp">This is sometimes written as ‘<code class="Li">ldio a,
+ [c]</code>’, or ‘<code class="Li">ld a,
+ [$ff00+c]</code>’.</p>
</section>
<section class="Ss">
-<h2 class="Ss" id="LD__HL+_,A"><a class="permalink" href="#LD__HL+_,A">LD
- [HL+],A</a></h2>
+<h2 class="Ss" id="LD__HLI_,A"><a class="permalink" href="#LD__HLI_,A">LD
+ [HLI],A</a></h2>
Store value in register <b class="Sy">A</b> into byte pointed by
- <b class="Sy">HL</b> and post-increment <b class="Sy">HL</b>.
+ <b class="Sy">HL</b> and increment <b class="Sy">HL</b> afterwards.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
</section>
<section class="Ss">
-<h2 class="Ss" id="LD__HL-_,A"><a class="permalink" href="#LD__HL-_,A">LD
- [HL-],A</a></h2>
+<h2 class="Ss" id="LD__HLD_,A"><a class="permalink" href="#LD__HLD_,A">LD
+ [HLD],A</a></h2>
Store value in register <b class="Sy">A</b> into byte pointed by
- <b class="Sy">HL</b> and post-decrement <b class="Sy">HL</b>.
+ <b class="Sy">HL</b> and decrement <b class="Sy">HL</b> afterwards.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
</section>
<section class="Ss">
-<h2 class="Ss" id="LD_A,_HL+_"><a class="permalink" href="#LD_A,_HL+_">LD
- A,[HL+]</a></h2>
+<h2 class="Ss" id="LD_A,_HLD_"><a class="permalink" href="#LD_A,_HLD_">LD
+ A,[HLD]</a></h2>
Load value into register <b class="Sy">A</b> from byte pointed by
- <b class="Sy">HL</b> and post-increment <b class="Sy">HL</b>.
+ <b class="Sy">HL</b> and decrement <b class="Sy">HL</b> afterwards.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
</section>
<section class="Ss">
-<h2 class="Ss" id="LD_A,_HL-_"><a class="permalink" href="#LD_A,_HL-_">LD
- A,[HL-]</a></h2>
+<h2 class="Ss" id="LD_A,_HLI_"><a class="permalink" href="#LD_A,_HLI_">LD
+ A,[HLI]</a></h2>
Load value into register <b class="Sy">A</b> from byte pointed by
- <b class="Sy">HL</b> and post-decrement <b class="Sy">HL</b>.
+ <b class="Sy">HL</b> and increment <b class="Sy">HL</b> afterwards.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -895,8 +981,8 @@
<section class="Ss">
<h2 class="Ss" id="LD__n16_,SP"><a class="permalink" href="#LD__n16_,SP">LD
[n16],SP</a></h2>
-Store <b class="Sy">SP</b> into addresses <var class="Ar">n16</var> (LSB) and
- <var class="Ar">n16</var> + 1 (MSB).
+Store <b class="Sy">SP & $FF</b> at address <var class="Ar">n16</var> and
+ <b class="Sy">SP >> 8</b> at address <var class="Ar">n16</var> + 1.
<p class="Pp">Cycles: 5</p>
<p class="Pp">Bytes: 3</p>
<p class="Pp">Flags: None affected.</p>
@@ -905,16 +991,20 @@
<h2 class="Ss" id="LD_HL,SP+e8"><a class="permalink" href="#LD_HL,SP+e8">LD
HL,SP+e8</a></h2>
Add the signed value <var class="Ar">e8</var> to <b class="Sy">SP</b> and store
- the result in <b class="Sy">HL.</b>
+ the result in <b class="Sy">HL</b>.
<p class="Pp">Cycles: 3</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: 0</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: Set if overflow from bit 3.</li>
- <li><b class="Sy">C</b>: Set if overflow from bit 7.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if overflow from bit 3.</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set if overflow from bit 7.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="LD_SP,HL"><a class="permalink" href="#LD_SP,HL">LD
@@ -926,7 +1016,7 @@
</section>
<section class="Ss">
<h2 class="Ss" id="NOP"><a class="permalink" href="#NOP">NOP</a></h2>
-No operation.
+No OPeration.
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -934,23 +1024,27 @@
<section class="Ss">
<h2 class="Ss" id="OR_A,r8"><a class="permalink" href="#OR_A,r8">OR
A,r8</a></h2>
-Bitwise OR between the value in <var class="Ar">r8</var> and
- <b class="Sy">A</b>.
+Store into <b class="Sy">A</b> the bitwise OR of the value in
+ <var class="Ar">r8</var> and <b class="Sy">A</b>.
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: 0</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>0</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="OR_A,_HL_"><a class="permalink" href="#OR_A,_HL_">OR
A,[HL]</a></h2>
-Bitwise OR between the value pointed by <b class="Sy">HL</b> and
- <b class="Sy">A</b>.
+Store into <b class="Sy">A</b> the bitwise OR of the byte pointed to by
+ <b class="Sy">HL</b> and <b class="Sy">A</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: See <a class="Sx" href="#OR_A,r8">OR A,r8</a></p>
@@ -958,7 +1052,7 @@
<section class="Ss">
<h2 class="Ss" id="OR_A,n8"><a class="permalink" href="#OR_A,n8">OR
A,n8</a></h2>
-Bitwise OR between the value in <var class="Ar">n8</var> and
+Store into <b class="Sy">A</b> the bitwise OR of <var class="Ar">n8</var> and
<b class="Sy">A</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
@@ -966,21 +1060,43 @@
</section>
<section class="Ss">
<h2 class="Ss" id="POP_AF"><a class="permalink" href="#POP_AF">POP AF</a></h2>
-Pop register <b class="Sy">AF</b> from the stack.
+Pop register <b class="Sy">AF</b> from the stack. This is roughly equivalent to
+ the following <i class="Em">imaginary</i> instructions:
+<div class="Bd Pp Bd-indent">
+<pre>
+inc sp
+ld a, [sp]
+inc sp
+ld f, [sp] ; See below for individual flags
+</pre>
+</div>
<p class="Pp">Cycles: 3</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set from bit 7 of the popped low byte.</li>
- <li><b class="Sy">N</b>: Set from bit 6 of the popped low byte.</li>
- <li><b class="Sy">H</b>: Set from bit 5 of the popped low byte.</li>
- <li><b class="Sy">C</b>: Set from bit 4 of the popped low byte.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set from bit 7 of the popped low byte.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>Set from bit 6 of the popped low byte.</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set from bit 5 of the popped low byte.</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set from bit 4 of the popped low byte.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="POP_r16"><a class="permalink" href="#POP_r16">POP
r16</a></h2>
-Pop register <var class="Ar">r16</var> from the stack.
+Pop register <var class="Ar">r16</var> from the stack. This is roughly
+ equivalent to the following <i class="Em">imaginary</i> instructions:
+<div class="Bd Pp Bd-indent">
+<pre>
+ld LOW(r16), [sp] ; C, E or L
+inc sp
+ld HIGH(r16), [sp] ; B, D or H
+inc sp
+</pre>
+</div>
<p class="Pp">Cycles: 3</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -988,10 +1104,16 @@
<section class="Ss">
<h2 class="Ss" id="PUSH_AF"><a class="permalink" href="#PUSH_AF">PUSH
AF</a></h2>
-Push register <b class="Sy">AF</b> into the stack. The low byte's bit 7
- corresponds to the <b class="Sy">Z</b> flag, its bit 6 to the
- <b class="Sy">N</b> flag, bit 5 to the <b class="Sy">H</b> flag, and bit 4 to
- the <b class="Sy">C</b> flag. Bits 3 to 0 are reset.
+Push register <b class="Sy">AF</b> into the stack. This is roughly equivalent to
+ the following <i class="Em">imaginary</i> instructions:
+<div class="Bd Pp Bd-indent">
+<pre>
+dec sp
+ld [sp], a
+dec sp
+ld [sp], flag_Z << 7 | flag_N << 6 | flag_H << 5 | flag_C << 4
+</pre>
+</div>
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -999,7 +1121,16 @@
<section class="Ss">
<h2 class="Ss" id="PUSH_r16"><a class="permalink" href="#PUSH_r16">PUSH
r16</a></h2>
-Push register <var class="Ar">r16</var> into the stack.
+Push register <var class="Ar">r16</var> into the stack. This is roughly
+ equivalent to the following <i class="Em">imaginary</i> instructions:
+<div class="Bd Pp Bd-indent">
+<pre>
+dec sp
+ld [sp], HIGH(r16) ; B, D or H
+dec sp
+ld [sp], LOW(r16) ; C, E or L
+</pre>
+</div>
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -1007,7 +1138,8 @@
<section class="Ss">
<h2 class="Ss" id="RES_u3,r8"><a class="permalink" href="#RES_u3,r8">RES
u3,r8</a></h2>
-Set bit <var class="Ar">u3</var> in register <var class="Ar">r8</var> to 0.
+Set bit <var class="Ar">u3</var> in register <var class="Ar">r8</var> to 0. Bit
+ 0 is the rightmost one, bit 7 the leftmost one.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags: None affected.</p>
@@ -1016,7 +1148,7 @@
<h2 class="Ss" id="RES_u3,_HL_"><a class="permalink" href="#RES_u3,_HL_">RES
u3,[HL]</a></h2>
Set bit <var class="Ar">u3</var> in the byte pointed by <b class="Sy">HL</b> to
- 0.
+ 0. Bit 0 is the rightmost one, bit 7 the leftmost one.
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags: None affected.</p>
@@ -1023,7 +1155,9 @@
</section>
<section class="Ss">
<h2 class="Ss" id="RET"><a class="permalink" href="#RET">RET</a></h2>
-Return from subroutine.
+Return from subroutine. This is basically a <b class="Sy">POP PC</b> (if such an
+ instruction existed). See <a class="Sx" href="#POP_r16">POP r16</a> for an
+ explanation of how <b class="Sy">POP</b> works.
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -1031,13 +1165,16 @@
<section class="Ss">
<h2 class="Ss" id="RET_cc"><a class="permalink" href="#RET_cc">RET cc</a></h2>
Return from subroutine if condition <var class="Ar">cc</var> is met.
-<p class="Pp">Cycles: 5/2</p>
+<p class="Pp">Cycles: 5 taken / 2 untaken</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="RETI"><a class="permalink" href="#RETI">RETI</a></h2>
-Return from subroutine and enable interrupts.
+Return from subroutine and enable interrupts. This is basically equivalent to
+ executing <a class="Sx" href="#EI">EI</a> then
+ <a class="Sx" href="#RET">RET</a>, meaning that <b class="Sy">IME</b> is set
+ right after this instruction.
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -1044,23 +1181,27 @@
</section>
<section class="Ss">
<h2 class="Ss" id="RL_r8"><a class="permalink" href="#RL_r8">RL r8</a></h2>
-Rotate register <var class="Ar">r8</var> left through carry.
+Rotate bits in register <var class="Ar">r8</var> left through carry.
<p class="Pp"></p>
<div class="Bd Bd-indent">C <- [7 <- 0] <- C</div>
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="RL__HL_"><a class="permalink" href="#RL__HL_">RL
[HL]</a></h2>
-Rotate value pointed by <b class="Sy">HL</b> left through carry.
+Rotate byte pointed to by <b class="Sy">HL</b> left through carry.
<p class="Pp"></p>
<div class="Bd Bd-indent">C <- [7 <- 0] <- C</div>
<p class="Pp">Cycles: 4</p>
@@ -1075,12 +1216,16 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: 0</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="RLC_r8"><a class="permalink" href="#RLC_r8">RLC r8</a></h2>
@@ -1090,17 +1235,21 @@
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="RLC__HL_"><a class="permalink" href="#RLC__HL_">RLC
[HL]</a></h2>
-Rotate value pointed by <b class="Sy">HL</b> left.
+Rotate byte pointed to by <b class="Sy">HL</b> left.
<p class="Pp"></p>
<div class="Bd Bd-indent">C <- [7 <- 0] <- [7]</div>
<p class="Pp">Cycles: 4</p>
@@ -1115,12 +1264,16 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: 0</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="RR_r8"><a class="permalink" href="#RR_r8">RR r8</a></h2>
@@ -1130,17 +1283,21 @@
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="RR__HL_"><a class="permalink" href="#RR__HL_">RR
[HL]</a></h2>
-Rotate value pointed by <b class="Sy">HL</b> right through carry.
+Rotate byte pointed to by <b class="Sy">HL</b> right through carry.
<p class="Pp"></p>
<div class="Bd Bd-indent">C -> [7 -> 0] -> C</div>
<p class="Pp">Cycles: 4</p>
@@ -1155,12 +1312,16 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: 0</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="RRC_r8"><a class="permalink" href="#RRC_r8">RRC r8</a></h2>
@@ -1170,17 +1331,21 @@
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="RRC__HL_"><a class="permalink" href="#RRC__HL_">RRC
[HL]</a></h2>
-Rotate value pointed by <b class="Sy">HL</b> right.
+Rotate byte pointed to by <b class="Sy">HL</b> right.
<p class="Pp"></p>
<div class="Bd Bd-indent">[0] -> [7 -> 0] -> C</div>
<p class="Pp">Cycles: 4</p>
@@ -1195,17 +1360,23 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: 0</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="RST_vec"><a class="permalink" href="#RST_vec">RST
vec</a></h2>
-Call restart vector <var class="Ar">vec</var>.
+Call address <var class="Ar">vec</var>. This is a shorter and faster equivalent
+ to <a class="Sx" href="#CALL">CALL</a> for suitable values of
+ <var class="Ar">vec</var>.
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: None affected.</p>
@@ -1218,18 +1389,22 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 1</li>
- <li><b class="Sy">H</b>: Set if no borrow from bit 4.</li>
- <li><b class="Sy">C</b>: Set if no borrow (set if <var class="Ar">r8</var>
- > <b class="Sy">A</b>).</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>1</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if borrow from bit 4.</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set if borrow (i.e. if (<var class="Ar">r8</var> + carry) >
+ <b class="Sy">A</b>).</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="SBC_A,_HL_"><a class="permalink" href="#SBC_A,_HL_">SBC
A,[HL]</a></h2>
-Subtract the value pointed by <b class="Sy">HL</b> and the carry flag from
+Subtract the byte pointed to by <b class="Sy">HL</b> and the carry flag from
<b class="Sy">A</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
@@ -1250,16 +1425,20 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: 1</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>1</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="SET_u3,r8"><a class="permalink" href="#SET_u3,r8">SET
u3,r8</a></h2>
-Set bit <var class="Ar">u3</var> in register <var class="Ar">r8</var> to 1.
+Set bit <var class="Ar">u3</var> in register <var class="Ar">r8</var> to 1. Bit
+ 0 is the rightmost one, bit 7 the leftmost one.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags: None affected.</p>
@@ -1268,7 +1447,7 @@
<h2 class="Ss" id="SET_u3,_HL_"><a class="permalink" href="#SET_u3,_HL_">SET
u3,[HL]</a></h2>
Set bit <var class="Ar">u3</var> in the byte pointed by <b class="Sy">HL</b> to
- 1.
+ 1. Bit 0 is the rightmost one, bit 7 the leftmost one.
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags: None affected.</p>
@@ -1275,23 +1454,27 @@
</section>
<section class="Ss">
<h2 class="Ss" id="SLA_r8"><a class="permalink" href="#SLA_r8">SLA r8</a></h2>
-Shift left arithmetic register <var class="Ar">r8</var>.
+Shift Left Arithmetic register <var class="Ar">r8</var>.
<p class="Pp"></p>
<div class="Bd Bd-indent">C <- [7 <- 0] <- 0</div>
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="SLA__HL_"><a class="permalink" href="#SLA__HL_">SLA
[HL]</a></h2>
-Shift left arithmetic value pointed by <b class="Sy">HL</b>.
+Shift Left Arithmetic byte pointed to by <b class="Sy">HL</b>.
<p class="Pp"></p>
<div class="Bd Bd-indent">C <- [7 <- 0] <- 0</div>
<p class="Pp">Cycles: 4</p>
@@ -1300,23 +1483,27 @@
</section>
<section class="Ss">
<h2 class="Ss" id="SRA_r8"><a class="permalink" href="#SRA_r8">SRA r8</a></h2>
-Shift right arithmetic register <var class="Ar">r8</var>.
+Shift Right Arithmetic register <var class="Ar">r8</var>.
<p class="Pp"></p>
<div class="Bd Bd-indent">[7] -> [7 -> 0] -> C</div>
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="SRA__HL_"><a class="permalink" href="#SRA__HL_">SRA
[HL]</a></h2>
-Shift right arithmetic value pointed by <b class="Sy">HL</b>.
+Shift Right Arithmetic byte pointed to by <b class="Sy">HL</b>.
<p class="Pp"></p>
<div class="Bd Bd-indent">[7] -> [7 -> 0] -> C</div>
<p class="Pp">Cycles: 4</p>
@@ -1325,23 +1512,27 @@
</section>
<section class="Ss">
<h2 class="Ss" id="SRL_r8"><a class="permalink" href="#SRL_r8">SRL r8</a></h2>
-Shift right logic register <var class="Ar">r8</var>.
+Shift Right Logic register <var class="Ar">r8</var>.
<p class="Pp"></p>
<div class="Bd Bd-indent">0 -> [7 -> 0] -> C</div>
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: Set according to result.</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set according to result.</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="SRL__HL_"><a class="permalink" href="#SRL__HL_">SRL
[HL]</a></h2>
-Shift right logic value pointed by <b class="Sy">HL</b>.
+Shift Right Logic byte pointed to by <b class="Sy">HL</b>.
<p class="Pp"></p>
<div class="Bd Bd-indent">0 -> [7 -> 0] -> C</div>
<p class="Pp">Cycles: 4</p>
@@ -1363,18 +1554,22 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 1</li>
- <li><b class="Sy">H</b>: Set if no borrow from bit 4.</li>
- <li><b class="Sy">C</b>: Set if no borrow (set if <var class="Ar">r8</var>
- > <b class="Sy">A</b>).</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>1</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>Set if borrow from bit 4.</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>Set if borrow (set if <var class="Ar">r8</var> >
+ <b class="Sy">A</b>).</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="SUB_A,_HL_"><a class="permalink" href="#SUB_A,_HL_">SUB
A,[HL]</a></h2>
-Subtract the value pointed by <b class="Sy">HL</b> from <b class="Sy">A</b>.
+Subtract the byte pointed to by <b class="Sy">HL</b> from <b class="Sy">A</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags: See <a class="Sx" href="#SUB_A,r8">SUB A,r8</a></p>
@@ -1390,21 +1585,25 @@
<section class="Ss">
<h2 class="Ss" id="SWAP_r8"><a class="permalink" href="#SWAP_r8">SWAP
r8</a></h2>
-Swap upper 4 bits in register <var class="Ar">r8</var> and the lower ones.
+Swap upper 4 bits in register <var class="Ar">r8</var> and the lower 4 ones.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 2</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: 0</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>0</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="SWAP__HL_"><a class="permalink" href="#SWAP__HL_">SWAP
[HL]</a></h2>
-Swap upper 4 bits in the byte pointed by <b class="Sy">HL</b> and the lower
+Swap upper 4 bits in the byte pointed by <b class="Sy">HL</b> and the lower 4
ones.
<p class="Pp">Cycles: 4</p>
<p class="Pp">Bytes: 2</p>
@@ -1418,17 +1617,21 @@
<p class="Pp">Cycles: 1</p>
<p class="Pp">Bytes: 1</p>
<p class="Pp">Flags:</p>
-<ul class="Bl-bullet Bl-compact">
- <li><b class="Sy">Z</b>: Set if result is 0.</li>
- <li><b class="Sy">N</b>: 0</li>
- <li><b class="Sy">H</b>: 0</li>
- <li><b class="Sy">C</b>: 0</li>
-</ul>
+<dl class="Bl-hang Bl-compact">
+ <dt><b class="Sy">Z</b></dt>
+ <dd>Set if result is 0.</dd>
+ <dt><b class="Sy">N</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">H</b></dt>
+ <dd>0</dd>
+ <dt><b class="Sy">C</b></dt>
+ <dd>0</dd>
+</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="XOR_A,_HL_"><a class="permalink" href="#XOR_A,_HL_">XOR
A,[HL]</a></h2>
-Bitwise XOR between the value pointed by <b class="Sy">HL</b> and
+Bitwise XOR between the byte pointed to by <b class="Sy">HL</b> and
<b class="Sy">A</b>.
<p class="Pp">Cycles: 2</p>
<p class="Pp">Bytes: 1</p>
@@ -1447,7 +1650,7 @@
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
-<a class="Xr">rgbasm(1)</a>, <a class="Xr">rgbds(7)</a>
+<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgbds.7.html">rgbds(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
@@ -1460,7 +1663,7 @@
<table class="foot">
<tr>
<td class="foot-date">February 23, 2018</td>
- <td class="foot-os">RGBDS Manual</td>
+ <td class="foot-os">General</td>
</tr>
</table>
</body>
--- a/docs/rgbasm.1.html
+++ b/docs/rgbasm.1.html
@@ -8,8 +8,10 @@
SPDX-License-Identifier: MIT
-->
<head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+ <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
<title>RGBASM(1)</title>
</head>
<body>
@@ -24,7 +26,7 @@
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgbasm</code> —
-<div class="Nd">Game Boy assembler</div>
+<span class="Nd">Game Boy assembler</span>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
@@ -31,100 +33,217 @@
<table class="Nm">
<tr>
<td><code class="Nm">rgbasm</code></td>
- <td>[<code class="Fl">-EhLVvw</code>] [<code class="Fl">-b</code>
- <var class="Ar">chars</var>] [<code class="Fl">-D</code>
+ <td>[<code class="Fl"><a href="#E">-E</a><a href="#h">h</a><a href="#L">L</a><a href="#V">V</a><a href="#v">v</a><a href="#w">w</a></code>] [<code class="Fl"><a href="#b">-b</a></code>
+ <var class="Ar">chars</var>] [<code class="Fl"><a href="#D">-D</a></code>
<var class="Ar">name</var>[=<var class="Ar">value</var>]]
- [<code class="Fl">-g</code> <var class="Ar">chars</var>]
- [<code class="Fl">-i</code> <var class="Ar">path</var>]
- [<code class="Fl">-M</code> <var class="Ar">dependfile</var>]
- [<code class="Fl">-o</code> <var class="Ar">outfile</var>]
- [<code class="Fl">-p</code> <var class="Ar">pad_value</var>]
- [<code class="Fl">-r</code> <var class="Ar">recursion_depth</var>]
- <var class="Ar">file</var></td>
+ [<code class="Fl"><a href="#g">-g</a></code> <var class="Ar">chars</var>]
+ [<code class="Fl"><a href="#i">-i</a></code> <var class="Ar">path</var>]
+ [<code class="Fl"><a href="#M">-M</a></code> <var class="Ar">depend_file</var>]
+ [<code class="Fl"><a href="#o">-o</a></code> <var class="Ar">out_file</var>]
+ [<code class="Fl"><a href="#p">-p</a></code> <var class="Ar">pad_value</var>]
+ [<code class="Fl"><a href="#r">-r</a></code> <var class="Ar">recursion_depth</var>]
+ [<code class="Fl"><a href="#W">-W</a></code> <var class="Ar">warning</var>]
+ <var class="Ar">file ...</var></td>
</tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-The <code class="Nm">rgbasm</code> program creates an object file from an
+The <code class="Nm">rgbasm</code> program creates an RGB object file from an
assembly source file. The input <var class="Ar">file</var> can be a file path,
- or <code class="Cm">-</code> denoting <code class="Cm">stdin</code>. Its
- arguments are as follows:
+ or <code class="Cm">-</code> denoting <code class="Cm">stdin</code>.
+<p class="Pp">Note that options can be abbreviated as long as the abbreviation
+ is unambiguous: <code class="Fl">--verb</code> is
+ <code class="Fl">--verbose</code>, but
+ <code class="Fl">--ver</code> is invalid because it
+ could also be <code class="Fl">--version</code>. The
+ arguments are as follows:</p>
<dl class="Bl-tag">
<dt><a class="permalink" href="#b"><code class="Fl" id="b">-b</code></a>
+ <var class="Ar">chars</var>,
+ <code class="Fl">--binary-digits</code>
<var class="Ar">chars</var></dt>
<dd>Change the two characters used for binary constants. The defaults are
01.</dd>
<dt><a class="permalink" href="#D"><code class="Fl" id="D">-D</code></a>
+ <var class="Ar">name</var>[=<var class="Ar">value</var>],
+ <code class="Fl">-</code> <code class="Fl">-define</code>
<var class="Ar">name</var>[=<var class="Ar">value</var>]</dt>
- <dd>Add string symbol to the compiled source code. This is equivalent to
- <var class="Ar">name</var> <code class="Cm">EQUS</code>
- “<var class="Ar">value</var>” in code. If a value is not
- specified, a value of 1 is given.</dd>
- <dt><a class="permalink" href="#E"><code class="Fl" id="E">-E</code></a></dt>
+ <dd>Add a string symbol to the compiled source code. This is equivalent to
+ ‘<code class="Li"><var class="Ar">name</var> <code class="Ic">EQUS
+ "</code><var class="Ar">value</var>"</code>’ in code, or
+ ‘<code class="Li"><var class="Ar">name</var> <code class="Ic">EQUS
+ "1"</code></code>’ if <var class="Ar">value</var> is not
+ specified.</dd>
+ <dt><a class="permalink" href="#E"><code class="Fl" id="E">-E</code></a>,
+ <code class="Fl">--export-all</code></dt>
<dd>Export all labels, including unreferenced and local labels.</dd>
<dt><a class="permalink" href="#g"><code class="Fl" id="g">-g</code></a>
+ <var class="Ar">chars</var>,
+ <code class="Fl">--gfx-chars</code>
<var class="Ar">chars</var></dt>
- <dd>Change the four characters used for binary constants. The defaults are
- 0123.</dd>
- <dt><a class="permalink" href="#h"><code class="Fl" id="h">-h</code></a></dt>
- <dd>By default, <code class="Nm">rgbasm</code> inserts a ‘nop’
- instruction immediately after any ‘halt’ instruction. The
- <code class="Fl">-h</code> option disables this behavior.</dd>
+ <dd>Change the four characters used for gfx constants. The defaults are
+ 0123.</dd>
+ <dt><a class="permalink" href="#h"><code class="Fl" id="h">-h</code></a>,
+ <code class="Fl">--halt-without-nop</code></dt>
+ <dd>By default, <code class="Nm">rgbasm</code> inserts a
+ <code class="Ic">nop</code> instruction immediately after any
+ <code class="Ic">halt</code> instruction. The <code class="Fl">-h</code>
+ option disables this behavior.</dd>
<dt><a class="permalink" href="#i"><code class="Fl" id="i">-i</code></a>
+ <var class="Ar">path</var>,
+ <code class="Fl">--include</code>
<var class="Ar">path</var></dt>
<dd>Add an include path.</dd>
- <dt><a class="permalink" href="#L"><code class="Fl" id="L">-L</code></a></dt>
- <dd>Disable the optimization that turns loads of the form <b class="Sy">LD
- [$FF00+n8],A</b> into the opcode <b class="Sy">LDH [$FF00+n8],A</b> in
- order to have full control of the result in the final ROM.</dd>
+ <dt><a class="permalink" href="#L"><code class="Fl" id="L">-L</code></a>,
+ <code class="Fl">--preserve-ld</code></dt>
+ <dd>Disable the optimization that turns loads of the form <code class="Ic">LD
+ [$FF00+n8],A</code> into the opcode <code class="Ic">LDH
+ [$FF00+n8],A</code> in order to have full control of the result in the
+ final ROM.</dd>
<dt><a class="permalink" href="#M"><code class="Fl" id="M">-M</code></a>
- <var class="Ar">dependfile</var></dt>
+ <var class="Ar">depend_file</var>,
+ <code class="Fl">--dependfile</code>
+ <var class="Ar">depend_file</var></dt>
<dd>Print <a class="Xr">make(1)</a> dependencies to
- <var class="Ar">dependfile</var>.</dd>
+ <var class="Ar">depend_file</var>.</dd>
<dt><a class="permalink" href="#o"><code class="Fl" id="o">-o</code></a>
- <var class="Ar">outfile</var></dt>
+ <var class="Ar">out_file</var>,
+ <code class="Fl">--output</code>
+ <var class="Ar">out_file</var></dt>
<dd>Write an object file to the given filename.</dd>
<dt><a class="permalink" href="#p"><code class="Fl" id="p">-p</code></a>
+ <var class="Ar">pad_value</var>,
+ <code class="Fl">--pad-value</code>
<var class="Ar">pad_value</var></dt>
<dd>When padding an image, pad with this value. The default is 0x00.</dd>
<dt><a class="permalink" href="#r"><code class="Fl" id="r">-r</code></a>
+ <var class="Ar">recursion_depth</var>,
+ <code class="Fl">--recursion-depth</code>
<var class="Ar">recursion_depth</var></dt>
<dd>Specifies the recursion depth at which RGBASM will assume being in an
infinite loop.</dd>
- <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a></dt>
+ <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a>,
+ <code class="Fl">--version</code></dt>
<dd>Print the version of the program and exit.</dd>
- <dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a></dt>
+ <dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a>,
+ <code class="Fl">--verbose</code></dt>
<dd>Be verbose.</dd>
+ <dt><a class="permalink" href="#W"><code class="Fl" id="W">-W</code></a>
+ <var class="Ar">warning</var>,
+ <code class="Fl">--warning</code>
+ <var class="Ar">warning</var></dt>
+ <dd>Set warning flag <var class="Ar">warning</var>. A warning message will be
+ printed if <var class="Ar">warning</var> is an unknown warning flag. See
+ the <a class="Sx" href="#DIAGNOSTICS">DIAGNOSTICS</a> section for a list
+ of warnings.</dd>
<dt><a class="permalink" href="#w"><code class="Fl" id="w">-w</code></a></dt>
- <dd>Disable warning output.</dd>
+ <dd>Disable all warning output, even when turned into errors.</dd>
</dl>
</section>
<section class="Sh">
+<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1>
+Warnings are diagnostic messages that indicate possibly erroneous behavior that
+ does not necessarily compromise the assembling process. The following options
+ alter the way warnings are processed.
+<dl class="Bl-tag">
+ <dt><a class="permalink" href="#Werror"><code class="Fl" id="Werror">-Werror</code></a></dt>
+ <dd>Make all warnings into errors.</dd>
+ <dt><a class="permalink" href="#Werror="><code class="Fl" id="Werror=">-Werror=</code></a></dt>
+ <dd>Make the specified warning into an error. A warning's name is appended
+ (example: <code class="Fl">-Werror=obsolete</code>), and this warning is
+ implicitly enabled and turned into an error. This is an error if used with
+ a meta warning, such as <code class="Fl">-Werror=all</code>.</dd>
+</dl>
+<p class="Pp">The following warnings are “meta” warnings, that
+ enable a collection of other warnings. If a specific warning is toggled via
+ a meta flag and a specific one, the more specific one takes priority. The
+ position on the command-line acts as a tie breaker, the last one taking
+ effect.</p>
+<dl class="Bl-tag">
+ <dt><a class="permalink" href="#Wall"><code class="Fl" id="Wall">-Wall</code></a></dt>
+ <dd>This enables warnings that are likely to indicate an error or undesired
+ behavior, and that can easily be fixed.</dd>
+ <dt><a class="permalink" href="#Wextra"><code class="Fl" id="Wextra">-Wextra</code></a></dt>
+ <dd>This enables extra warnings that are less likely to pose a problem, but
+ that may still be wanted.</dd>
+ <dt><a class="permalink" href="#Weverything"><code class="Fl" id="Weverything">-Weverything</code></a></dt>
+ <dd>Enables literally every warning.</dd>
+</dl>
+<p class="Pp">The following warnings are actual warning flags; with each
+ description, the corresponding warning flag is included. Note that each of
+ these flag also has a negation (for example,
+ <code class="Fl">-Wempty-entry</code> enables the warning that
+ <code class="Fl">-Wno-empty-entry</code> disables). Only the non-default
+ flag is listed here. Ignoring the “no-” prefix, entries are
+ listed alphabetically.</p>
+<dl class="Bl-tag">
+ <dt><a class="permalink" href="#Wno-assert"><code class="Fl" id="Wno-assert">-Wno-assert</code></a></dt>
+ <dd>Warns when <code class="Ic">WARN</code><span class="No">-type</span>
+ assertions fail. (See “Aborting the assembly process” in
+ <a class="Xr" href="rgbasm.5.html">rgbasm(5)</a> for <code class="Ic">ASSERT</code>).</dd>
+ <dt><a class="permalink" href="#Wbuiltin-args"><code class="Fl" id="Wbuiltin-args">-Wbuiltin-args</code></a></dt>
+ <dd>Warn about incorrect arguments to built-in functions, such as
+ <code class="Fn">STRSUB</code>() with indexes outside of the string's
+ bounds. This warning is enabled by <code class="Fl">-Wall</code>.</dd>
+ <dt><a class="permalink" href="#Wdiv"><code class="Fl" id="Wdiv">-Wdiv</code></a></dt>
+ <dd>Warn when dividing the smallest negative integer by -1, which yields
+ itself due to integer overflow.</dd>
+ <dt><a class="permalink" href="#Wempty-entry"><code class="Fl" id="Wempty-entry">-Wempty-entry</code></a></dt>
+ <dd>Warn when an empty entry is encountered in a <code class="Ic">db</code>,
+ <code class="Ic">dw</code>, <code class="Ic">dl</code> list. This warning
+ is enabled by <code class="Fl">-Wextra</code>.</dd>
+ <dt><a class="permalink" href="#Wlarge-constant"><code class="Fl" id="Wlarge-constant">-Wlarge-constant</code></a></dt>
+ <dd>Warn when a constant too large to fit in a signed 32-bit integer is
+ encountered. This warning is enabled by
+ <code class="Fl">-Wall</code>.</dd>
+ <dt><a class="permalink" href="#Wlong-string"><code class="Fl" id="Wlong-string">-Wlong-string</code></a></dt>
+ <dd>Warn when a string too long to fit in internal buffers is encountered.
+ This warning is enabled by <code class="Fl">-Wall</code>.</dd>
+ <dt><a class="permalink" href="#Wobsolete"><code class="Fl" id="Wobsolete">-Wobsolete</code></a></dt>
+ <dd>Warn when obsolete constructs such as the <code class="Ic">jp [hl]</code>
+ instruction or <code class="Ic">HOME</code> section type are encountered.
+ This warning is enabled by <code class="Fl">-Wextra</code>.</dd>
+ <dt><a class="permalink" href="#Wshift"><code class="Fl" id="Wshift">-Wshift</code></a></dt>
+ <dd>Warn when shifting right a negative value. Use a division by 2^N
+ instead.</dd>
+ <dt><a class="permalink" href="#Wshift-amount"><code class="Fl" id="Wshift-amount">-Wshift-amount</code></a></dt>
+ <dd>Warn when a shift's operand is negative or greater than 32.</dd>
+ <dt><a class="permalink" href="#Wno-truncation"><code class="Fl" id="Wno-truncation">-Wno-truncation</code></a></dt>
+ <dd>Warn when an implicit truncation (for example, <code class="Ic">db</code>)
+ loses some bits.</dd>
+ <dt><a class="permalink" href="#Wno-user"><code class="Fl" id="Wno-user">-Wno-user</code></a></dt>
+ <dd>Warn when the <code class="Ic">WARN</code> built-in is executed. (See
+ “Aborting the assembly process” in
+ <a class="Xr" href="rgbasm.5.html">rgbasm(5)</a> for <code class="Ic">WARN</code>).</dd>
+</dl>
+</section>
+<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
-You can assemble a source file in two ways. Straight forward way:
-<div class="Bd Pp Bd-indent">
-<pre>
-$ rgbasm -o bar.o foo.asm
-</pre>
-</div>
+You can assemble a source file in two ways.
+<p class="Pp">Straightforward way:</p>
+<div class="Bd Bd-indent"><code class="Li">$ rgbasm -o bar.o
+ foo.asm</code></div>
<p class="Pp">Pipes way:</p>
-<div class="Bd Pp Bd-indent">
-<pre>
-$ cat foo.asm | rgbasm -o bar.o -
-$ rgbasm -o bar.o - < foo.asm
-</pre>
-</div>
-<p class="Pp">The resulting object file is not yet a usable ROM image —
- it must first be run through <a class="Xr">rgblink(1)</a> and
- <a class="Xr">rgbfix(1)</a>.</p>
+<div class="Bd Bd-indent"><code class="Li">$ cat foo.asm | rgbasm -o bar.o
+ -</code></div>
+<div class="Bd Bd-indent"><code class="Li">$ rgbasm -o bar.o - <
+ foo.asm</code></div>
+<p class="Pp">The resulting object file is not yet a usable ROM image—it
+ must first be run through <a class="Xr" href="rgblink.1.html">rgblink(1)</a> and then
+ <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>.</p>
</section>
<section class="Sh">
+<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
+Please report bugs on
+ <a class="Lk" href="https://github.com/rednex/rgbds/issues">GitHub</a>.
+</section>
+<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
-<a class="Xr">rgbasm(5)</a>, <a class="Xr">rgbfix(1)</a>,
- <a class="Xr">rgblink(1)</a>, <a class="Xr">rgbds(5)</a>,
- <a class="Xr">rgbds(7)</a>, <a class="Xr">gbz80(7)</a>
+<a class="Xr" href="rgbasm.5.html">rgbasm(5)</a>, <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>,
+ <a class="Xr" href="rgblink.1.html">rgblink(1)</a>, <a class="Xr" href="rgbds.5.html">rgbds(5)</a>,
+ <a class="Xr" href="rgbds.7.html">rgbds(7)</a>, <a class="Xr" href="gbz80.7.html">gbz80(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
@@ -137,7 +256,7 @@
<table class="foot">
<tr>
<td class="foot-date">July 8, 2019</td>
- <td class="foot-os">RGBDS Manual</td>
+ <td class="foot-os">General</td>
</tr>
</table>
</body>
--- a/docs/rgbasm.5.html
+++ b/docs/rgbasm.5.html
@@ -8,8 +8,10 @@
SPDX-License-Identifier: MIT
-->
<head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+ <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
<title>RGBASM(5)</title>
</head>
<body>
@@ -24,24 +26,30 @@
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgbasm</code> —
-<div class="Nd">language documentation</div>
+<span class="Nd">language documentation</span>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
This is the full description of the language used by
- <a class="Xr">rgbasm(1)</a>. The description of the instructions supported by
- the GameBoy CPU is in <a class="Xr">gbz80(7)</a>.
+ <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>. The description of the instructions supported by
+ the Game Boy CPU is in <a class="Xr" href="gbz80.7.html">gbz80(7)</a>.
+<p class="Pp">It is strongly recommended to have some familiarity with the Game
+ Boy hardware before reading this document. RGBDS is specifically targeted at
+ the Game Boy, and thus a lot of its features tie directly to its concepts.
+ This document is not intended to be a Game Boy hardware reference.</p>
+<p class="Pp">Generally, “the linker” will refer to
+ <a class="Xr" href="rgblink.1.html">rgblink(1)</a>, but any program that processes RGB object
+ files (described in <a class="Xr" href="rgbds.5.html">rgbds(5)</a>) can be used in its
+ place.</p>
</section>
<section class="Sh">
-<h1 class="Sh" id="GENERAL"><a class="permalink" href="#GENERAL">GENERAL</a></h1>
-<section class="Ss">
-<h2 class="Ss" id="Syntax"><a class="permalink" href="#Syntax">Syntax</a></h2>
+<h1 class="Sh" id="SYNTAX"><a class="permalink" href="#SYNTAX">SYNTAX</a></h1>
The syntax is line‐based, just as in any other assembler, meaning that
you do one instruction or pseudo‐op per line:
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">[<var class="Ar">label</var>]
[<var class="Ar">instruction</var>]
- [<var class="Ar">;comment</var>]</code></div>
+ [<var class="Ar">; comment</var>]</code></div>
<p class="Pp">Example:</p>
<div class="Bd Pp Bd-indent">
<pre>
@@ -48,21 +56,26 @@
John: ld a,87 ;Weee
</pre>
</div>
-<p class="Pp">All pseudo‐ops, mnemonics and registers (reserved keywords)
- are case‐insensitive and all labels are case‐sensitive.</p>
-<p class="Pp">There are two syntaxes for comments. In both cases, a comment ends
- at the end of the line. The most common one is: anything that follows a
- semicolon ‘<code class="Li">;</code>’ (that isn't inside a
- string) is a comment. There is another format: anything that follows a
- ‘<code class="Li">*</code>’ that is placed right at the start
- of a line is a comment. The assembler removes all comments from the code
- before doing anything else.</p>
+<p class="Pp">All reserved keywords (pseudo‐ops, mnemonics, registers
+ etc.) are case‐insensitive, all identifiers (symbol names) are
+ case-sensitive.</p>
+<p class="Pp">Comments are used to give humans information about the code, such
+ as explanations. The assembler <i class="Em">always</i> ignores comments and
+ their contents.</p>
+<p class="Pp">There are two syntaxes for comments. The most common is that
+ anything that follows a semicolon ‘<code class="Li">;</code>’
+ not inside a string, is a comment until the end of the line. The other is
+ that lines beginning with a ‘<code class="Li">*</code>’ (not
+ even spaces before it) are ignored. This second syntax is deprecated (will
+ be removed in a future version) and should be replaced with the first
+ one.</p>
<p class="Pp">Sometimes lines can be too long and it may be necessary to split
- them. The syntax to do so is the following one:</p>
+ them. To do so, put a backslash at the end of the line:</p>
<div class="Bd Pp Bd-indent">
<pre>
- DB 1, 2, 3, 4 \
- 5, 6, 7, 8
+ DB 1, 2, 3, \
+ 4, 5, 6, \ ; Put it before any comments
+ 7, 8, 9
</pre>
</div>
<p class="Pp">This works anywhere in the code except inside of strings. To split
@@ -69,269 +82,886 @@
strings it is needed to use <code class="Fn">STRCAT</code>() like this:</p>
<div class="Bd Pp Bd-indent">
<pre>
- DB STRCAT("Hello ", \
+ db STRCAT("Hello ", \
"world!")
</pre>
</div>
</section>
+<section class="Sh">
+<h1 class="Sh" id="EXPRESSIONS"><a class="permalink" href="#EXPRESSIONS">EXPRESSIONS</a></h1>
+An expression can be composed of many things. Numerical expressions are always
+ evaluated using signed 32-bit math. Zero is considered to be the only
+ "false" number, all non-zero numbers (including negative) are
+ "true".
+<p class="Pp">An expression is said to be "constant" if
+ <code class="Nm">rgbasm</code> knows its value. This is generally always the
+ case, unless a label is involved, as explained in the
+ <a class="Sx" href="#SYMBOLS">SYMBOLS</a> section.</p>
+<p class="Pp">The instructions in the macro-language generally require constant
+ expressions.</p>
<section class="Ss">
-<h2 class="Ss" id="Sections"><a class="permalink" href="#Sections">Sections</a></h2>
-<code class="Ic">SECTION</code> <var class="Ar">name</var>,
- <var class="Ar">type</var>
-<p class="Pp"><code class="Ic">SECTION</code> <var class="Ar">name</var>,
- <var class="Ar">type</var>, <var class="Ar">options</var></p>
-<p class="Pp"><code class="Ic">SECTION</code> <var class="Ar">name</var>,
- <var class="Ar">type</var>[<var class="Ar">addr</var>]</p>
-<p class="Pp"><code class="Ic">SECTION</code> <var class="Ar">name</var>,
- <var class="Ar">type</var>[<var class="Ar">addr</var>],
- <var class="Ar">options</var></p>
-<p class="Pp">Before you can start writing code, you must define a section. This
- tells the assembler what kind of information follows and, if it is code,
- where to put it.</p>
-<p class="Pp"><var class="Ar">name</var> is a string enclosed in double quotes
+<h2 class="Ss" id="Numeric_Formats"><a class="permalink" href="#Numeric_Formats">Numeric
+ Formats</a></h2>
+There are a number of numeric formats.
+<table class="Bl-column Bd-indent">
+ <tr>
+ <th>Format type</th>
+ <th>Prefix</th>
+ <th>Accepted characters</th>
+ </tr>
+ <tr>
+ <td>Hexadecimal</td>
+ <td>$</td>
+ <td>0123456789ABCDEF</td>
+ </tr>
+ <tr>
+ <td>Decimal</td>
+ <td>none</td>
+ <td>0123456789</td>
+ </tr>
+ <tr>
+ <td>Octal</td>
+ <td>&</td>
+ <td>01234567</td>
+ </tr>
+ <tr>
+ <td>Binary</td>
+ <td>%</td>
+ <td>01</td>
+ </tr>
+ <tr>
+ <td>Fixed point (16.16)</td>
+ <td>none</td>
+ <td>01234.56789</td>
+ </tr>
+ <tr>
+ <td>Character constant</td>
+ <td>none</td>
+ <td>"ABYZ"</td>
+ </tr>
+ <tr>
+ <td>Gameboy graphics</td>
+ <td>`</td>
+ <td>0123</td>
+ </tr>
+</table>
+<p class="Pp">The "character constant" form yields the value the
+ character maps to in the current charmap. For example, by default (refer to
+ <a class="Xr">ascii(7)</a>) ‘"A"’ yields 65. See
+ <a class="Sx" href="#Character_maps">Character maps</a> for information on
+ charmaps.</p>
+<p class="Pp">The last one, Gameboy graphics, is quite interesting and useful.
+ After the backtick, 8 digits between 0 and 3 are expected, corresponding to
+ pixel values. The resulting value is the two bytes of tile data that would
+ produce that row of pixels. For example, ‘`01012323’ is
+ equivalent to ‘$0F55’.</p>
+<p class="Pp">You can also use symbols, which are implicitly replaced with their
+ value.</p>
+</section>
+<section class="Ss">
+<h2 class="Ss" id="Operators"><a class="permalink" href="#Operators">Operators</a></h2>
+A great number of operators you can use in expressions are available (listed
+ from highest to lowest precedence):
+<table class="Bl-column Bd-indent">
+ <tr>
+ <th>Operator</th>
+ <th>Meaning</th>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#(__&)"><code class="Li" id="(__&)">(
+ )</code></a></td>
+ <td>Precedence override</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#FUNC()"><code class="Li" id="FUNC()">FUNC()</code></a></td>
+ <td>Built-in function call</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#~_+_-"><code class="Li" id="~_+_-">~ +
+ -</code></a></td>
+ <td>Unary complement/plus/minus</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#*_/__"><code class="Li" id="*_/__">* /
+ %</code></a></td>
+ <td>Multiply/divide/modulo</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#_____"><code class="Li" id="_____"><<
+ >></code></a></td>
+ <td>Shift left/right</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#&__&___"><code class="Li" id="&__&___">&
+ | ^</code></a></td>
+ <td>Binary and/or/xor</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#+_-"><code class="Li" id="+_-">+
+ -</code></a></td>
+ <td>Add/subtract</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#!=_==__=__=____"><code class="Li" id="!=_==__=__=____">!=
+ == <= >= < ></code></a></td>
+ <td>Comparison</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#&&___"><code class="Li" id="&&___">&&
+ ||</code></a></td>
+ <td>Boolean and/or</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#!"><code class="Li" id="!">!</code></a></td>
+ <td>Unary not</td>
+ </tr>
+</table>
+<p class="Pp"><code class="Ic">~</code> complements a value by inverting all its
+ bits.</p>
+<p class="Pp"><code class="Ic">%</code> is used to get the remainder of the
+ corresponding division. ‘5 % 2’ is 1.</p>
+<p class="Pp">Shifting works by shifting all bits in the left operand either
+ left (‘<<’) or right (‘>>’) by the
+ right operand's amount. When shifting left, all newly-inserted bits are
+ reset; when shifting right, they are copies of the original most significant
+ bit instead. This makes ‘a << b’ and ‘a >>
+ b’ equivalent to multiplying and dividing by 2 to the power of b,
+ respectively.</p>
+<p class="Pp">Comparison operators return 0 if the comparison is false, and 1
+ otherwise.</p>
+<p class="Pp">Unlike in a lot of languages, and for technical reasons,
+ <code class="Nm">rgbasm</code> still evaluates both operands of
+ ‘&&’ and ‘||’.</p>
+<p class="Pp">! returns 1 if the operand was 0, and 1 otherwise.</p>
+</section>
+<section class="Ss">
+<h2 class="Ss" id="Fixed__u2010_point_Expressions"><a class="permalink" href="#Fixed__u2010_point_Expressions">Fixed‐point
+ Expressions</a></h2>
+Fixed-point numbers are basically normal (32-bit) integers, which count
+ 65536th's instead of entire units, offering better precision than integers but
+ limiting the range of values. The upper 16 bits are used for the integer part
+ and the lower 16 bits are used for the fraction (65536ths). Since they are
+ still akin to integers, you can use them in normal integer expressions, and
+ some integer operators like ‘+’ and ‘-’ don't care
+ whether the operands are integers or fixed-point. You can easily truncate a
+ fixed-point number into an integer by shifting it right by 16 bits. It follows
+ that you can convert an integer to a fixed-point number by shifting it left.
+<p class="Pp">The following functions are designed to operate with fixed-point
+ numbers:</p>
+<table class="Bl-column Bd-indent">
+ <tr>
+ <th>Name</th>
+ <th>Operation</th>
+ </tr>
+ <tr>
+ <td><code class="Fn">DIV</code>(<var class="Fa">x</var>,
+ <var class="Fa">y</var>)</td>
+ <td>
+ <math class="eqn">
+ <mrow><mi>x</mi><mo>÷</mo><mi>y</mi></mrow>
+ </math>
+ </td>
+ </tr>
+ <tr>
+ <td><code class="Fn">MUL</code>(<var class="Fa">x</var>,
+ <var class="Fa">y</var>)</td>
+ <td>
+ <math class="eqn">
+ <mrow><mi>x</mi><mo>×</mo><mi>y</mi></mrow>
+ </math>
+ </td>
+ </tr>
+ <tr>
+ <td><code class="Fn">SIN</code>(<var class="Fa">x</var>)</td>
+ <td>
+ <math class="eqn">
+ <mrow><mi>sin</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
+ </math>
+ </td>
+ </tr>
+ <tr>
+ <td><code class="Fn">COS</code>(<var class="Fa">x</var>)</td>
+ <td>
+ <math class="eqn">
+ <mrow><mi>cos</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
+ </math>
+ </td>
+ </tr>
+ <tr>
+ <td><code class="Fn">TAN</code>(<var class="Fa">x</var>)</td>
+ <td>
+ <math class="eqn">
+ <mrow><mi>tan</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
+ </math>
+ </td>
+ </tr>
+ <tr>
+ <td><code class="Fn">ASIN</code>(<var class="Fa">x</var>)</td>
+ <td>
+ <math class="eqn">
+ <mrow><mi>asin</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
+ </math>
+ </td>
+ </tr>
+ <tr>
+ <td><code class="Fn">ACOS</code>(<var class="Fa">x</var>)</td>
+ <td>
+ <math class="eqn">
+ <mrow><mi>acos</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
+ </math>
+ </td>
+ </tr>
+ <tr>
+ <td><code class="Fn">ATAN</code>(<var class="Fa">x</var>)</td>
+ <td>
+ <math class="eqn">
+ <mrow><mi>atan</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
+ </math>
+ </td>
+ </tr>
+ <tr>
+ <td><code class="Fn">ATAN2</code>(<var class="Fa">x</var>,
+ <var class="Fa">y</var>)</td>
+ <td>Angle between
+ <math class="eqn">
+ <mrow><mo>(</mo><mi>x</mi><mo>,</mo><mi>y</mi><mo>)</mo></mrow>
+ </math>
+ and
+ <math class="eqn">
+ <mrow><mo>(</mo><mn>1</mn><mo>,</mo><mn>0</mn><mo>)</mo></mrow>
+ </math>
+ </td>
+ </tr>
+</table>
+<p class="Pp">These functions are useful for automatic generation of various
+ tables. Example: assuming a circle has 65536.0 degrees, and sine values are
+ in range [-1.0 ; 1.0]:</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+; --
+; -- Generate a 256-byte sine table with values between 0 and 128
+; --
+ANGLE = 0.0
+ REPT 256
+ db MUL(64.0, SIN(ANGLE) + 1.0) >> 16
+ANGLE = ANGLE + 256.0 ; 256 = 65536 / table_len, with table_len = 256
+ ENDR
+</pre>
+</div>
+</section>
+<section class="Ss">
+<h2 class="Ss" id="String_Expressions"><a class="permalink" href="#String_Expressions">String
+ Expressions</a></h2>
+The most basic string expression is any number of characters contained in double
+ quotes (‘<code class="Li">"for instance"</code>’). The
+ backslash character ‘<code class="Li">\</code>’ is special in
+ that it causes the character following it to be “escaped”,
+ meaning that it is treated differently from normal. There are a number of
+ escape sequences you can use within a string:
+<table class="Bl-column Bd-indent">
+ <tr>
+ <th>String</th>
+ <th>Meaning</th>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">\\</code>’</td>
+ <td>Produces a backslash</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">\"</code>’</td>
+ <td>Produces a double quote without terminating</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">\,</code>’</td>
+ <td>Comma</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">\{</code>’</td>+ <td>Curly bracket left</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">\}</code>’</td>
+ <td>Curly bracket right</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">\n</code>’</td>
+ <td>Newline ($0A)</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">\r</code>’</td>
+ <td>Carriage return ($0D)</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">\t</code>’</td>
+ <td>Tab ($09)</td>
+ </tr>
+ <tr>
+ <td>“\1” – “\9”</td>
+ <td>Macro argument (Only the body of a macro, see
+ <a class="Sx" href="#Invoking_macros">Invoking macros</a>)</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">\@</code>’</td>
+ <td>Label name suffix (Only in the body of macros and REPTs)</td>
+ </tr>
+</table>
+(Note that some of those can be used outside of strings, when noted further in
+ this document.)
+<p class="Pp">A funky feature is
+ ‘<code class="Li">{symbol}</code>’ within a string, called+ “symbol interpolation”. This will paste
+ <var class="Ar">symbol</var>'s contents as a string. If it's a string
+ symbol, the string is simply inserted. If it's a numeric symbol, its value
+ is converted to hexadecimal notation with a dollar sign ‘$’
+ prepended.</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+TOPIC equs "life, the universe, and everything"
+ANSWER = 42
+; Prints "The answer to life, the universe, and everything is $2A"
+PRINTT "The answer to {TOPIC} is {ANSWER}\n"+</pre>
+</div>
+<p class="Pp">Symbol interpolations can be nested, too!</p>
+<p class="Pp">It's possible to change the way numeric symbols are converted by
+ specifying a print type like so:
+ ‘<code class="Li">{d:symbol}</code>’. Valid print types+ are:</p>
+<table class="Bl-column Bd-indent">
+ <tr>
+ <th>Print type</th>
+ <th>Format</th>
+ <th>Example</th>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">d</code>’</td>
+ <td>Decimal</td>
+ <td>42</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">x</code>’</td>
+ <td>Lowercase hexadecimal</td>
+ <td>2a</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">X</code>’</td>
+ <td>Uppercase hexadecimal</td>
+ <td>2A</td>
+ </tr>
+ <tr>
+ <td>‘<code class="Li">b</code>’</td>
+ <td>Binary</td>
+ <td>101010</td>
+ </tr>
+</table>
+<p class="Pp">Note that print types should only be used with numeric values, not
+ strings.</p>
+<p class="Pp">HINT: The <code class="Ic">{symbol}</code> construct can also be+ used outside strings. The symbol's value is again inserted directly.</p>
+<p class="Pp">The following functions operate on string expressions. Most of
+ them return a string, however some of these functions actually return an
+ integer and can be used as part of an integer expression!</p>
+<table class="Bl-column">
+ <tr>
+ <th>Name</th>
+ <th>Operation</th>
+ </tr>
+ <tr>
+ <td><code class="Fn">STRLEN</code>(<var class="Fa">string</var>)</td>
+ <td>Returns the number of characters in <var class="Ar">string</var>.</td>
+ </tr>
+ <tr>
+ <td><code class="Fn">STRCAT</code>(<var class="Fa">str1</var>,
+ <var class="Fa">str2</var>)</td>
+ <td>Appends <var class="Ar">str2</var> <span class="No">to</span>
+ <var class="Ar">str1</var>.</td>
+ </tr>
+ <tr>
+ <td><code class="Fn">STRCMP</code>(<var class="Fa">str1</var>,
+ <var class="Fa">str2</var>)</td>
+ <td>Returns negative if <var class="Ar">str1</var> <span class="No">is
+ alphabetically lower than</span> <var class="Ar">str2</var> ,
+ <span class="No">zero if they match, positive if</span>
+ <var class="Ar">str1</var> <span class="No">is greater than</span>
+ <var class="Ar">str2</var>.</td>
+ </tr>
+ <tr>
+ <td><code class="Fn">STRIN</code>(<var class="Fa">str1</var>,
+ <var class="Fa">str2</var>)</td>
+ <td>Returns the position of <var class="Ar">str2</var>
+ <span class="No">in</span> <var class="Ar">str1</var> <span class="No">or
+ zero if it's not present</span> (first character is position 1).</td>
+ </tr>
+ <tr>
+ <td><code class="Fn">STRSUB</code>(<var class="Fa">str</var>,
+ <var class="Fa">pos</var>, <var class="Fa">len</var>)</td>
+ <td>Returns a substring from <var class="Ar">str</var>
+ <span class="No">starting at</span> <var class="Ar">pos</var> (first
+ character is position 1) and <var class="Ar">len</var>
+ <span class="No">characters long.</span></td>
+ </tr>
+ <tr>
+ <td><code class="Fn">STRUPR</code>(<var class="Fa">str</var>)</td>
+ <td>Converts all characters in <var class="Ar">str</var> <span class="No">to
+ capitals and returns the new string.</span></td>
+ </tr>
+ <tr>
+ <td><code class="Fn">STRLWR</code>(<var class="Fa">str</var>)</td>
+ <td>Converts all characters in <var class="Ar">str</var> <span class="No">to
+ lower case and returns the new string.</span></td>
+ </tr>
+</table>
+</section>
+<section class="Ss">
+<h2 class="Ss" id="Character_maps"><a class="permalink" href="#Character_maps">Character
+ maps</a></h2>
+When writing text that is meant to be displayed in the Game Boy, the characters
+ used in the source code may have a different encoding than the default of
+ ASCII. For example, the tiles used for uppercase letters may be placed
+ starting at tile index 128, which makes it difficult to add text strings to
+ the ROM.
+<p class="Pp">Character maps allow mapping strings up to 16 characters long to
+ an abitrary 8-bit value:</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+CHARMAP "<LF>", 10
+CHARMAP "&iacute", 20
+CHARMAP "A", 128
+</pre>
+</div>
+By default, a character map contains ASCII encoding.
+<p class="Pp">It is possible to create multiple character maps and then switch
+ between them as desired. This can be used to encode debug information in
+ ASCII and use a different encoding for other purposes, for example.
+ Initially, there is one character map called ‘main’ and it is
+ automatically selected as the current character map from the beginning.
+ There is also a character map stack that can be used to save and restore
+ which character map is currently active.</p>
+<table class="Bl-column">
+ <tr>
+ <th>Command</th>
+ <th>Meaning</th>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#NEWCHARMAP"><code class="Ic" id="NEWCHARMAP">NEWCHARMAP</code></a>
+ <var class="Ar">name</var></td>
+ <td>Creates a new, empty character map called
+ <var class="Ar">name</var>.</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#NEWCHARMAP_2"><code class="Ic" id="NEWCHARMAP_2">NEWCHARMAP</code></a>
+ <var class="Ar">name</var>, <var class="Ar">basename</var></td>
+ <td>Creates a new character map called <var class="Ar">name</var>,
+ <span class="No">copied from character map</span>
+ <var class="Ar">basename</var>.</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#SETCHARMAP"><code class="Ic" id="SETCHARMAP">SETCHARMAP</code></a>
+ <var class="Ar">name</var></td>
+ <td>Switch to character map <var class="Ar">name</var>.</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#PUSHC"><code class="Ic" id="PUSHC">PUSHC</code></a></td>
+ <td>Push the current character map onto the stack.</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#POPC"><code class="Ic" id="POPC">POPC</code></a></td>
+ <td>Pop a character map off the stack and switch to it.</td>
+ </tr>
+</table>
+<p class="Pp"><b class="Sy">Note:</b> Character maps affect all strings in the
+ file from the point in which they are defined, until switching to a
+ different character map. This means that any string that the code may want
+ to print as debug information will also be affected by it.</p>
+<p class="Pp"><b class="Sy">Note:</b> The output value of a mapping can be 0. If
+ this happens, the assembler will treat this as the end of the string and the
+ rest of it will be trimmed.</p>
+</section>
+<section class="Ss">
+<h2 class="Ss" id="Other_functions"><a class="permalink" href="#Other_functions">Other
+ functions</a></h2>
+There are a few other functions that do various useful things:
+<table class="Bl-column">
+ <tr>
+ <th>Name</th>
+ <th>Operation</th>
+ </tr>
+ <tr>
+ <td><code class="Fn">BANK</code>(<var class="Fa">arg</var>)</td>
+ <td>Returns a bank number. If <var class="Ar">arg</var> is the symbol
+ <code class="Ic">@</code>, this function returns the bank of the current
+ section. If <var class="Ar">arg</var> is a string, it returns the bank of
+ the section that has that name. If <var class="Ar">arg</var> is a label,
+ it returns the bank number the label is in. The result may be constant if
+ <code class="Nm">rgbasm</code> is able to compute it.</td>
+ </tr>
+ <tr>
+ <td><code class="Fn">DEF</code>(<var class="Fa">label</var>)</td>
+ <td>Returns TRUE (1) if <var class="Ar">label</var> has been defined, FALSE
+ (0) otherwise. String symbols are not expanded within the
+ parentheses.</td>
+ </tr>
+ <tr>
+ <td><code class="Fn">HIGH</code>(<var class="Fa">arg</var>)</td>
+ <td>Returns the top 8 bits of the operand if <var class="Ar">arg</var>
+ <span class="No">is a label or constant, or the top 8-bit register if it
+ is a 16-bit register.</span></td>
+ </tr>
+ <tr>
+ <td><code class="Fn">LOW</code>(<var class="Fa">arg</var>)</td>
+ <td>Returns the bottom 8 bits of the operand if <var class="Ar">arg</var>
+ <span class="No">is a label or constant, or the bottom 8-bit register if
+ it is a 16-bit register</span> (<code class="Cm">AF</code>
+ <span class="No">isn't a valid register for this function</span>).</td>
+ </tr>
+ <tr>
+ <td><code class="Fn">ISCONST</code>(<var class="Fa">arg</var>)</td>
+ <td>Returns 1 if <var class="Ar">arg</var>'s value is known by RGBASM (e.g.
+ if it can be an argument to <code class="Ic">IF</code>), or 0 if only
+ RGBLINK can compute its value.</td>
+ </tr>
+</table>
+</section>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="SECTIONS"><a class="permalink" href="#SECTIONS">SECTIONS</a></h1>
+Before you can start writing code, you must define a section. This tells the
+ assembler what kind of information follows and, if it is code, where to put
+ it.
+<p class="Pp"></p>
+<div class="Bd Bd-indent"><code class="Li">SECTION <var class="Ar">name</var>,
+ <var class="Ar">type</var></code></div>
+<div class="Bd Bd-indent"><code class="Li">SECTION <var class="Ar">name</var>,
+ <var class="Ar">type</var>, <var class="Ar">options</var></code></div>
+<div class="Bd Bd-indent"><code class="Li">SECTION <var class="Ar">name</var>,
+ <var class="Ar">type</var>[<var class="Ar">addr</var>]</code></div>
+<div class="Bd Bd-indent"><code class="Li">SECTION <var class="Ar">name</var>,
+ <var class="Ar">type</var>[<var class="Ar">addr</var>],
+ <var class="Ar">options</var></code></div>
+<p class="Pp"><var class="Ar">name</var> is a string enclosed in double quotes,
and can be a new name or the name of an existing section. All sections
- assembled at the same time that have the same name and type are considered
- to be the same section, and their code is put together in the object file
- generated by the assembler. All other sections must have a unique name, even
- in different source files, or the linker will treat it as an error.</p>
+ assembled at the same time that have the same name are considered to be the
+ same section, and their code is put together in the object file generated by
+ the assembler. If the type doesn't match, an error occurs. All other
+ sections must have a unique name, even in different source files, or the
+ linker will treat it as an error.</p>
<p class="Pp">Possible section <var class="Ar">type</var>s are as follows:</p>
<dl class="Bl-tag">
- <dt><a class="permalink" href="#ROM0"><code class="Cm" id="ROM0">ROM0</code></a></dt>
+ <dt><a class="permalink" href="#ROM0"><code class="Ic" id="ROM0">ROM0</code></a></dt>
<dd>A ROM section. <var class="Ar">addr</var> can range from
- $0000–$3FFF (or $0000–$7FFF if tiny ROM mode is enabled in
- <a class="Xr">rgblink(1)</a>).</dd>
- <dt><a class="permalink" href="#ROMX"><code class="Cm" id="ROMX">ROMX</code></a></dt>
+ <span class="Ad">$0000</span> to <span class="Ad">$3FFF</span>, or
+ <span class="Ad">$0000</span> to <span class="Ad">$7FFF</span> if tiny ROM
+ mode is enabled in the linker.</dd>
+ <dt><a class="permalink" href="#ROMX"><code class="Ic" id="ROMX">ROMX</code></a></dt>
<dd>A banked ROM section. <var class="Ar">addr</var> can range from
- $4000–$7FFF. <var class="Ar">bank</var> can range from 1 to 511.
- Not available if tiny ROM mode is enabled in
- <a class="Xr">rgblink(1)</a>.</dd>
- <dt><a class="permalink" href="#VRAM"><code class="Cm" id="VRAM">VRAM</code></a></dt>
+ <span class="Ad">$4000</span> to <span class="Ad">$7FFF</span>.
+ <var class="Ar">bank</var> can range from 1 to 511. Becomes an alias for
+ <code class="Ic">ROM0</code> if tiny ROM mode is enabled in the
+ linker.</dd>
+ <dt><a class="permalink" href="#VRAM"><code class="Ic" id="VRAM">VRAM</code></a></dt>
<dd>A banked video RAM section. <var class="Ar">addr</var> can range from
- $8000–$9FFF. <var class="Ar">bank</var> can be 0 or 1 but bank 1 is
- unavailable if DMG mode is enabled in <a class="Xr">rgblink(1)</a>. Memory
- in this section can only be allocated with <b class="Sy">DS</b>, not
- filled with data.</dd>
- <dt><a class="permalink" href="#SRAM"><code class="Cm" id="SRAM">SRAM</code></a></dt>
+ <span class="Ad">$8000</span> to <span class="Ad">$9FFF</span>.
+ <var class="Ar">bank</var> can be 0 or 1, but bank 1 is unavailable if DMG
+ mode is enabled in the linker.</dd>
+ <dt><a class="permalink" href="#SRAM"><code class="Ic" id="SRAM">SRAM</code></a></dt>
<dd>A banked external (save) RAM section. <var class="Ar">addr</var> can range
- from $A000–$BFFF. <var class="Ar">bank</var> can range from 0 to
- 15. Memory in this section can only be allocated with
- <b class="Sy">DS</b>, not filled with data.</dd>
- <dt><a class="permalink" href="#WRAM0"><code class="Cm" id="WRAM0">WRAM0</code></a></dt>
+ from <span class="Ad">$A000</span> to <span class="Ad">$BFFF</span>.
+ <var class="Ar">bank</var> can range from 0 to 15.</dd>
+ <dt><a class="permalink" href="#WRAM0"><code class="Ic" id="WRAM0">WRAM0</code></a></dt>
<dd>A general-purpose RAM section. <var class="Ar">addr</var> can range from
- $C000–$CFFF, or $C000–$DFFF if DMG mode is enabled in
- <a class="Xr">rgblink(1)</a>. Memory in this section can only be allocated
- with <b class="Sy">DS</b>, not filled with data.</dd>
- <dt><a class="permalink" href="#WRAMX"><code class="Cm" id="WRAMX">WRAMX</code></a></dt>
+ <span class="Ad">$C000</span> to <span class="Ad">$CFFF</span>, or
+ <span class="Ad">$C000</span> to <span class="Ad">$DFFF</span> if WRAM0
+ mode is enabled in the linker.</dd>
+ <dt><a class="permalink" href="#WRAMX"><code class="Ic" id="WRAMX">WRAMX</code></a></dt>
<dd>A banked general-purpose RAM section. <var class="Ar">addr</var> can range
- from $D000–$DFFF. <var class="Ar">bank</var> can range from 1 to 7.
- Memory in this section can only be allocated with <b class="Sy">DS</b>,
- not filled with data. Not available if DMG mode is enabled in
- <a class="Xr">rgblink(1)</a>.</dd>
- <dt><a class="permalink" href="#OAM"><code class="Cm" id="OAM">OAM</code></a></dt>
- <dd>An object attributes RAM section. <var class="Ar">addr</var> can range
- from $FE00-$FE9F. Memory in this section can only be allocated with
- <b class="Sy">DS</b>, not filled with data.</dd>
- <dt><a class="permalink" href="#HRAM"><code class="Cm" id="HRAM">HRAM</code></a></dt>
+ from <span class="Ad">$D000</span> to <span class="Ad">$DFFF</span>.
+ <var class="Ar">bank</var> can range from 1 to 7. Becomes an alias for
+ <code class="Ic">WRAM0</code> if WRAM0 mode is enabled in the linker.</dd>
+ <dt><a class="permalink" href="#OAM"><code class="Ic" id="OAM">OAM</code></a></dt>
+ <dd>An object attribute RAM section. <var class="Ar">addr</var> can range from
+ <span class="Ad">$FE00</span> to <span class="Ad">$FE9F</span>.</dd>
+ <dt><a class="permalink" href="#HRAM"><code class="Ic" id="HRAM">HRAM</code></a></dt>
<dd>A high RAM section. <var class="Ar">addr</var> can range from
- $FF80–$FFFE. Memory in this section can only be allocated with
- <b class="Sy">DS</b>, not filled with data.
- <p class="Pp"><b class="Sy">Note</b>: If you use this method of allocating
- HRAM the assembler will <i class="Em">not</i> choose the short
- addressing mode in the LD instructions <b class="Sy">LD [$FF00+n8],A</b>
- and <b class="Sy">LD A,[$FF00+n8]</b> because the actual address
- calculation is done by the linker. If you find this undesirable you can
- use <code class="Ic">RSSET</code>, <code class="Ic">RB</code>, or
- <code class="Ic">RW</code> instead or use the <b class="Sy">LDH
- [$FF00+n8],A</b> and <b class="Sy">LDH A,[$FF00+n8]</b> syntax instead.
- This forces the assembler to emit the correct instruction and the linker
- to check if the value is in the correct range. This optimization can be
- disabled by passing the <code class="Fl">-L</code> flag to
- <a class="Xr">rgbasm(1)</a>.</p>
+ <span class="Ad">$FF80</span> to <span class="Ad">$FFFE</span>.
+ <p class="Pp"><b class="Sy">Note</b>: While <code class="Nm">rgbasm</code>
+ will automatically optimize <code class="Ic">ld</code> instructions to
+ the smaller and faster <code class="Ic">ldh</code> (see
+ <a class="Xr" href="gbz80.7.html">gbz80(7)</a>) whenever possible, it is generally unable to
+ do so when a label is involved. Using the <code class="Ic">ldh</code>
+ instruction directly is recommended. This forces the assembler to emit a
+ <code class="Ic">ldh</code> instruction and the linker to check if the
+ value is in the correct range.</p>
</dd>
</dl>
-<p class="Pp"><var class="Ar">option</var>s are comma separated and may
+<p class="Pp">Since RGBDS produces ROMs, code and data can only be placed in
+ <code class="Ic">ROM0</code> and <code class="Ic">ROMX</code> sections. To
+ put some in RAM, have it stored in ROM, and copy it to RAM.</p>
+<p class="Pp"><var class="Ar">option</var>s are comma-separated and may
include:</p>
<dl class="Bl-tag">
- <dt><a class="permalink" href="#BANK"><code class="Cm" id="BANK">BANK</code></a>[<var class="Ar">bank</var>]</dt>
+ <dt><a class="permalink" href="#BANK"><code class="Ic" id="BANK">BANK</code></a>[<var class="Ar">bank</var>]</dt>
<dd>Specify which <var class="Ar">bank</var> for the linker to place the
- section.</dd>
- <dt><a class="permalink" href="#ALIGN"><code class="Cm" id="ALIGN">ALIGN</code></a>[<var class="Ar">align</var>]</dt>
+ section in. See above for possible values for <var class="Ar">bank</var>,
+ depending on <var class="Ar">type</var>.</dd>
+ <dt><a class="permalink" href="#ALIGN"><code class="Ic" id="ALIGN">ALIGN</code></a>[<var class="Ar">align</var>]</dt>
<dd>Place the section at an address whose <var class="Ar">align</var>
- least‐significant bits are zero. It is a syntax error to use this
- option with <var class="Ar">addr</var>.</dd>
+ least‐significant bits are zero. This option can be used with
+ <var class="Ar">addr</var>, as long as they don't contradict
+ eachother.</dd>
</dl>
<p class="Pp">If [<var class="Ar">addr</var>] is not specified, the section is
considered “floating”; the linker will automatically calculate
an appropriate address for the section. Similarly, if
- <code class="Cm">BANK</code>[<var class="Ar">bank</var>] is not specified,
+ <code class="Ic">BANK</code>[<var class="Ar">bank</var>] is not specified,
the linker will automatically find a bank with enough space.</p>
-<p class="Pp">Sections can also be placed by using a linkerscript file. The
- format is described in <a class="Xr">rgblink(5)</a>. They allow the user to
+<p class="Pp">Sections can also be placed by using a linker script file. The
+ format is described in <a class="Xr" href="rgblink.5.html">rgblink(5)</a>. They allow the user to
place floating sections in the desired bank in the order specified in the
script. This is useful if the sections can't be placed at an address
manually because the size may change, but they have to be together.</p>
<p class="Pp">Section examples:</p>
-<div class="Bd Pp Bd-indent">
-<pre>
- SECTION "CoolStuff",ROMX
-</pre>
-</div>
-<p class="Pp">This switches to the section called “CoolStuff” (or
- creates it if it doesn't already exist) and defines it as a code
- section.</p>
-<p class="Pp">The following example defines a section that can be placed
- anywhere in any ROMX bank:</p>
-<div class="Bd Pp Bd-indent">
-<pre>
- SECTION "CoolStuff",ROMX
-</pre>
-</div>
-<p class="Pp">If it is needed, the the base address of the section can be
- specified:</p>
-<div class="Bd Pp Bd-indent">
-<pre>
- SECTION "CoolStuff",ROMX[$4567]
-</pre>
-</div>
-<p class="Pp">An example with a fixed bank:</p>
-<div class="Bd Pp Bd-indent">
-<pre>
- SECTION "CoolStuff",ROMX[$4567],BANK[3]
-</pre>
-</div>
-<p class="Pp">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>
-<div class="Bd Pp Bd-indent">
-<pre>
- SECTION "CoolStuff",ROMX,BANK[7]
-</pre>
-</div>
-<p class="Pp">Alignment examples: one use could be when using DMA to copy data
- or when it is needed to align the start of an array to 256 bytes to optimize
- the code that accesses it.</p>
-<div class="Bd Pp Bd-indent">
-<pre>
- SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes
-
- SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
-</pre>
-</div>
-<p class="Pp"><b class="Sy">Hint</b>: 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 <code class="Ic">ORG</code> for example) that uses
- <code class="Ic">@</code> for the section name and determines correct
- section type etc as arguments for <code class="Ic">SECTION</code>.</p>
-</section>
+<ul class="Bl-item">
+ <li>
+ <div class="Bd Pp Bd-indent">
+ <pre>
+SECTION "CoolStuff",ROMX
+ </pre>
+ </div>
+ This switches to the section called “CoolStuff”, creating it
+ if it doesn't already exist. It can end up in any ROM bank. Code and data
+ may follow.</li>
+ <li>If it is needed, the the base address of the section can be specified:
+ <div class="Bd Pp Bd-indent">
+ <pre>
+SECTION "CoolStuff",ROMX[$4567]
+ </pre>
+ </div>
+ </li>
+ <li>An example with a fixed bank:
+ <div class="Bd Pp Bd-indent">
+ <pre>
+SECTION "CoolStuff",ROMX[$4567],BANK[3]
+ </pre>
+ </div>
+ </li>
+ <li>And if you want to force only the section's bank, and not its position
+ within the bank, that's also possible:
+ <div class="Bd Pp Bd-indent">
+ <pre>
+SECTION "CoolStuff",ROMX,BANK[7]
+ </pre>
+ </div>
+ </li>
+ <li>Alignment examples: The first one could be useful for defining an OAM
+ buffer to be DMA'd, since it must be aligned to 256 bytes. The second
+ could also be appropriate for GBC HDMA, or for an optimized copy code that
+ requires alignment.
+ <div class="Bd Pp Bd-indent">
+ <pre>
+SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes
+SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
+ </pre>
+ </div>
+ </li>
+</ul>
<section class="Ss">
<h2 class="Ss" id="Section_Stack"><a class="permalink" href="#Section_Stack">Section
Stack</a></h2>
<code class="Ic">POPS</code> and <code class="Ic">PUSHS</code> provide the
- interface to the section stack.
+ interface to the section stack. The number of entries in the stack is limited
+ only by the amount of memory in your machine.
<p class="Pp"><code class="Ic">PUSHS</code> will push the current section
context on the section stack. <code class="Ic">POPS</code> can then later be
used to restore it. Useful for defining sections in included files when you
- don't want to destroy the section context for the program that included your
- file. The number of entries in the stack is limited only by the amount of
- memory in your machine.</p>
+ don't want to override the section context at the point the file was
+ included.</p>
</section>
+<section class="Ss">
+<h2 class="Ss" id="RAM_Code"><a class="permalink" href="#RAM_Code">RAM
+ Code</a></h2>
+Sometimes you want to have some code in RAM. But then you can't simply put it in
+ a RAM section, you have to store it in ROM and copy it to RAM at some point.
+<p class="Pp">This means the code (or data) will not be stored in the place it
+ gets executed. Luckily, <code class="Ic">LOAD</code> blocks are the perfect
+ solution to that. Here's an example of how to use them:</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+SECTION "LOAD example", ROMX
+CopyCode:
+ ld de, RAMCode
+ ld hl, RAMLocation
+ ld c, RAMLocation.end - RAMLocation
+.loop
+ ld a, [de]
+ inc de
+ ld [hli], a
+ dec c
+ jr nz, .loop
+ ret
+
+RAMCode:
+ LOAD "RAM code", WRAM0
+RAMLocation:
+ ld hl, .string
+ ld de, $9864
+.copy
+ ld a, [hli]
+ ld [de], a
+ inc de
+ and a
+ jr nz, .copy
+ ret
+
+.string
+ db "Hello World!", 0
+.end
+ ENDL
+</pre>
+</div>
+<p class="Pp">A <code class="Ic">LOAD</code> block feels similar to a
+ <code class="Ic">SECTION</code> declaration because it creates a new one.
+ All data and code generated within such a block is placed in the current
+ section like usual, but all labels are created as if they were placed in
+ this newly-created section.</p>
+<p class="Pp">In the example above, all of the code and data will end up in the
+ "LOAD example" section. You will notice the
+ ‘RAMCode’ and ‘RAMLocation’ labels. The former
+ is situated in ROM, where the code is stored, the latter in RAM, where the
+ code will be loaded.</p>
+<p class="Pp">You cannot nest <code class="Ic">LOAD</code> blocks, nor can you
+ change the current section within them.</p>
</section>
+<section class="Ss">
+<h2 class="Ss" id="Unionized_Sections"><a class="permalink" href="#Unionized_Sections">Unionized
+ Sections</a></h2>
+When you're tight on RAM, you may want to define overlapping blocks of
+ variables, as explained in the <a class="Sx" href="#Unions">Unions</a>
+ section. However, the <code class="Ic">UNION</code> keyword only works within
+ a single file, which prevents e.g. defining temporary variables on a single
+ memory area across several files. Unionized sections solve this problem. To
+ declare an unionized section, add a <code class="Ic">UNION</code> keyword
+ after the <code class="Ic">SECTION</code> one; the declaration is otherwise
+ not different. Unionized sections follow some different rules from normal
+ sections:
+<ul class="Bl-bullet Bd-indent">
+ <li>The same unionized section (= having the same name) can be declared
+ several times per <code class="Nm">rgbasm</code> invocation, and across
+ several invocations. Different declarations are treated and merged
+ identically whether within the same invocation, or different ones.</li>
+ <li>A section cannot be declared both as unionized or non-unionized.</li>
+ <li>All declarations must have the same type. For example, even if
+ <a class="Xr" href="rgblink.1.html">rgblink(1)</a>'s <code class="Fl">-w</code> flag is used,
+ <code class="Ic">WRAM0</code> and <code class="Ic">WRAMX</code> types are
+ still considered different.</li>
+ <li>Different constraints (alignment, bank, etc.) can be specified for each
+ unionized section declaration, but they must all be compatible. For
+ example, alignment must be compatible with any fixed address, all
+ specified banks must be the same, etc.</li>
+ <li>Unionized sections cannot have type <code class="Ic">ROM0</code> or
+ <code class="Ic">ROMX</code>.</li>
+</ul>
+<p class="Pp">Different declarations of the same unionized section are not
+ appended, but instead overlaid on top of eachother, just like
+ <a class="Sx" href="#Unions">Unions</a>. Similarly, the size of an unionized
+ section is the largest of all its declarations.</p>
+</section>
+</section>
<section class="Sh">
<h1 class="Sh" id="SYMBOLS"><a class="permalink" href="#SYMBOLS">SYMBOLS</a></h1>
-<section class="Ss">
-<h2 class="Ss" id="Symbols"><a class="permalink" href="#Symbols">Symbols</a></h2>
RGBDS supports several types of symbols:
<dl class="Bl-hang">
<dt><b class="Sy">Label</b></dt>
- <dd>Used to assign a memory location with a name</dd>
- <dt><b class="Sy">EQUate</b></dt>
- <dd>Give a constant a name.</dd>
- <dt><b class="Sy">SET</b></dt>
- <dd>Almost the same as EQUate, but you can change the value of a SET during
- assembling.</dd>
- <dt><b class="Sy">Structure</b> (<b class="Sy">the RS group</b>)</dt>
- <dd>Define a structure easily.</dd>
- <dt><b class="Sy">String equate</b> (<b class="Sy">EQUS</b>)</dt>
- <dd>Give a frequently used string a name. Can also be used as a mini-macro,
- like <code class="Fd">#define</code> in C.</dd>
- <dt><b class="Sy">MACRO</b></dt>
- <dd>A block of code or pseudo instructions that you invoke like any other
- mnemonic. You can give them arguments too.</dd>
+ <dd>Numerical symbol designating a memory location. May or may not have a
+ value known at assembly time.</dd>
+ <dt><b class="Sy">Constant</b></dt>
+ <dd>Numerical symbol whose value has to be known at assembly time.</dd>
+ <dt><b class="Sy">Macro</b></dt>
+ <dd>A block of <code class="Nm">rgbasm</code> code that can be invoked
+ later.</dd>
+ <dt><b class="Sy">String equate</b></dt>
+ <dd>String symbol that can be evaluated, similarly to a macro.</dd>
</dl>
-<p class="Pp">A symbol cannot have the same name as a reserved keyword.</p>
-<dl class="Bl-hang">
- <dt><b class="Sy">Label</b></dt>
- <dd>
- <p class="Pp">One of the assembler's main tasks is to keep track of
- addresses for you so you don't have to remember obscure numbers but can
- make do with a meaningful name, a label.</p>
+<p class="Pp">Symbol names can contain letters, numbers, underscores, hashes and
+ ‘@’. However, they must begin with either a letter, a number,
+ or an underscore. Periods are allowed exclusively for labels, as described
+ below. A symbol cannot have the same name as a reserved keyword.
+ <i class="Em">In the line where a symbol is defined there mustn't be any
+ whitespace before it</i>, otherwise <code class="Nm">rgbasm</code> will
+ treat it as a macro invocation.</p>
+<dl class="Bl-tag">
+ <dt><b class="Sy">Label declaration</b></dt>
+ <dd>One of the assembler's main tasks is to keep track of addresses for you,
+ so you can work with meaningful names instead of "magic"
+ numbers.
<p class="Pp">This can be done in a number of ways:</p>
<div class="Bd Pp Bd-indent">
<pre>
-GlobalLabel
-AnotherGlobal:
+GlobalLabel ; This syntax is deprecated,
+AnotherGlobal: ; please use this instead
.locallabel
.yet_a_local:
AnotherGlobal.with_another_local:
-ThisWillBeExported:: ;note the two colons
+ThisWillBeExported:: ; Note the two colons
ThisWillBeExported.too::
</pre>
</div>
- <p class="Pp">In the line where a label is defined there musn't be any
- whitespace before it. Local labels are only accessible within the scope
- they are defined. A scope starts after a global label and ends at the
- next global label. Declaring a label (global or local) with :: does an
- EXPORT at the same time. Local labels can be declared as scope.local or
- simply as as .local. If the former notation is used, the scope must be
- the actual current scope.</p>
- <p class="Pp">Labels will normally change their value during the link
- process and are thus not constant. The exception is the case in which
- the base address of a section is fixed, so the address of the label is
- known at assembly time.</p>
- <p class="Pp">The subtraction of two labels is only constant (known at
- assembly time) if they are two local labels that belong to the same
- scope, or they are two global labels that belong to sections with fixed
- base addresses.</p>
+ <p class="Pp">Declaring a label (global or local) with
+ ‘<code class="Li">::</code>’ does an
+ <code class="Ic">EXPORT</code> at the same time. (See
+ <a class="Sx" href="#Exporting_and_importing_symbols">Exporting and
+ importing symbols</a> below).</p>
+ <p class="Pp">Any label whose name does not contain a period is a global
+ label, others are locals. Declaring a global label sets it as the
+ current label scope until the next one; any local label whose first
+ character is a period will have the global label's name implicitly
+ prepended. Local labels can be declared as
+ ‘<code class="Li">scope.local:</code>’ or simply as as
+ ‘<code class="Li">.local:</code>’. If the former notation
+ is used, then ‘<code class="Li">scope</code>’ must be the
+ actual current scope.</p>
+ <p class="Pp">A label's location (and thus value) is usually not determined
+ until the linking stage, so labels usually cannot be used as constants.
+ However, if the section in which the label is declared has a fixed base
+ address, its value is known at assembly time.</p>
+ <p class="Pp"><code class="Nm">rgbasm</code> is able to compute the
+ subtraction of two labels either if both are constant as described
+ above, or if both belong to the same section.</p>
</dd>
- <dt><b class="Sy">EQU</b></dt>
- <dd>
- <p class="Pp">EQUates are constant symbols. They can, for example, be used
- for things such as bit-definitions of hardware registers.</p>
+ <dt><a class="permalink" href="#EQU"><code class="Ic" id="EQU">EQU</code></a></dt>
+ <dd><a class="permalink" href="#EQU_2"><code class="Ic" id="EQU_2">EQU</code></a>
+ allows defining constant symbols. Unlike <code class="Ic">SET</code>
+ below, constants defined this way cannot be redefined. They can, for
+ example, be used for things such as bit definitions of hardware registers.
<div class="Bd Pp Bd-indent">
<pre>
-EXIT_OK EQU $00
-EXIT_FAILURE EQU $01
+SCREEN_WIDTH equ 160 ; In pixels
+SCREEN_HEIGHT equ 144
</pre>
</div>
- <p class="Pp">Note that a colon (:) following the label-name is not allowed.
- EQUates cannot be exported and imported. They don't change their value
- during the link process.</p>
+ <p class="Pp">Note that colons ‘<code class="Li">:</code>’
+ following the name are not allowed.</p>
</dd>
- <dt><b class="Sy">SET</b></dt>
- <dd>
- <p class="Pp">SETs are similar to EQUates. They are also constant symbols in
- the sense that their values are defined during the assembly process.
- These symbols are normally used in macros.</p>
+ <dt><a class="permalink" href="#SET"><code class="Ic" id="SET">SET</code></a></dt>
+ <dd><a class="permalink" href="#SET_2"><code class="Ic" id="SET_2">SET</code></a>,
+ or its synonym <code class="Ic">=</code>, defines constant symbols like
+ <code class="Ic">EQU</code>, but those constants can be re-defined. This
+ is useful for variables in macros, for counters, etc.
<div class="Bd Pp Bd-indent">
<pre>
ARRAY_SIZE EQU 4
COUNT SET 2
COUNT SET ARRAY_SIZE+COUNT
+; COUNT now has the value 6
+COUNT = COUNT + 1
</pre>
</div>
- <p class="Pp">Note that a colon (:) following the label-name is not allowed.
- SETs cannot be exported and imported. Alternatively you can use = as a
- synonym for SET.</p>
- <div class="Bd Pp Bd-indent">
- <pre>
-COUNT = 2
- </pre>
- </div>
+ <p class="Pp">Note that colons ‘<code class="Li">:</code>’
+ following the name are not allowed.</p>
</dd>
- <dt><b class="Sy">RSSET</b>, <b class="Sy">RSRESET</b>, <b class="Sy">RB</b>,
- <b class="Sy">RW</b></dt>
- <dd>
- <p class="Pp">The RS group of commands is a handy way of defining
- structures:</p>
+ <dt><a class="permalink" href="#RSSET"><code class="Ic" id="RSSET">RSSET</code></a>,
+ <code class="Ic">RSRESET</code>, <code class="Ic">RB</code>,
+ <code class="Ic">RW</code></dt>
+ <dd>The RS group of commands is a handy way of defining structures:
<div class="Bd Pp Bd-indent">
<pre>
RSRESET
@@ -341,27 +971,27 @@
str_SIZEOF RB 0
</pre>
</div>
- <p class="Pp">The example defines four equated symbols:</p>
+ <p class="Pp">The example defines four constants as if by:</p>
<div class="Bd Pp Bd-indent">
<pre>
-str_pStuff = 0
-str_tData = 2
-str_bCount = 258
-str_SIZEOF = 259
+str_pStuff EQU 0
+str_tData EQU 2
+str_bCount EQU 258
+str_SIZEOF EQU 259
</pre>
</div>
- <p class="Pp">There are four commands in the RS group of commands:</p>
+ <p class="Pp">There are five commands in the RS group of commands:</p>
<table class="Bl-column">
<tr>
- <td><b class="Sy">Command</b></td>
- <td><b class="Sy">Meaning</b></td>
+ <th>Command</th>
+ <th>Meaning</th>
</tr>
<tr>
<td><a class="permalink" href="#RSRESET"><code class="Ic" id="RSRESET">RSRESET</code></a></td>
- <td>Resets the _RS counter to zero.</td>
+ <td>Equivalent to ‘<code class="Li">RSSET 0</code>’.</td>
</tr>
<tr>
- <td><a class="permalink" href="#RSSET"><code class="Ic" id="RSSET">RSSET</code></a>
+ <td><a class="permalink" href="#RSSET_2"><code class="Ic" id="RSSET_2">RSSET</code></a>
<var class="Ar">constexpr</var></td>
<td>Sets the <code class="Ic">_RS</code> <span class="No">counter
to</span> <var class="Ar">constexpr</var>.</td>
@@ -378,7 +1008,7 @@
<var class="Ar">constexpr</var></td>
<td>Sets the preceding symbol to <code class="Ic">_RS</code>
<span class="No">and adds</span> <var class="Ar">constexpr</var>
- <span class="No">* 2 to</span> <code class="Ic">_RS.</code></td>
+ <span class="No">* 2 to</span> <code class="Ic">_RS</code>.</td>
</tr>
<tr>
<td><a class="permalink" href="#RL"><code class="Ic" id="RL">RL</code></a>
@@ -385,19 +1015,18 @@
<var class="Ar">constexpr</var></td>
<td>Sets the preceding symbol to <code class="Ic">_RS</code>
<span class="No">and adds</span> <var class="Ar">constexpr</var>
- <span class="No">* 4 to</span> <code class="Ic">_RS.</code></td>
+ <span class="No">* 4 to</span> <code class="Ic">_RS</code>. (In
+ practice, this one cannot be used due to a bug).</td>
</tr>
</table>
- <p class="Pp">Note that a colon (:) following the symbol-name is not
- allowed. <b class="Sy">RS</b> symbols cannot be exported and imported.
- They don't change their value during the link process.</p>
+ <p class="Pp">Note that colons ‘<code class="Li">:</code>’
+ following the name are not allowed.</p>
</dd>
- <dt><b class="Sy">EQUS</b></dt>
- <dd>
- <p class="Pp">EQUS is used to define string-symbols. Wherever the assembler
- meets a string symbol its name is replaced with its value. If you are
- familiar with C you can think of it as the same as
- <code class="Fd">#define .</code></p>
+ <dt><a class="permalink" href="#EQUS"><code class="Ic" id="EQUS">EQUS</code></a></dt>
+ <dd><a class="permalink" href="#EQUS_2"><code class="Ic" id="EQUS_2">EQUS</code></a>
+ is used to define string symbols. Wherever the assembler meets a string
+ symbol its name is replaced with its value. If you are familiar with C you
+ can think of it as similar to <code class="Fd">#define .</code>
<div class="Bd Pp Bd-indent">
<pre>
COUNTREG EQUS "[hl+]"
@@ -407,8 +1036,6 @@
db PLAYER_NAME
</pre>
</div>
- <p class="Pp">Note that : following the label-name is not allowed, and that
- strings must be quoted to be useful.</p>
<p class="Pp">This will be interpreted as:</p>
<div class="Bd Pp Bd-indent">
<pre>
@@ -416,27 +1043,29 @@
db "John"
</pre>
</div>
- <p class="Pp">String-symbols can also be used to define small one-line
+ <p class="Pp">String symbols can also be used to define small one-line
macros:</p>
<div class="Bd Pp Bd-indent">
<pre>
-PUSHA EQUS "push af\npush bc\npush de\npush hl\n"
+pusha EQUS "push af\npush bc\npush de\npush hl\n"
</pre>
</div>
- <p class="Pp">Note that a colon (:) following the label-name is not allowed.
- String equates can't be exported or imported.</p>
- <p class="Pp"><b class="Sy">Important note</b>: An EQUS can be expanded to a
- string that contains another EQUS and it will be expanded as well. If
- this creates an infinite loop, RGBASM will error out once a certain
- depth is reached. See the -r command-line option. Also, a MACRO can have
- inside an EQUS which references the same MACRO, which has the same
- problem.</p>
+ <p class="Pp">Note that colons ‘<code class="Li">:</code>’
+ following the name are not allowed. String equates can't be exported or
+ imported.</p>
+ <p class="Pp"><b class="Sy">Important note</b>: An
+ <code class="Ic">EQUS</code> can be expanded to a string that contains
+ another <code class="Ic">EQUS</code> and it will be expanded as well. If
+ this creates an infinite loop, <code class="Nm">rgbasm</code> will error
+ out once a certain depth is reached. See the <code class="Fl">-r</code>
+ command-line option in <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>. Also, a macro can
+ contain an <code class="Ic">EQUS</code> which calls the same macro,
+ which causes the same problem.</p>
</dd>
- <dt><b class="Sy">MACRO</b></dt>
- <dd>
- <p class="Pp">One of the best features of an assembler is the ability to
- write macros for it. Macros also provide a method of passing arguments
- to them and they can then react to the input using IF-constructs.</p>
+ <dt><a class="permalink" href="#MACRO"><code class="Ic" id="MACRO">MACRO</code></a></dt>
+ <dd>One of the best features of an assembler is the ability to write macros
+ for it. Macros can be called with arguments, and can react depending on
+ input using <code class="Ic">IF</code> constructs.
<div class="Bd Pp Bd-indent">
<pre>
MyMacro: MACRO
@@ -445,145 +1074,40 @@
ENDM
</pre>
</div>
- <p class="Pp">Note that a colon (:) following the macro-name is required.
- Macros can't be exported or imported. It's valid to call a macro from a
- macro (yes, even the same one).</p>
- <p class="Pp">The above example is a very simple macro. You execute the
- macro by typing its name.</p>
- <div class="Bd Pp Bd-indent">
- <pre>
- add a,b
- ld sp,hl
- MyMacro ;This will be expanded
- sub a,87
- </pre>
- </div>
- <p class="Pp">When the assembler meets MyMacro it will insert the
- macrodefinition (the text enclosed in <code class="Ic">MACRO</code> /
- <code class="Ic">ENDM</code>).</p>
- <p class="Pp">Suppose your macro contains a loop.</p>
- <div class="Bd Pp Bd-indent">
- <pre>
-LoopyMacro: MACRO
- xor a,a
-.loop ld [hl+],a
- dec c
- jr nz,.loop
- ENDM
- </pre>
- </div>
- <p class="Pp">This is fine. That is, if you only use the macro once per
- scope. To get around this problem there is a special label string equate
- called <code class="Ic">\@</code> that you can append to your labels and
- it will then expand to a unique string.</p>
- <p class="Pp"><code class="Ic">\@</code> also works in REPT-blocks should
- you have any loops there.</p>
- <div class="Bd Pp Bd-indent">
- <pre>
-LoopyMacro: MACRO
- xor a,a
-.loop\@ ld [hl+],a
- dec c
- jr nz,.loop\@
- ENDM
- </pre>
- </div>
- <p class="Pp"><b class="Sy">Important note</b>: Since a MACRO can call
- itself (or a different MACRO that calls the first one) there can be
- problems of circular dependency. They trap the assembler in an infinite
- loop, so you have to be careful when using recursion with MACROs. Also,
- a MACRO can have inside an EQUS which references the same MACRO, which
- has the same problem.</p>
- <p class="Pp"><b class="Sy">Macro Arguments</b></p>
- <p class="Pp">I'd like LoopyMacro a lot better if I didn't have to pre-load
- the registers with values and then call it. What I'd like is the ability
- to pass it arguments and it then loaded the registers itself.</p>
- <p class="Pp">And I can do that. In macros you can get the arguments by
- using the special macro string equates <code class="Ic">\1</code>
- through <code class="Ic">\9</code>, <code class="Ic">\1</code> being the
- first argument specified on the calling of the macro.</p>
- <div class="Bd Pp Bd-indent">
- <pre>
-LoopyMacro: MACRO
- ld hl,\1
- ld c,\2
- xor a,a
-.loop\@ ld [hl+],a
- dec c
- jr nz,.loop\@
- ENDM
- </pre>
- </div>
- <p class="Pp">Now I can call the macro specifying two arguments. The first
- being the address and the second being a bytecount. The macro will then
- reset all bytes in this range.</p>
- <div class="Bd Pp Bd-indent">
- <pre>
-LoopyMacro MyVars,54
- </pre>
- </div>
- <p class="Pp">Arguments are passed as string equates. There's no need to
- enclose them in quotes. An expression will not be evaluated first but
- passed directly. This means that it's probably a very good idea to use
- brackets around <code class="Ic">\1</code> to <code class="Ic">\9</code>
- if you perform further calculations on them. For instance, if you pass 1
- + 2 as the first argument and then do <code class="Ic">PRINTV</code>
- <code class="Ic">\1</code> * 2 you will get the value 5 on screen and
- not 6 as you might have expected.</p>
- <p class="Pp">In reality, up to 256 arguments can be passed to a macro, but
- you can only use the first 9 like this. If you want to use the rest, you
- need to use the keyword <code class="Ic">SHIFT</code>.</p>
- <p class="Pp">Line continuations work as usual inside macros or lists of
- arguments of macros. However, some characters need to be escaped, as in
- the following example:</p>
- <div class="Bd Pp Bd-indent">
- <pre>
-PrintMacro : MACRO
- PRINTT \1
-ENDM
-
- PrintMacro STRCAT("Hello"\, \
- " world\\n")
- </pre>
- </div>
- <p class="Pp"><code class="Ic">SHIFT</code> is a special command only
- available in macros. Very useful in REPT-blocks. It will shift the
- arguments by one to the left. <code class="Ic">\1</code> will get the
- value of <code class="Ic">\2</code>, <code class="Ic">\2</code> will get
- the value in <code class="Ic">\3</code> and so forth.</p>
- <p class="Pp">This is the only way of accessing the value of arguments from
- 10 to 256.</p>
+ <p class="Pp">Note that a single colon
+ ‘<code class="Li">:</code>’ following the macro's name is
+ required. Macros can't be exported or imported.</p>
</dd>
</dl>
-</section>
<section class="Ss">
<h2 class="Ss" id="Exporting_and_importing_symbols"><a class="permalink" href="#Exporting_and_importing_symbols">Exporting
and importing symbols</a></h2>
Importing and exporting of symbols is a feature that is very useful when your
- project spans many source-files and, for example, you need to jump to a
+ project spans many source files and, for example, you need to jump to a
routine defined in another file.
<p class="Pp">Exporting of symbols has to be done manually, importing is done
- automatically if the assembler doesn't know where a symbol is defined.</p>
-<p class="Pp"><code class="Ic">EXPORT</code> <var class="Ar">label</var> [,
- <var class="Ar">label</var> , <span class="No">...</span>]</p>
-<p class="Pp">The assembler will make label accessible to other files during the
- link process.</p>
-<p class="Pp"><code class="Ic">GLOBAL</code> <var class="Ar">label</var> [,
- <var class="Ar">label</var> , <span class="No">...</span>]</p>
-<p class="Pp">If label is defined during the assembly it will be exported, if
- not, it will be imported. Handy (very!) for include-files. Note that, since
- importing is done automatically, this keyword has the same effect as
- <code class="Ic">EXPORT</code>.</p>
+ automatically if <code class="Nm">rgbasm</code> finds a symbol it does not
+ know about.</p>
+<p class="Pp">The following will cause <var class="Ar">symbol1</var>,
+ <var class="Ar">symbol2</var> and so on to be accessible to other files
+ during the link process:</p>
+<div class="Bd Bd-indent"><code class="Li"><code class="Ic">EXPORT</code>
+ <var class="Ar">symbol1</var> [, <var class="Ar">symbol2</var>,
+ <span class="No">...</span>]</code></div>
+<p class="Pp"><code class="Ic">GLOBAL</code> is a deprecated synonym for
+ <code class="Ic">EXPORT</code>, do not use it.</p>
+<p class="Pp">Note also that only exported symbols will appear in symbol and map
+ files produced by <a class="Xr" href="rgblink.1.html">rgblink(1)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Purging_symbols"><a class="permalink" href="#Purging_symbols">Purging
symbols</a></h2>
<code class="Ic">PURGE</code> allows you to completely remove a symbol from the
- symbol table as if it had never existed. USE WITH EXTREME CAUTION!!! I can't
- stress this enough, you seriously need to know what you are doing. DON'T purge
- symbol that you use in expressions the linker needs to calculate. In fact,
- it's probably not even safe to purge anything other than string symbols and
- macros.
+ symbol table as if it had never existed. <i class="Em">USE WITH EXTREME
+ CAUTION!!!</i> I can't stress this enough, <b class="Sy">you seriously need to
+ know what you are doing</b>. DON'T purge a symbol that you use in expressions
+ the linker needs to calculate. When not sure, it's probably not safe to purge
+ anything other than string symbols, macros, and constants.
<div class="Bd Pp Bd-indent">
<pre>
Kamikaze EQUS "I don't want to live anymore"
@@ -591,9 +1115,9 @@
PURGE Kamikaze, AOLer
</pre>
</div>
-<p class="Pp">Note that string symbols that are part of a
- <code class="Ic">PURGE</code> command WILL NOT BE EXPANDED as the ONLY
- exception to this rule.</p>
+<p class="Pp">Note that, as an exception, string symbols in the argument list of
+ a <code class="Ic">PURGE</code> command <i class="Em">will not be
+ expanded</i>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Predeclared_Symbols"><a class="permalink" href="#Predeclared_Symbols">Predeclared
@@ -601,105 +1125,105 @@
The following symbols are defined by the assembler:
<table class="Bl-column Bd-indent">
<tr>
- <td><b class="Sy">Type</b></td>
- <td><b class="Sy">Name</b></td>
- <td><b class="Sy">Contents</b></td>
+ <th>Type</th>
+ <th>Name</th>
+ <th>Contents</th>
</tr>
<tr>
- <td><a class="permalink" href="#EQU"><code class="Ic" id="EQU">EQU</code></a></td>
- <td><a class="permalink" href="#@"><code class="Ic" id="@">@</code></a></td>
+ <td><a class="permalink" href="#EQU_3"><code class="Ic" id="EQU_3">EQU</code></a></td>
+ <td><a class="permalink" href="#@"><code class="Dv" id="@">@</code></a></td>
<td>PC value</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQU_2"><code class="Ic" id="EQU_2">EQU</code></a></td>
- <td><a class="permalink" href="#_PI"><code class="Ic" id="_PI">_PI</code></a></td>
+ <td><a class="permalink" href="#EQU_4"><code class="Ic" id="EQU_4">EQU</code></a></td>
+ <td><a class="permalink" href="#_PI"><code class="Dv" id="_PI">_PI</code></a></td>
<td>Fixed point π</td>
</tr>
<tr>
- <td><a class="permalink" href="#SET"><code class="Ic" id="SET">SET</code></a></td>
- <td><a class="permalink" href="#_RS"><code class="Ic" id="_RS">_RS</code></a></td>
+ <td><a class="permalink" href="#SET_3"><code class="Ic" id="SET_3">SET</code></a></td>
+ <td><a class="permalink" href="#_RS"><code class="Dv" id="_RS">_RS</code></a></td>
<td>_RS Counter</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQU_3"><code class="Ic" id="EQU_3">EQU</code></a></td>
- <td><a class="permalink" href="#_NARG"><code class="Ic" id="_NARG">_NARG</code></a></td>
+ <td><a class="permalink" href="#EQU_5"><code class="Ic" id="EQU_5">EQU</code></a></td>
+ <td><a class="permalink" href="#_NARG"><code class="Dv" id="_NARG">_NARG</code></a></td>
<td>Number of arguments passed to macro</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQU_4"><code class="Ic" id="EQU_4">EQU</code></a></td>
- <td><a class="permalink" href="#__LINE__"><code class="Ic" id="__LINE__">__LINE__</code></a></td>
+ <td><a class="permalink" href="#EQU_6"><code class="Ic" id="EQU_6">EQU</code></a></td>
+ <td><a class="permalink" href="#__LINE__"><code class="Dv" id="__LINE__">__LINE__</code></a></td>
<td>The current line number</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQUS"><code class="Ic" id="EQUS">EQUS</code></a></td>
- <td><a class="permalink" href="#__FILE__"><code class="Ic" id="__FILE__">__FILE__</code></a></td>
+ <td><a class="permalink" href="#EQUS_3"><code class="Ic" id="EQUS_3">EQUS</code></a></td>
+ <td><a class="permalink" href="#__FILE__"><code class="Dv" id="__FILE__">__FILE__</code></a></td>
<td>The current filename</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQUS_2"><code class="Ic" id="EQUS_2">EQUS</code></a></td>
- <td><a class="permalink" href="#__DATE__"><code class="Ic" id="__DATE__">__DATE__</code></a></td>
+ <td><a class="permalink" href="#EQUS_4"><code class="Ic" id="EQUS_4">EQUS</code></a></td>
+ <td><a class="permalink" href="#__DATE__"><code class="Dv" id="__DATE__">__DATE__</code></a></td>
<td>Today's date</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQUS_3"><code class="Ic" id="EQUS_3">EQUS</code></a></td>
- <td><a class="permalink" href="#__TIME__"><code class="Ic" id="__TIME__">__TIME__</code></a></td>
+ <td><a class="permalink" href="#EQUS_5"><code class="Ic" id="EQUS_5">EQUS</code></a></td>
+ <td><a class="permalink" href="#__TIME__"><code class="Dv" id="__TIME__">__TIME__</code></a></td>
<td>The current time</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQUS_4"><code class="Ic" id="EQUS_4">EQUS</code></a></td>
- <td><a class="permalink" href="#__ISO_8601_LOCAL__"><code class="Ic" id="__ISO_8601_LOCAL__">__ISO_8601_LOCAL__</code></a></td>
+ <td><a class="permalink" href="#EQUS_6"><code class="Ic" id="EQUS_6">EQUS</code></a></td>
+ <td><a class="permalink" href="#__ISO_8601_LOCAL__"><code class="Dv" id="__ISO_8601_LOCAL__">__ISO_8601_LOCAL__</code></a></td>
<td>ISO 8601 timestamp (local)</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQUS_5"><code class="Ic" id="EQUS_5">EQUS</code></a></td>
- <td><a class="permalink" href="#__ISO_8601_UTC__"><code class="Ic" id="__ISO_8601_UTC__">__ISO_8601_UTC__</code></a></td>
+ <td><a class="permalink" href="#EQUS_7"><code class="Ic" id="EQUS_7">EQUS</code></a></td>
+ <td><a class="permalink" href="#__ISO_8601_UTC__"><code class="Dv" id="__ISO_8601_UTC__">__ISO_8601_UTC__</code></a></td>
<td>ISO 8601 timestamp (UTC)</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQU_5"><code class="Ic" id="EQU_5">EQU</code></a></td>
- <td><a class="permalink" href="#__UTC_YEAR__"><code class="Ic" id="__UTC_YEAR__">__UTC_YEAR__</code></a></td>
+ <td><a class="permalink" href="#EQU_7"><code class="Ic" id="EQU_7">EQU</code></a></td>
+ <td><a class="permalink" href="#__UTC_YEAR__"><code class="Dv" id="__UTC_YEAR__">__UTC_YEAR__</code></a></td>
<td>Today's year</td>
</tr>
<tr>
- <td><a class="permalink" href="#EQU_6"><code class="Ic" id="EQU_6">EQU</code></a></td>
- <td><a class="permalink" href="#__UTC_MONTH__"><code class="Ic" id="__UTC_MONTH__">__UTC_MONTH__</code></a></td>
- <td>Today's month number, 1-12</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#EQU_7"><code class="Ic" id="EQU_7">EQU</code></a></td>
- <td><a class="permalink" href="#__UTC_DAY__"><code class="Ic" id="__UTC_DAY__">__UTC_DAY__</code></a></td>
- <td>Today's day of the month, 1-31</td>
- </tr>
- <tr>
<td><a class="permalink" href="#EQU_8"><code class="Ic" id="EQU_8">EQU</code></a></td>
- <td><a class="permalink" href="#__UTC_HOUR__"><code class="Ic" id="__UTC_HOUR__">__UTC_HOUR__</code></a></td>
- <td>Current hour, 0-23</td>
+ <td><a class="permalink" href="#__UTC_MONTH__"><code class="Dv" id="__UTC_MONTH__">__UTC_MONTH__</code></a></td>
+ <td>Today's month number, 1–12</td>
</tr>
<tr>
<td><a class="permalink" href="#EQU_9"><code class="Ic" id="EQU_9">EQU</code></a></td>
- <td><a class="permalink" href="#__UTC_MINUTE__"><code class="Ic" id="__UTC_MINUTE__">__UTC_MINUTE__</code></a></td>
- <td>Current minute, 0-59</td>
+ <td><a class="permalink" href="#__UTC_DAY__"><code class="Dv" id="__UTC_DAY__">__UTC_DAY__</code></a></td>
+ <td>Today's day of the month, 1–31</td>
</tr>
<tr>
<td><a class="permalink" href="#EQU_10"><code class="Ic" id="EQU_10">EQU</code></a></td>
- <td><a class="permalink" href="#__UTC_SECOND__"><code class="Ic" id="__UTC_SECOND__">__UTC_SECOND__</code></a></td>
- <td>Current second, 0-59</td>
+ <td><a class="permalink" href="#__UTC_HOUR__"><code class="Dv" id="__UTC_HOUR__">__UTC_HOUR__</code></a></td>
+ <td>Current hour, 0–23</td>
</tr>
<tr>
<td><a class="permalink" href="#EQU_11"><code class="Ic" id="EQU_11">EQU</code></a></td>
- <td><a class="permalink" href="#__RGBDS_MAJOR__"><code class="Ic" id="__RGBDS_MAJOR__">__RGBDS_MAJOR__</code></a></td>
- <td>Major version number of RGBDS.</td>
+ <td><a class="permalink" href="#__UTC_MINUTE__"><code class="Dv" id="__UTC_MINUTE__">__UTC_MINUTE__</code></a></td>
+ <td>Current minute, 0–59</td>
</tr>
<tr>
<td><a class="permalink" href="#EQU_12"><code class="Ic" id="EQU_12">EQU</code></a></td>
- <td><a class="permalink" href="#__RGBDS_MINOR__"><code class="Ic" id="__RGBDS_MINOR__">__RGBDS_MINOR__</code></a></td>
- <td>Minor version number of RGBDS.</td>
+ <td><a class="permalink" href="#__UTC_SECOND__"><code class="Dv" id="__UTC_SECOND__">__UTC_SECOND__</code></a></td>
+ <td>Current second, 0–59</td>
</tr>
<tr>
<td><a class="permalink" href="#EQU_13"><code class="Ic" id="EQU_13">EQU</code></a></td>
- <td><a class="permalink" href="#__RGBDS_PATCH__"><code class="Ic" id="__RGBDS_PATCH__">__RGBDS_PATCH__</code></a></td>
- <td>Patch version number of RGBDS.</td>
+ <td><a class="permalink" href="#__RGBDS_MAJOR__"><code class="Dv" id="__RGBDS_MAJOR__">__RGBDS_MAJOR__</code></a></td>
+ <td>Major version number of RGBDS</td>
</tr>
+ <tr>
+ <td><a class="permalink" href="#EQU_14"><code class="Ic" id="EQU_14">EQU</code></a></td>
+ <td><a class="permalink" href="#__RGBDS_MINOR__"><code class="Dv" id="__RGBDS_MINOR__">__RGBDS_MINOR__</code></a></td>
+ <td>Minor version number of RGBDS</td>
+ </tr>
+ <tr>
+ <td><a class="permalink" href="#EQU_15"><code class="Ic" id="EQU_15">EQU</code></a></td>
+ <td><a class="permalink" href="#__RGBDS_PATCH__"><code class="Dv" id="__RGBDS_PATCH__">__RGBDS_PATCH__</code></a></td>
+ <td>Patch version number of RGBDS</td>
+ </tr>
</table>
</section>
</section>
@@ -707,60 +1231,73 @@
<h1 class="Sh" id="DEFINING_DATA"><a class="permalink" href="#DEFINING_DATA">DEFINING
DATA</a></h1>
<section class="Ss">
+<h2 class="Ss" id="Declaring_variables_in_a_RAM_section"><a class="permalink" href="#Declaring_variables_in_a_RAM_section">Declaring
+ variables in a RAM section</a></h2>
+<code class="Ic">DS</code> allocates a number of empty bytes. This is the
+ preferred method of allocating space in a RAM section. You can also use
+ <code class="Ic">DB</code>, <code class="Ic">DW</code> and
+ <code class="Ic">DL</code> without any arguments instead (see
+ <a class="Sx" href="#Defining_constant_data">Defining constant data</a>
+ below).
+<div class="Bd Pp Bd-indent">
+<pre>
+DS 42 ; Allocates 42 bytes
+</pre>
+</div>
+<p class="Pp">Empty space in RAM sections will not be initialized. In ROM
+ sections, it will be filled with the value passed to the
+ <code class="Fl">-p</code> command-line option, except when using overlays
+ with <code class="Fl">-O</code>.</p>
+</section>
+<section class="Ss">
<h2 class="Ss" id="Defining_constant_data"><a class="permalink" href="#Defining_constant_data">Defining
constant data</a></h2>
<code class="Ic">DB</code> defines a list of bytes that will be stored in the
- final image. Ideal for tables and text (which is not zero-terminated).
+ final image. Ideal for tables and text. Note that strings are not
+ zero-terminated!
<div class="Bd Pp Bd-indent">
<pre>
DB 1,2,3,4,"This is a string"
</pre>
</div>
+<p class="Pp"><code class="Ic">DS</code> can also be used to fill a region of
+ memory with some value. The following produces 42 times the byte $FF:</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+DS 42, $FF
+</pre>
+</div>
<p class="Pp">Alternatively, you can use <code class="Ic">DW</code> to store a
- list of words (16-bits) or <code class="Ic">DL</code> to store a list of
- doublewords/longs (32-bits). Strings are not allowed as arguments to
+ list of words (16-bit) or <code class="Ic">DL</code> to store a list of
+ double-words/longs (32-bit). Strings are not allowed as arguments to
<code class="Ic">DW</code> and <code class="Ic">DL</code>.</p>
<p class="Pp">You can also use <code class="Ic">DB</code>,
<code class="Ic">DW</code> and <code class="Ic">DL</code> without arguments,
or leaving empty elements at any point in the list. This works exactly like
- <b class="Sy">DS 1</b>, <b class="Sy">DS 2</b> and <b class="Sy">DS 4</b>
- respectively. Consequently, <code class="Ic">DB</code>,
- <code class="Ic">DW</code> and <code class="Ic">DL</code> can be used in a
- <b class="Sy">WRAM0</b> <span class="No">/</span> <b class="Sy">WRAMX</b>
- <span class="No">/</span> <b class="Sy">HRAM</b> <span class="No">/</span>
- <b class="Sy">VRAM</b> <span class="No">/</span> <b class="Sy">SRAM</b>
- section.</p>
+ <code class="Ic">DS 1</code>, <code class="Ic">DS 2</code> and
+ <code class="Ic">DS 4</code> respectively. Consequently, no-argument
+ <code class="Ic">DB</code>, <code class="Ic">DW</code> and
+ <code class="Ic">DL</code> can be used in a <code class="Ic">WRAM0</code> /
+ <code class="Ic">WRAMX</code> / <code class="Ic">HRAM</code> /
+ <code class="Ic">VRAM</code> / <code class="Ic">SRAM</code> section.</p>
</section>
<section class="Ss">
-<h2 class="Ss" id="Declaring_variables_in_a_RAM_section"><a class="permalink" href="#Declaring_variables_in_a_RAM_section">Declaring
- variables in a RAM section</a></h2>
-<code class="Ic">DS</code> allocates a number of bytes. The content is
- undefined. This is the preferred method of allocationg space in a RAM section.
- You can, however, use <code class="Ic">DB</code>, <code class="Ic">DW</code>
- and <code class="Ic">DL</code> without any arguments instead.
-<div class="Bd Pp Bd-indent">
-<pre>
-DS str_SIZEOF ;allocate str_SIZEOF bytes
-</pre>
-</div>
-</section>
-<section class="Ss">
<h2 class="Ss" id="Including_binary_files"><a class="permalink" href="#Including_binary_files">Including
binary files</a></h2>
-You probably have some graphics you'd like to include. Use
+You probably have some graphics, level data, etc. you'd like to include. Use
<code class="Ic">INCBIN</code> to include a raw binary file as it is. If the
- file isn't found in the current directory, the include-path list passed to the
- linker on the command line will be searched.
+ file isn't found in the current directory, the include-path list passed to
+ <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a> (see the <code class="Fl">-i</code> option) on the
+ command line will be searched.
<div class="Bd Pp Bd-indent">
<pre>
INCBIN "titlepic.bin"
-INCBIN "sprites/hero.bin" ; UNIX
-INCBIN "sprites\\hero.bin" ; Windows
+INCBIN "sprites/hero.bin"
</pre>
</div>
<p class="Pp">You can also include only part of a file with
<code class="Ic">INCBIN</code>. The example below includes 256 bytes from
- data.bin starting from byte 78.</p>
+ data.bin, starting from byte 78.</p>
<div class="Bd Pp Bd-indent">
<pre>
INCBIN "data.bin",78,256
@@ -769,33 +1306,46 @@
</section>
<section class="Ss">
<h2 class="Ss" id="Unions"><a class="permalink" href="#Unions">Unions</a></h2>
-Unions allow multiple memory allocations to share the same space in memory, like
- unions in C. This allows you to easily reuse memory for different purposes,
- depending on the game's state.
-<p class="Pp">You create unions using the <code class="Ic">UNION</code>,
- <code class="Ic">NEXTU</code> and <code class="Ic">ENDU</code> keywords.
- <code class="Ic">NEXTU</code> lets you create a new block of allocations,
- and you may use it as many times within a union as necessary.</p>
+Unions allow multiple memory allocations to overlap, like unions in C. This does
+ not increase the amount of memory available, but allows re-using the same
+ memory region for different purposes.
+<p class="Pp">A union starts with a <code class="Ic">UNION</code> keyword, and
+ ends at the corresponding <code class="Ic">ENDU</code> keyword.
+ <code class="Ic">NEXTU</code> separates each block of allocations, and you
+ may use it as many times within a union as necessary.</p>
<div class="Bd Pp Bd-indent">
<pre>
-UNION
+ ; Let's say PC = $C0DE here
+ UNION
+ ; Here, PC = $C0DE
Name: ds 8
+ ; PC = $C0E6
Nickname: ds 8
-NEXTU
+ ; PC = $C0EE
+ NEXTU
+ ; PC is back to $C0DE
Health: dw
-Something: ds 3
+ ; PC = $C0E0
+Something: ds 6
+ ; And so on
Lives: db
-NEXTU
-Temporary: ds 19
-ENDU
+ NEXTU
+VideoBuffer: ds 19
+ ENDU
</pre>
</div>
-<p class="Pp">This union will use up 19 bytes, as this is the size of the
- largest block (the last one, containing 'Temporary'). Of course, as 'Name',
- 'Health', and 'Temporary' all point to the same memory locations, writes to
- any one of these will affect values read from the others.</p>
-<p class="Pp">Unions may be used in any section, but code and data may not be
- included.</p>
+<p class="Pp">In the example above, ‘Name, Health, VideoBuffer’
+ all have the same value, as do ‘Nickname’ and
+ ‘Lives’. Thus, keep in mind that <code class="Ic">ld [Health],
+ a</code> is identical to <code class="Ic">ld [Name], a</code>.</p>
+<p class="Pp">The size of this union is 19 bytes, as this is the size of the
+ largest block (the last one, containing ‘VideoBuffer’).
+ Nesting unions is possible, with each inner union's size being considered as
+ described above.</p>
+<p class="Pp">Unions may be used in any section, but inside them may only be
+ <code class="Ic">DS -</code> like commands (see
+ <a class="Sx" href="#Declaring_variables_in_a_RAM_section">Declaring
+ variables in a RAM section</a>).</p>
</section>
</section>
<section class="Sh">
@@ -802,11 +1352,134 @@
<h1 class="Sh" id="THE_MACRO_LANGUAGE"><a class="permalink" href="#THE_MACRO_LANGUAGE">THE
MACRO LANGUAGE</a></h1>
<section class="Ss">
+<h2 class="Ss" id="Invoking_macros"><a class="permalink" href="#Invoking_macros">Invoking
+ macros</a></h2>
+You execute the macro by inserting its name.
+<div class="Bd Pp Bd-indent">
+<pre>
+ add a,b
+ ld sp,hl
+ MyMacro ; This will be expanded
+ sub a,87
+</pre>
+</div>
+<p class="Pp">It's valid to call a macro from a macro (yes, even the same
+ one).</p>
+<p class="Pp">When <code class="Nm">rgbasm</code> sees
+ <code class="Ic">MyMacro</code> it will insert the macro definition (the
+ code enclosed in <code class="Ic">MACRO</code> /
+ <code class="Ic">ENDM</code>).</p>
+<p class="Pp">Suppose your macro contains a loop.</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+LoopyMacro: MACRO
+ xor a,a
+.loop ld [hl+],a
+ dec c
+ jr nz,.loop
+ENDM
+</pre>
+</div>
+<p class="Pp">This is fine, but only if you use the macro no more than once per
+ scope. To get around this problem, there is the escape sequence
+ <code class="Ic">\@</code> that expands to a unique string.</p>
+<p class="Pp"><code class="Ic">\@</code> also works in
+ <code class="Ic">REPT</code> blocks.</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+LoopyMacro: MACRO
+ xor a,a
+.loop\@ ld [hl+],a
+ dec c
+ jr nz,.loop\@
+ENDM
+</pre>
+</div>
+<p class="Pp"><b class="Sy">Important note</b>: Since a macro can call itself
+ (or a different macro that calls the first one), there can be circular
+ dependency problems. If this creates an infinite loop,
+ <code class="Nm">rgbasm</code> will error out once a certain depth is
+ reached. See the <code class="Fl">-r</code> command-line option in
+ <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>. Also, a macro can have inside an
+ <b class="Sy">EQUS</b> which references the same macro, which has the same
+ problem.</p>
+<p class="Pp">It's possible to pass arguments to macros as well! You retrieve
+ the arguments by using the escape sequences <code class="Ic">\1</code>
+ through <code class="Ic">\9</code>, <code class="Ic">\1</code> being the
+ first argument specified on the macro invocation.</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+LoopyMacro: MACRO
+ ld hl,\1
+ ld c,\2
+ xor a,a
+.loop\@ ld [hl+],a
+ dec c
+ jr nz,.loop\@
+ ENDM
+</pre>
+</div>
+<p class="Pp">Now I can call the macro specifying two arguments, the first being
+ the address and the second being a byte count. The generated code will then
+ reset all bytes in this range.</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+LoopyMacro MyVars,54
+</pre>
+</div>
+<p class="Pp">Arguments are passed as string equates, although there's no need
+ to enclose them in quotes. Thus, an expression will not be evaluated first
+ but kind of copy-pasted. This means that it's probably a very good idea to
+ use brackets around <code class="Ic">\1</code> to <code class="Ic">\9</code>
+ if you perform further calculations on them. For instance, consider the
+ following:</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+print_double: MACRO
+ PRINTV \1 * 2
+ENDM
+ print_double 1 + 2
+</pre>
+</div>
+<p class="Pp">The <code class="Ic">PRINTV</code> statement will expand to
+ ‘<code class="Li">PRINTV 1 + 2 * 2</code>’, which will print 5
+ and not 6 as you might have expected.</p>
+<p class="Pp">Line continuations work as usual inside macros or lists of macro
+ arguments. However, some characters need to be escaped, as in the following
+ example:</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+PrintMacro: MACRO
+ PRINTT \1
+ENDM
+
+ PrintMacro STRCAT("Hello "\, \
+ "world\\n")
+</pre>
+</div>
+<p class="Pp">The comma needs to be escaped to avoid it being treated as
+ separating the macro's arguments. The backslash ‘\’ (from
+ ‘\n’) also needs to be escaped because of the way
+ <code class="Nm">rgbasm</code> processes macro arguments.</p>
+<p class="Pp">In reality, up to 256 arguments can be passed to a macro, but you
+ can only use the first 9 like this. If you want to use the rest, you need to
+ use the <code class="Ic">SHIFT</code> command.</p>
+<p class="Pp"><code class="Ic">SHIFT</code> is a special command only available
+ in macros. Very useful in <code class="Ic">REPT</code> blocks. It will shift
+ the arguments by one to the left. <code class="Ic">\1</code> will get the
+ value of <code class="Ic">\2</code>, <code class="Ic">\2</code> will get the
+ value of <code class="Ic">\3</code>, and so forth.</p>
+<p class="Pp">This is the only way of accessing the value of arguments from 10
+ to 256.</p>
+<p class="Pp"><code class="Ic">SHIFT</code> can optionally be given an integer
+ parameter, and will apply the above shifting that number of times.</p>
+</section>
+<section class="Ss">
<h2 class="Ss" id="Printing_things_during_assembly"><a class="permalink" href="#Printing_things_during_assembly">Printing
things during assembly</a></h2>
-These three instructions type text and values to stdout. Useful for debugging
- macros or wherever you may feel the need to tell yourself some important
- information.
+The next four commands print text and values to the standard output. Useful for
+ debugging macros, or wherever you may feel the need to tell yourself some
+ important information.
<div class="Bd Pp Bd-indent">
<pre>
PRINTT "I'm the greatest programmer in the whole wide world\n"
@@ -817,29 +1490,33 @@
</div>
<dl class="Bl-inset">
<dt><a class="permalink" href="#PRINTT"><code class="Ic" id="PRINTT">PRINTT</code></a></dt>
- <dd>prints out a string.</dd>
+ <dd>prints out a string. Be careful to add a line feed (“\n”) at
+ the end, as it is not added automatically.</dd>
<dt><a class="permalink" href="#PRINTV"><code class="Ic" id="PRINTV">PRINTV</code></a></dt>
<dd>prints out an integer value in hexadecimal or, as in the example, the
result of a calculation. Unsurprisingly, you can also print out a constant
- symbols value.</dd>
+ symbol's value.</dd>
<dt><a class="permalink" href="#PRINTI"><code class="Ic" id="PRINTI">PRINTI</code></a></dt>
<dd>prints out a signed integer value.</dd>
<dt><a class="permalink" href="#PRINTF"><code class="Ic" id="PRINTF">PRINTF</code></a></dt>
<dd>prints out a fixed point value.</dd>
</dl>
+<p class="Pp">Be careful that none of those automatically print a line feed; if
+ you need one, use <code class="Ic">PRINTT \n</code>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Automatically_repeating_blocks_of_code"><a class="permalink" href="#Automatically_repeating_blocks_of_code">Automatically
repeating blocks of code</a></h2>
-Suppose you're feeling lazy and you want to unroll a time consuming loop.
+Suppose you want to unroll a time consuming loop without copy-pasting it.
<code class="Ic">REPT</code> is here for that purpose. Everything between
- <code class="Ic">REPT</code> and <code class="Ic">ENDR</code> will be repeated
- a number of times just as if you done a copy/paste operation yourself. The
- following example will assemble <b class="Sy">add a,c</b> four times:
+ <code class="Ic">REPT</code> and the matching <code class="Ic">ENDR</code>
+ will be repeated a number of times just as if you had done a copy/paste
+ operation yourself. The following example will assemble
+ ‘<code class="Li">add a,c</code>’ four times:
<div class="Bd Pp Bd-indent">
<pre>
REPT 4
-add a,c
+ add a,c
ENDR
</pre>
</div>
@@ -847,19 +1524,19 @@
on the fly:</p>
<div class="Bd Pp Bd-indent">
<pre>
-; --
-; -- Generate a 256 byte sine table with values between 0 and 128
-; --
-ANGLE SET 0.0
+; --
+; -- Generate a 256 byte sine table with values between 0 and 128
+; --
+ANGLE = 0.0
REPT 256
- DB (MUL(64.0,SIN(ANGLE))+64.0)>>16
-ANGLE SET ANGLE+256.0
+ db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
+ANGLE = ANGLE+256.0
ENDR
</pre>
</div>
-<p class="Pp"><code class="Ic">REPT</code> is also very useful in recursive
- macros and, as in macros, you can also use the special label operator
- <code class="Ic">\@</code>. REPT-blocks can be nested.</p>
+<p class="Pp">As in macros, you can also use the escape sequence
+ <code class="Ic">\@</code>. <code class="Ic">REPT</code> blocks can be
+ nested.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Aborting_the_assembly_process"><a class="permalink" href="#Aborting_the_assembly_process">Aborting
@@ -872,13 +1549,52 @@
line number.
<p class="Pp"><code class="Ic">FAIL</code> stops assembling immediately while
<code class="Ic">WARN</code> shows the message but continues afterwards.</p>
+<p class="Pp">If you need to ensure some assumption is correct when compiling,
+ you can use <code class="Ic">ASSERT</code> and
+ <code class="Ic">STATIC_ASSERT</code>. Syntax examples are given below:</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+Function:
+ xor a
+ASSERT LOW(Variable) == 0
+ ld h, HIGH(Variable)
+ ld l, a
+ ld a, [hli]
+ ; You can also indent this!
+ ASSERT BANK(OtherFunction) == BANK(Function)
+ call OtherFunction
+; Lowercase also works
+assert Variable + 1 == OtherVariable
+ ld c, [hl]
+ ret
+.end
+ ; If you specify one, a message will be printed
+ STATIC_ASSERT .end - Function < 256, "Function is too large!"
+</pre>
+</div>
+<p class="Pp">First, the difference between <code class="Ic">ASSERT</code> and
+ <code class="Ic">STATIC_ASSERT</code> is that the former is evaluated by
+ RGBASM if it can, otherwise by RGBLINK; but the latter is only ever
+ evaluated by RGBASM. If RGBASM cannot compute the value of the argument to
+ <code class="Ic">STATIC_ASSERT</code>, it will produce an error.</p>
+<p class="Pp">Second, as shown above, a string can be optionally added at the
+ end, to give insight into what the assertion is checking.</p>
+<p class="Pp">Finally, you can add one of <code class="Ic">WARN</code>,
+ <code class="Ic">FAIL</code> or <code class="Ic">FATAL</code> as the first
+ optional argument to either <code class="Ic">ASSERT</code> or
+ <code class="Ic">STATIC_ASSERT</code>. If the assertion fails,
+ <code class="Ic">WARN</code> will cause a simple warning (controlled by
+ <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a> flag <code class="Fl">-Wassert</code>) to be
+ emitted; <code class="Ic">FAIL</code> (the default) will cause a non-fatal
+ error; and <code class="Ic">FATAL</code> immediately aborts.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Including_other_source_files"><a class="permalink" href="#Including_other_source_files">Including
other source files</a></h2>
-Use <code class="Ic">INCLUDE</code> to process another assembler-file and then
+Use <code class="Ic">INCLUDE</code> to process another assembler file and then
return to the current file when done. If the file isn't found in the current
- directory the include-path list will be searched. You may nest
+ directory the include path list (see the <code class="Fl">-i</code> option in
+ <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>) will be searched. You may nest
<code class="Ic">INCLUDE</code> calls infinitely (or until you run out of
memory, whichever comes first).
<div class="Bd Pp Bd-indent">
@@ -891,9 +1607,9 @@
<h2 class="Ss" id="Conditional_assembling"><a class="permalink" href="#Conditional_assembling">Conditional
assembling</a></h2>
The four commands <code class="Ic">IF</code>, <code class="Ic">ELIF</code>,
- <code class="Ic">ELSE</code>, and <code class="Ic">ENDC</code> are used to
- conditionally assemble parts of your file. This is a powerful feature commonly
- used in macros.
+ <code class="Ic">ELSE</code>, and <code class="Ic">ENDC</code> let you have
+ <code class="Nm">rgbasm</code> skip over parts of your code depending on a
+ condition. This is a powerful feature commonly used in macros.
<div class="Bd Pp Bd-indent">
<pre>
IF NUM < 0
@@ -905,11 +1621,11 @@
ENDC
</pre>
</div>
-<p class="Pp">The <code class="Ic">ELIF</code> and <code class="Ic">ELSE</code>
- blocks are optional. <code class="Ic">IF</code> <span class="No">/</span>
- <code class="Ic">ELIF</code> <span class="No">/</span>
- <code class="Ic">ELSE</code> <span class="No">/</span>
- <code class="Ic">ENDC</code> blocks can be nested.</p>
+<p class="Pp">The <code class="Ic">ELIF</code> (standing for "else
+ if") and <code class="Ic">ELSE</code> blocks are optional.
+ <code class="Ic">IF</code> / <code class="Ic">ELIF</code> /
+ <code class="Ic">ELSE</code> / <code class="Ic">ENDC</code> blocks can be
+ nested.</p>
<p class="Pp">Note that if an <code class="Ic">ELSE</code> block is found before
an <code class="Ic">ELIF</code> block, the <code class="Ic">ELIF</code>
block will be ignored. All <code class="Ic">ELIF</code> blocks must go
@@ -917,464 +1633,7 @@
one <code class="Ic">ELSE</code> block, all of them but the first one are
ignored.</p>
</section>
-<section class="Ss">
-<h2 class="Ss" id="Integer_and_Boolean_expressions"><a class="permalink" href="#Integer_and_Boolean_expressions">Integer
- and Boolean expressions</a></h2>
-An expression can be composed of many things. Expressions are always evaluated
- using signed 32-bit math.
-<p class="Pp">The most basic expression is just a single number.</p>
-<p class="Pp"><b class="Sy">Numeric Formats</b></p>
-<p class="Pp">There are a number of numeric formats.</p>
-<p class="Pp"></p>
-<ul class="Bl-dash Bl-compact">
- <li>Hexadecimal: $0123456789ABCDEF. Case-insensitive</li>
- <li>Decimal: 0123456789</li>
- <li>Octal: &01234567</li>
- <li>Binary: %01</li>
- <li>Fixedpoint (16.16): 01234.56789</li>
- <li>Character constant: "ABYZ"</li>
- <li>Gameboy graphics: `0123</li>
-</ul>
-<p class="Pp">The last one, Gameboy graphics, is quite interesting and useful.
- The values are actually pixel values and it converts the
- “chunky” data to “planar” data as used in the
- Gameboy.</p>
-<div class="Bd Pp Bd-indent">
-<pre>
- DW `01012323
-</pre>
-</div>
-<p class="Pp">Admittedly, an expression with just a single number is quite
- boring. To spice things up a bit there are a few operators you can use to
- perform calculations between numbers.</p>
-<p class="Pp"><b class="Sy">Operators</b></p>
-<p class="Pp">A great number of operators you can use in expressions are
- available (listed in order of precedence):</p>
-<table class="Bl-column Bd-indent">
- <tr>
- <td><b class="Sy">Operator</b></td>
- <td><b class="Sy">Meaning</b></td>
- </tr>
- <tr>
- <td><a class="permalink" href="#(__&)"><code class="Li" id="(__&)">(
- )</code></a></td>
- <td>Precedence override</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#FUNC()"><code class="Li" id="FUNC()">FUNC()</code></a></td>
- <td>Function call</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#~_+_-"><code class="Li" id="~_+_-">~ +
- -</code></a></td>
- <td>Unary not/plus/minus</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#*_/__"><code class="Li" id="*_/__">* /
- %</code></a></td>
- <td>Multiply/divide/modulo</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#_____"><code class="Li" id="_____"><<
- >></code></a></td>
- <td>Shift left/right</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#&__&___"><code class="Li" id="&__&___">&
- | ^</code></a></td>
- <td>Binary and/or/xor</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#+_-"><code class="Li" id="+_-">+
- -</code></a></td>
- <td>Add/subtract</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#!=_==__="><code class="Li" id="!=_==__=">!=
- == <=</code></a></td>
- <td>Boolean comparison</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#_=____"><code class="Li" id="_=____">>=
- < ></code></a></td>
- <td>Boolean comparison (Same precedence as the others)</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#&&___"><code class="Li" id="&&___">&&
- ||</code></a></td>
- <td>Boolean and/or</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#!"><code class="Li" id="!">!</code></a></td>
- <td>Unary Boolean not</td>
- </tr>
-</table>
-<p class="Pp">The result of the boolean operators is zero if when FALSE and
- non-zero when TRUE. It is legal to use an integer as the condition for IF
- blocks. You can use symbols instead of numbers in your expression if you
- wish.</p>
-<p class="Pp">An expression is said to be constant when it doesn't change its
- value during linking. This basically means that you can't use labels in
- those expressions. The instructions in the macro-language all require
- expressions that are constant. The only exception is the subtraction of
- labels in the same section or labels that belong to sections with a fixed
- base addresses, all of which must be defined in the same source file (the
- calculation cannot be passed to the object file generated by the assembler).
- In this case, the result is a constant that can be calculated at assembly
- time.</p>
</section>
-<section class="Ss">
-<h2 class="Ss" id="Fixed__u2010_point_Expressions"><a class="permalink" href="#Fixed__u2010_point_Expressions">Fixed‐point
- Expressions</a></h2>
-Fixed point constants are basically normal 32-bit constants where the upper 16
- bits are used for the integer part and the lower 16 bits are used for the
- fraction (65536ths). This means that you can use them in normal integer
- expression, and some integer operators like plus and minus don't care whether
- the operands are integer or fixed-point. You can easily convert a fixed-point
- number to an integer by shifting it right 16 bits. It follows that you can
- convert an integer to a fixed-point number by shifting it left.
-<p class="Pp">Some things are different for fixed-point math, though, which is
- why you have the following functions to use:</p>
-<table class="Bl-column Bd-indent">
- <tr>
- <td><b class="Sy">Name</b></td>
- <td><b class="Sy">Operation</b></td>
- </tr>
- <tr>
- <td><code class="Fn">DIV</code>(<var class="Fa">x</var>,
- <var class="Fa">y</var>)</td>
- <td>
- <math class="eqn">
- <mrow><mi>x</mi><mo>÷</mo><mi>y</mi></mrow>
- </math>
- </td>
- </tr>
- <tr>
- <td><code class="Fn">MUL</code>(<var class="Fa">x</var>,
- <var class="Fa">y</var>)</td>
- <td>
- <math class="eqn">
- <mrow><mi>x</mi><mo>×</mo><mi>y</mi></mrow>
- </math>
- </td>
- </tr>
- <tr>
- <td><code class="Fn">SIN</code>(<var class="Fa">x</var>)</td>
- <td>
- <math class="eqn">
- <mrow><mi>sin</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
- </math>
- </td>
- </tr>
- <tr>
- <td><code class="Fn">COS</code>(<var class="Fa">x</var>)</td>
- <td>
- <math class="eqn">
- <mrow><mi>cos</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
- </math>
- </td>
- </tr>
- <tr>
- <td><code class="Fn">TAN</code>(<var class="Fa">x</var>)</td>
- <td>
- <math class="eqn">
- <mrow><mi>tan</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
- </math>
- </td>
- </tr>
- <tr>
- <td><code class="Fn">ASIN</code>(<var class="Fa">x</var>)</td>
- <td>
- <math class="eqn">
- <mrow><mi>asin</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
- </math>
- </td>
- </tr>
- <tr>
- <td><code class="Fn">ACOS</code>(<var class="Fa">x</var>)</td>
- <td>
- <math class="eqn">
- <mrow><mi>acos</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
- </math>
- </td>
- </tr>
- <tr>
- <td><code class="Fn">ATAN</code>(<var class="Fa">x</var>)</td>
- <td>
- <math class="eqn">
- <mrow><mi>atan</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
- </math>
- </td>
- </tr>
- <tr>
- <td><code class="Fn">ATAN2</code>(<var class="Fa">x</var>,
- <var class="Fa">y</var>)</td>
- <td>Angle between
- <math class="eqn">
- <mrow><mo>(</mo><mi>x</mi><mo>,</mo><mi>y</mi><mo>)</mo></mrow>
- </math>
- and
- <math class="eqn">
- <mrow><mo>(</mo><mn>1</mn><mo>,</mo><mn>0</mn><mo>)</mo></mrow>
- </math>
- </td>
- </tr>
-</table>
-<p class="Pp">These functions are extremely useful for automatic generation of
- various tables. A circle has 65536.0 degrees. Sine values are between [-1.0;
- 1.0].</p>
-<div class="Bd Pp Bd-indent">
-<pre>
-; --
-; -- Generate a 256 byte sine table with values between 0 and 128
-; --
-ANGLE SET 0.0
- REPT 256
- DB (MUL(64.0,SIN(ANGLE))+64.0)>>16
-ANGLE SET ANGLE+256.0
- ENDR
-</pre>
-</div>
-</section>
-<section class="Ss">
-<h2 class="Ss" id="String_Expressions"><a class="permalink" href="#String_Expressions">String
- Expressions</a></h2>
-The most basic string expression is any number of characters contained in double
- quotes ("for instance"). Like in C, the escape character is \, and
- there are a number of commands you can use within a string:
-<table class="Bl-column Bd-indent">
- <tr>
- <td><b class="Sy">String</b></td>
- <td><b class="Sy">Meaning</b></td>
- </tr>
- <tr>
- <td><a class="permalink" href="#__rs___rs_"><code class="Li" id="__rs___rs_">\\</code></a></td>
- <td>Backslash</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#__rs__"><code class="Li" id="__rs__">\"</code></a></td>
- <td>Double quote</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#__rs_,"><code class="Li" id="__rs_,">\,</code></a></td>
- <td>Comma</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#__rs___2"><code class="Li" id="__rs___2">\{</code></a></td>- <td>Curly bracket left</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#__rs___3"><code class="Li" id="__rs___3">\}</code></a></td>
- <td>Curly bracket right</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#__rs_n"><code class="Li" id="__rs_n">\n</code></a></td>
- <td>Newline ($0A)</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#__rs_t"><code class="Li" id="__rs_t">\t</code></a></td>
- <td>Tab ($09)</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#__rs_1_-___rs_9"><code class="Li" id="__rs_1_-___rs_9">\1
- - \9</code></a></td>
- <td>Macro argument (Only the body of a macros)</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#__rs_@"><code class="Li" id="__rs_@">\@</code></a></td>
- <td>Label name suffix (Only in the body of macros and repts)</td>
- </tr>
-</table>
-<p class="Pp">A funky feature is <b class="Sy">{symbol}</b> within a string.- This will examine the type of the symbol and insert its value accordingly.
- If symbol is a string symbol, the symbols value is simply copied. If it's a
- numeric symbol, the value is converted to hexadecimal notation and inserted
- as a string with a dollar prepended.</p>
-<p class="Pp">It's possible to change the way numeric symbols are converted by
- specifying a print type like so: <b class="Sy">{d:symbol}</b> Valid print- types are:</p>
-<table class="Bl-column Bd-indent">
- <tr>
- <td><b class="Sy">Print type</b></td>
- <td><b class="Sy">Format</b></td>
- <td><b class="Sy">Example</b></td>
- </tr>
- <tr>
- <td><a class="permalink" href="#d"><code class="Li" id="d">d</code></a></td>
- <td>Decimal</td>
- <td>42</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#x"><code class="Li" id="x">x</code></a></td>
- <td>Lowercase hexadecimal</td>
- <td>2a</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#X"><code class="Li" id="X">X</code></a></td>
- <td>Uppercase hexadecimal</td>
- <td>2A</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#b"><code class="Li" id="b">b</code></a></td>
- <td>Binary</td>
- <td>101010
- <p class="Pp">Note that print types should only be used with numeric values,
- not strings.</p>
- <p class="Pp">HINT: The <b class="Sy">{symbol}</b> construct can also be- used outside strings. The symbol's value is again inserted as a string.
- This is just a short way of doing “{symbol}”.</p>- <p class="Pp">Whenever the macro-language expects a string you can actually
- use a string expression. This consists of one or more of these function
- (yes, you can nest them). Note that some of these functions actually
- return an integer and can be used as part of an integer expression!</p>
- <table class="Bl-column">
- <tr>
- <td><b class="Sy">Name</b></td>
- <td><b class="Sy">Operation</b></td>
- </tr>
- <tr>
- <td><code class="Fn">STRLEN</code>(<var class="Fa">string</var>)</td>
- <td>Returns the number of characters in string</td>
- </tr>
- <tr>
- <td><code class="Fn">STRCAT</code>(<var class="Fa">str1</var>,
- <var class="Fa">str2</var>)</td>
- <td>Appends str2 to str1.</td>
- </tr>
- <tr>
- <td><code class="Fn">STRCMP</code>(<var class="Fa">str1</var>,
- <var class="Fa">str2</var>)</td>
- <td>Returns negative if str1 is alphabetically lower than str2, zero if
- they match, positive if str1 is greater than str2.</td>
- </tr>
- <tr>
- <td><code class="Fn">STRIN</code>(<var class="Fa">str1</var>,
- <var class="Fa">str2</var>)</td>
- <td>Returns the position of str2 in str1 or zero if it's not present
- (first character is position 1).</td>
- </tr>
- <tr>
- <td><code class="Fn">STRSUB</code>(<var class="Fa">str</var>,
- <var class="Fa">pos</var>, <var class="Fa">len</var>)</td>
- <td>Returns a substring from str starting at pos (first character is
- position 1) and with len characters.</td>
- </tr>
- <tr>
- <td><code class="Fn">STRUPR</code>(<var class="Fa">str</var>)</td>
- <td>Converts all characters in str to capitals and returns the new
- string.</td>
- </tr>
- <tr>
- <td><code class="Fn">STRLWR</code>(<var class="Fa">str</var>)</td>
- <td>Converts all characters in str to lower case and returns the new
- string.</td>
- </tr>
- </table>
- </td>
- </tr>
-</table>
-</section>
-<section class="Ss">
-<h2 class="Ss" id="Character_maps"><a class="permalink" href="#Character_maps">Character
- maps</a></h2>
-When writing text that is meant to be displayed in the Game Boy, the ASCII
- characters used in the source code may not be the same ones used in the
- tileset used in the ROM. For example, the tiles used for uppercase letters may
- be placed starting at tile index 128, which makes it difficult to add text
- strings to the ROM.
-<p class="Pp">Character maps allow the code to map strings up to 16 characters
- long to an abitrary 8-bit value:</p>
-<div class="Bd Pp Bd-indent">
-<pre>
-CHARMAP "<LF>", 10
-CHARMAP "&iacute", 20
-CHARMAP "A", 128
-</pre>
-</div>
-<p class="Pp">It is possible to create multiple character maps and then switch
- between them as desired. This can be used to encode debug information in
- ASCII and use a different encoding for other purposes, for example.
- Initially, there is one character map called <b class="Sy">main</b> and it
- is automatically selected as the current character map from the beginning.
- There is also a character map stack that can be used to save and restore
- which character map is currently active.</p>
-<table class="Bl-column">
- <tr>
- <td><b class="Sy">Command</b></td>
- <td><b class="Sy">Meaning</b></td>
- </tr>
- <tr>
- <td><a class="permalink" href="#NEWCHARMAP"><code class="Ic" id="NEWCHARMAP">NEWCHARMAP</code></a>
- <var class="Ar">name</var></td>
- <td>Creates a new, empty character map called
- <code class="Ic">name</code>.</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#NEWCHARMAP_2"><code class="Ic" id="NEWCHARMAP_2">NEWCHARMAP</code></a>
- <var class="Ar">name</var>, <var class="Ar">basename</var></td>
- <td>Creates a new character map called <code class="Ic">name</code>, copied
- from character map <code class="Ic">basename</code>.</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#SETCHARMAP"><code class="Ic" id="SETCHARMAP">SETCHARMAP</code></a>
- <var class="Ar">name</var></td>
- <td>Switch to character map <code class="Ic">name</code>.</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#PUSHC"><code class="Ic" id="PUSHC">PUSHC</code></a></td>
- <td>Push the current character map onto the stack.</td>
- </tr>
- <tr>
- <td><a class="permalink" href="#POPC"><code class="Ic" id="POPC">POPC</code></a></td>
- <td>Pop a character map off the stack and switch to it.</td>
- </tr>
-</table>
-<p class="Pp"><b class="Sy">Note:</b> Character maps affect all strings in the
- file from the point in which they are defined, until switching to a
- different character map. This means that any string that the code may want
- to print as debug information will also be affected by it.</p>
-<p class="Pp"><b class="Sy">Note:</b> The output value of a mapping can be 0. If
- this happens, the assembler will treat this as the end of the string and the
- rest of it will be trimmed.</p>
-</section>
-<section class="Ss">
-<h2 class="Ss" id="Other_functions"><a class="permalink" href="#Other_functions">Other
- functions</a></h2>
-There are a few other functions that do various useful things:
-<table class="Bl-column">
- <tr>
- <td><b class="Sy">Name</b></td>
- <td><b class="Sy">Operation</b></td>
- </tr>
- <tr>
- <td><code class="Fn">BANK</code>(<var class="Fa">arg</var>)</td>
- <td>Returns a bank number. If <var class="Ar">arg</var> is the symbol
- <code class="Ic">@</code>, this function returns the bank of the current
- section. If <var class="Ar">arg</var> is a string, it returns the bank of
- the section that has that name. If <var class="Ar">arg</var> is a label,
- it returns the bank number the label is in. For labels, as the linker has
- to resolve this, it can't be used when the expression has to be
- constant.</td>
- </tr>
- <tr>
- <td><code class="Fn">DEF</code>(<var class="Fa">label</var>)</td>
- <td>Returns TRUE if <var class="Ar">label</var> has been defined.</td>
- </tr>
- <tr>
- <td><code class="Fn">HIGH</code>(<var class="Fa">arg</var>)</td>
- <td>Returns the top 8 bits of the operand if <var class="Ar">arg</var> is a
- label or constant, or the top 8-bit register if it is a 16-bit
- register.</td>
- </tr>
- <tr>
- <td><code class="Fn">LOW</code>(<var class="Fa">arg</var>)</td>
- <td>Returns the bottom 8 bits of the operand if <var class="Ar">arg</var> is
- a label or constant, or the bottom 8-bit register if it is a 16-bit
- register (AF isn't a valid register for this function).</td>
- </tr>
-</table>
-</section>
-</section>
<section class="Sh">
<h1 class="Sh" id="MISCELLANEOUS"><a class="permalink" href="#MISCELLANEOUS">MISCELLANEOUS</a></h1>
<section class="Ss">
@@ -1381,8 +1640,9 @@
<h2 class="Ss" id="Changing_options_while_assembling"><a class="permalink" href="#Changing_options_while_assembling">Changing
options while assembling</a></h2>
<code class="Ic">OPT</code> can be used to change some of the options during
- assembling the source instead of defining them on the commandline.
-<p class="Pp"><code class="Ic">OPT</code> takes a comma-seperated list of
+ assembling from within the source, instead of defining them on the
+ command-line.
+<p class="Pp"><code class="Ic">OPT</code> takes a comma-separated list of
options as its argument:</p>
<div class="Bd Pp Bd-indent">
<pre>
@@ -1394,13 +1654,14 @@
</pre>
</div>
<p class="Pp">The options that OPT can modify are currently:
- <b class="Sy">b</b>, <b class="Sy">e</b> and <b class="Sy">g</b>.</p>
+ <code class="Cm">b</code>, <code class="Cm">g</code> and
+ <code class="Cm">p</code>.</p>
<p class="Pp"><code class="Ic">POPO</code> and <code class="Ic">PUSHO</code>
provide the interface to the option stack. <code class="Ic">PUSHO</code>
will push the current set of options on the option stack.
<code class="Ic">POPO</code> can then later be used to restore them. Useful
if you want to change some options in an include file and you don't want to
- destroy the options set by the program that included your file. The stacks
+ destroy the options set by the program that included your file. The stack's
number of entries is limited only by the amount of memory in your
machine.</p>
</section>
@@ -1408,13 +1669,13 @@
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
-<a class="Xr">rgbasm(1)</a>, <a class="Xr">rgblink(1)</a>,
- <a class="Xr">rgblink(5)</a>, <a class="Xr">rgbds(5)</a>,
- <a class="Xr">rgbds(7)</a>, <a class="Xr">gbz80(7)</a>
+<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.1.html">rgblink(1)</a>,
+ <a class="Xr" href="rgblink.5.html">rgblink(5)</a>, <a class="Xr" href="rgbds.5.html">rgbds(5)</a>,
+ <a class="Xr" href="rgbds.7.html">rgbds(7)</a>, <a class="Xr" href="gbz80.7.html">gbz80(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
-<code class="Nm">rgbds</code> was originally written by Carsten Sørensen
+<code class="Nm">rgbasm</code> was originally written by Carsten Sørensen
as part of the ASMotor package, and was later packaged in RGBDS by Justin
Lloyd. It is now maintained by a number of contributors at
<a class="Lk" href="https://github.com/rednex/rgbds">https://github.com/rednex/rgbds</a>.
@@ -1422,8 +1683,8 @@
</div>
<table class="foot">
<tr>
- <td class="foot-date">March 13, 2018</td>
- <td class="foot-os">RGBDS Manual</td>
+ <td class="foot-date">December 5, 2019</td>
+ <td class="foot-os">General</td>
</tr>
</table>
</body>
--- a/docs/rgbds.5.html
+++ b/docs/rgbds.5.html
@@ -8,8 +8,10 @@
SPDX-License-Identifier: MIT
-->
<head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+ <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
<title>RGBDS(5)</title>
</head>
<body>
@@ -24,15 +26,15 @@
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgbds</code> —
-<div class="Nd">object file format documentation</div>
+<span class="Nd">object file format documentation</span>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-This is the description of the object files used by <a class="Xr">rgbasm(1)</a>
- and <a class="Xr">rgblink(1)</a>. Please, note that the specifications may
- change. This toolchain is in development and new features may require adding
- more information to the current format, or modifying some fields, which would
- break compatibility with older versions.
+This is the description of the object files used by <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>
+ and <a class="Xr" href="rgblink.1.html">rgblink(1)</a>. <i class="Em">Please note that the
+ specifications may change.</i> This toolchain is in development and new
+ features may require adding more information to the current format, or
+ modifying some fields, which would break compatibility with older versions.
</section>
<section class="Sh">
<h1 class="Sh" id="FILE_STRUCTURE"><a class="permalink" href="#FILE_STRUCTURE">FILE
@@ -39,14 +41,15 @@
STRUCTURE</a></h1>
The following types are used:
<p class="Pp"><var class="Ar">LONG</var> is a 32‐bit integer stored in
- little‐endian format (Intel). <var class="Ar">BYTE</var> is an
- 8‐bit integer. <var class="Ar">STRING</var> is a 0‐terminated
- string of <var class="Ar">BYTE</var>.</p>
+ little‐endian format. <var class="Ar">BYTE</var> is an 8‐bit
+ integer. <var class="Ar">STRING</var> is a 0‐terminated string of
+ <var class="Ar">BYTE</var>.</p>
<div class="Bd Pp">
<pre>
; Header
-BYTE ID[4] ; "RGB6"
+BYTE ID[4] ; "RGB9"
+LONG RevisionNumber ; The format's revision number this file uses
LONG NumberOfSymbols ; The number of symbols used in this file
LONG NumberOfSections ; The number of sections used in this file
@@ -60,8 +63,10 @@
BYTE Type ; 0 = LOCAL symbol only used in this file.
; 1 = IMPORT this symbol from elsewhere
; 2 = EXPORT this symbol to other objects.
+ ; Bit 7 is independent from the above value, and
+ ; encodes whether the section is unionized
- IF Type != 1 ; If symbol is defined in this object file.
+ IF (Type & 0x7F) != 1 ; If symbol is defined in this object file.
STRING FileName ; File where the symbol is defined.
@@ -102,8 +107,8 @@
; decide (floating bank). This field is only valid for ROMX,
; VRAM, WRAMX and SRAM sections.
- LONG Align ; Alignment of this section (expressed as number of low bits
- ; to leave as 0). -1 if not defined.
+ LONG Align ; Alignment of this section, expressed as 1 << align. 1 if
+ ; not specified.
IF (Type == ROMX) || (Type == ROM0) ; Sections that can contain data.
@@ -118,8 +123,6 @@
STRING SourceFile ; Name of the source file (for printing error
; messages).
- LONG Line ; The line of the source file.
-
LONG Offset ; Offset into the section where patch should
; be applied (in bytes).
@@ -138,6 +141,34 @@
ENDC
ENDR
+
+; Assertions
+
+LONG NumberOfAssertions
+
+REPT NumberOfAssertions
+
+ STRING SourceFile ; Name of the source file (for printing the failure).
+
+ LONG Offset ; Offset into the section where the assertion is located.
+
+ BYTE Type ; 0 = Prints the message but allows linking to continue
+ ; 1 = Prints the message and evaluates other assertions,
+ ; but linking fails afterwards
+ ; 2 = Prints the message and immediately fails linking
+
+ LONG RPNSize ; Size of the RPN expression's buffer.
+
+ BYTE RPN[RPNSize] ; RPN expression, same as patches. Assert fails if == 0.
+
+ LONG SectionID ; The section number (of this object file) in which this
+ ; assert is defined. If it doesn't belong to any specific
+ ; section (like a constant), this field has the value -1.
+
+ STRING Message ; A message displayed when the assert fails. If set to
+ ; the empty string, a generic message is printed instead.
+
+ENDR
</pre>
</div>
<section class="Ss">
@@ -145,15 +176,15 @@
DATA</a></h2>
Expressions in the object file are stored as RPN. This is an expression of the
form “2 5 +”. This will first push the value “2”
- to the stack. Then “5”. The “+” operator pops two
+ to the stack, then “5”. The “+” operator pops two
arguments from the stack, adds them, and then pushes the result on the stack,
effectively replacing the two top arguments with their sum. In the RGB format,
- RPN expressions are stored as BYTEs with some bytes being special prefixes for
- integers and symbols.
+ RPN expressions are stored as <var class="Ar">BYTE</var>s with some bytes
+ being special prefixes for integers and symbols.
<table class="Bl-column Bd-indent">
<tr>
- <td><b class="Sy">Value</b></td>
- <td><b class="Sy">Meaning</b></td>
+ <th>Value</th>
+ <th>Meaning</th>
</tr>
<tr>
<td><a class="permalink" href="#$00"><code class="Li" id="$00">$00</code></a></td>
@@ -261,31 +292,36 @@
</tr>
<tr>
<td><a class="permalink" href="#$50"><code class="Li" id="$50">$50</code></a></td>
- <td><a class="permalink" href="#BANK(symbol),"><code class="Li" id="BANK(symbol),">BANK(symbol),</code></a>
+ <td><a class="permalink" href="#BANK(symbol)"><code class="Li" id="BANK(symbol)">BANK(symbol)</code></a>,
a <var class="Ar">LONG</var> Symbol ID follows.</td>
</tr>
<tr>
<td><a class="permalink" href="#$51"><code class="Li" id="$51">$51</code></a></td>
- <td><a class="permalink" href="#BANK(section_name),"><code class="Li" id="BANK(section_name),">BANK(section_name),</code></a>
+ <td><a class="permalink" href="#BANK(section_name)"><code class="Li" id="BANK(section_name)">BANK(section_name)</code></a>,
a null-terminated string follows.</td>
</tr>
<tr>
<td><a class="permalink" href="#$52"><code class="Li" id="$52">$52</code></a></td>
<td><a class="permalink" href="#Current_BANK()"><code class="Li" id="Current_BANK()">Current
- BANK()</code></a>.</td>
+ BANK()</code></a></td>
</tr>
<tr>
<td><a class="permalink" href="#$60"><code class="Li" id="$60">$60</code></a></td>
- <td><a class="permalink" href="#HRAMCheck."><code class="Li" id="HRAMCheck.">HRAMCheck.</code></a>
- Check if the value is in HRAM, AND it with 0xFF.</td>
+ <td><a class="permalink" href="#HRAMCheck"><code class="Li" id="HRAMCheck">HRAMCheck</code></a>.
+ Checks if the value is in HRAM, ANDs it with 0xFF.</td>
</tr>
<tr>
+ <td><a class="permalink" href="#$61"><code class="Li" id="$61">$61</code></a></td>
+ <td><a class="permalink" href="#RSTCheck"><code class="Li" id="RSTCheck">RSTCheck</code></a>.
+ Checks if the value is a RST vector, ORs it with 0xC7.</td>
+ </tr>
+ <tr>
<td><a class="permalink" href="#$80"><code class="Li" id="$80">$80</code></a></td>
<td><var class="Ar">LONG</var> integer follows.</td>
</tr>
<tr>
<td><a class="permalink" href="#$81"><code class="Li" id="$81">$81</code></a></td>
- <td><var class="Ar">LONG</var> Symbol ID follows.</td>
+ <td><var class="Ar">LONG</var> symbol ID follows.</td>
</tr>
</table>
</section>
@@ -293,8 +329,8 @@
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
-<a class="Xr">rgbasm(1)</a>, <a class="Xr">rgblink(1)</a>,
- <a class="Xr">rgbds(7)</a>, <a class="Xr">gbz80(7)</a>
+<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.1.html">rgblink(1)</a>,
+ <a class="Xr" href="rgbds.7.html">rgbds(7)</a>, <a class="Xr" href="gbz80.7.html">gbz80(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
@@ -307,7 +343,7 @@
<table class="foot">
<tr>
<td class="foot-date">January 26, 2018</td>
- <td class="foot-os">RGBDS Manual</td>
+ <td class="foot-os">General</td>
</tr>
</table>
</body>
--- a/docs/rgbds.7.html
+++ b/docs/rgbds.7.html
@@ -8,8 +8,10 @@
SPDX-License-Identifier: MIT
-->
<head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+ <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
<title>RGBDS(7)</title>
</head>
<body>
@@ -24,7 +26,7 @@
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgbds</code> —
-<div class="Nd">Rednex Game Boy Development System</div>
+<span class="Nd">Rednex Game Boy Development System</span>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
@@ -40,9 +42,9 @@
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
-<a class="Xr">rgbasm(1)</a>, <a class="Xr">rgbfix(1)</a>,
- <a class="Xr">rgblink(1)</a>, <a class="Xr">rgbds(5)</a>,
- <a class="Xr">gbz80(7)</a>
+<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>,
+ <a class="Xr" href="rgblink.1.html">rgblink(1)</a>, <a class="Xr" href="rgbds.5.html">rgbds(5)</a>,
+ <a class="Xr" href="gbz80.7.html">gbz80(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
@@ -71,7 +73,7 @@
<table class="foot">
<tr>
<td class="foot-date">March 7, 2018</td>
- <td class="foot-os">RGBDS Manual</td>
+ <td class="foot-os">General</td>
</tr>
</table>
</body>
--- a/docs/rgbfix.1.html
+++ b/docs/rgbfix.1.html
@@ -8,8 +8,10 @@
SPDX-License-Identifier: MIT
-->
<head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+ <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
<title>RGBFIX(1)</title>
</head>
<body>
@@ -24,7 +26,7 @@
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgbfix</code> —
-<div class="Nd">Game Boy checksum fixer</div>
+<span class="Nd">Game Boy header utility and checksum fixer</span>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
@@ -31,15 +33,16 @@
<table class="Nm">
<tr>
<td><code class="Nm">rgbfix</code></td>
- <td>[<code class="Fl">-CcjsVv</code>] [<code class="Fl">-f</code>
- <var class="Ar">fix_spec</var>] [<code class="Fl">-i</code>
- <var class="Ar">game_id</var>] [<code class="Fl">-k</code>
- <var class="Ar">licensee_str</var>] [<code class="Fl">-l</code>
- <var class="Ar">licensee_id</var>] [<code class="Fl">-m</code>
- <var class="Ar">mbc_type</var>] [<code class="Fl">-n</code>
- <var class="Ar">rom_version</var>] [<code class="Fl">-p</code>
- <var class="Ar">pad_value</var>] [<code class="Fl">-r</code>
- <var class="Ar">ram_size</var>] [<code class="Fl">-t</code>
+ <td>[<code class="Fl"><a href="#j">-j</a><a href="#s">s</a><a href="#V">V</a><a href="#v">v</a></code>] [<code class="Fl"><a href="#C">-C</a></code> |
+ <code class="Fl"><a href="#c">-c</a></code>] [<code class="Fl"><a href="#f">-f</a></code>
+ <var class="Ar">fix_spec</var>] [<code class="Fl"><a href="#i">-i</a></code>
+ <var class="Ar">game_id</var>] [<code class="Fl"><a href="#k">-k</a></code>
+ <var class="Ar">licensee_str</var>] [<code class="Fl"><a href="#l">-l</a></code>
+ <var class="Ar">licensee_id</var>] [<code class="Fl"><a href="#m">-m</a></code>
+ <var class="Ar">mbc_type</var>] [<code class="Fl"><a href="#n">-n</a></code>
+ <var class="Ar">rom_version</var>] [<code class="Fl"><a href="#p">-p</a></code>
+ <var class="Ar">pad_value</var>] [<code class="Fl"><a href="#r">-r</a></code>
+ <var class="Ar">ram_size</var>] [<code class="Fl"><a href="#t">-t</a></code>
<var class="Ar">title_str</var>] <var class="Ar">file</var></td>
</tr>
</table>
@@ -47,19 +50,28 @@
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
The <code class="Nm">rgbfix</code> program changes headers of Game Boy ROM
- images. It also performs other filetype operations, such as truncation. The
- arguments are as follows:
+ images. It also performs other correctness operations, such as padding.
+<p class="Pp">Note that options can be abbreviated as long as the abbreviation
+ is unambiguous: <code class="Fl">--verb</code> is
+ <code class="Fl">--verbose</code>, but
+ <code class="Fl">--ver</code> is invalid because it
+ could also be <code class="Fl">--version</code>. The
+ arguments are as follows:</p>
<dl class="Bl-tag">
- <dt><a class="permalink" href="#C"><code class="Fl" id="C">-C</code></a></dt>
+ <dt><a class="permalink" href="#C"><code class="Fl" id="C">-C</code></a>,
+ <code class="Fl">--color-only</code></dt>
<dd>Set the Game Boy Color–only flag: <span class="Ad">0x143</span> =
0xC0. If both this and the <code class="Fl">-c</code> flag are set, this
takes precedence.</dd>
- <dt><a class="permalink" href="#c"><code class="Fl" id="c">-c</code></a></dt>
+ <dt><a class="permalink" href="#c"><code class="Fl" id="c">-c</code></a>,
+ <code class="Fl">--color-compatible</code></dt>
<dd>Set the Game Boy Color–compatible flag:
<span class="Ad">0x143</span> = 0x80. If both this and the
<code class="Fl">-C</code> flag are set, <code class="Fl">-C</code> takes
precedence.</dd>
<dt><a class="permalink" href="#f"><code class="Fl" id="f">-f</code></a>
+ <var class="Ar">fix_spec</var>,
+ <code class="Fl">--fix-spec</code>
<var class="Ar">fix_spec</var></dt>
<dd>Fix certain header values that the Game Boy checks for correctness.
Alternatively, intentionally trash these values by writing their binary
@@ -84,45 +96,64 @@
</dl>
</dd>
<dt><a class="permalink" href="#i"><code class="Fl" id="i">-i</code></a>
+ <var class="Ar">game_id</var>,
+ <code class="Fl">--game-id</code>
<var class="Ar">game_id</var></dt>
<dd>Set the game ID string
(<span class="Ad">0x13F</span>–<span class="Ad">0x142</span>) to a
given string of exactly 4 characters. If both this and the title are set,
the game ID will overwrite the overlapping portion of the title.</dd>
- <dt><a class="permalink" href="#j"><code class="Fl" id="j">-j</code></a></dt>
+ <dt><a class="permalink" href="#j"><code class="Fl" id="j">-j</code></a>,
+ <code class="Fl">--non-japanese</code></dt>
<dd>Set the non-Japanese region flag: <span class="Ad">0x14A</span> = 1.</dd>
<dt><a class="permalink" href="#k"><code class="Fl" id="k">-k</code></a>
+ <var class="Ar">licensee_str</var>,
+ <code class="Fl">--new-licensee</code>
<var class="Ar">licensee_str</var></dt>
<dd>Set the new licensee string
(<span class="Ad">0x144</span>–<span class="Ad">0x145</span>) to a
given string, truncated to at most two characters.</dd>
<dt><a class="permalink" href="#l_2"><code class="Fl" id="l_2">-l</code></a>
+ <var class="Ar">licensee_id</var>,
+ <code class="Fl">--old-licensee</code>
<var class="Ar">licensee_id</var></dt>
<dd>Set the old licensee code, <span class="Ad">0x14B</span>, to a given value
from 0 to 0xFF. This value is deprecated and should be set to 0x33 in all
new software.</dd>
<dt><a class="permalink" href="#m"><code class="Fl" id="m">-m</code></a>
+ <var class="Ar">mbc_type</var>,
+ <code class="Fl">--mbc-type</code>
<var class="Ar">mbc_type</var></dt>
<dd>Set the MBC type, <span class="Ad">0x147</span>, to a given value from 0
to 0xFF.</dd>
<dt><a class="permalink" href="#n"><code class="Fl" id="n">-n</code></a>
+ <var class="Ar">rom_version</var>,
+ <code class="Fl">--rom-version</code>
<var class="Ar">rom_version</var></dt>
<dd>Set the ROM version, <span class="Ad">0x14C</span>, to a given value from
0 to 0xFF.</dd>
<dt><a class="permalink" href="#p"><code class="Fl" id="p">-p</code></a>
+ <var class="Ar">pad_value</var>,
+ <code class="Fl">--pad-value</code>
<var class="Ar">pad_value</var></dt>
<dd>Pad the image to a valid size with a given pad value from 0 to 0xFF.
- <code class="Nm">rgbfix</code> will automatically pick a size from 32KiB,
- 64KiB, 128KiB, ..., 8192KiB and give a warning thereafter. The cartridge
- size byte (<span class="Ad">0x148</span>) will be changed to reflect this
- new size.</dd>
+ <code class="Nm">rgbfix</code> will automatically pick a size from 32 KiB,
+ 64 KiB, 128 KiB, ..., 8192 KiB. The cartridge size byte
+ (<span class="Ad">0x148</span>) will be changed to reflect this new
+ size.</dd>
<dt><a class="permalink" href="#r"><code class="Fl" id="r">-r</code></a>
+ <var class="Ar">ram_size</var>,
+ <code class="Fl">--ram-size</code>
<var class="Ar">ram_size</var></dt>
<dd>Set the RAM size, <span class="Ad">0x149</span>, to a given value from 0
to 0xFF.</dd>
- <dt><a class="permalink" href="#s"><code class="Fl" id="s">-s</code></a></dt>
- <dd>Set the SGB flag: <span class="Ad">0x146</span> = 3.</dd>
+ <dt><a class="permalink" href="#s"><code class="Fl" id="s">-s</code></a>,
+ <code class="Fl">--sgb-compatible</code></dt>
+ <dd>Set the SGB flag: <span class="Ad">0x146</span> = 3. This flag will be
+ ignored by the SGB unless the old licensee code is 0x33!</dd>
<dt><a class="permalink" href="#t"><code class="Fl" id="t">-t</code></a>
+ <var class="Ar">title</var>,
+ <code class="Fl">--title</code>
<var class="Ar">title</var></dt>
<dd>Set the title string
(<span class="Ad">0x134</span>–<span class="Ad">0x143</span>) to a
@@ -131,9 +162,11 @@
(<code class="Fl">-c</code> or <code class="Fl">-C</code>). If both this
and the game ID are set, the game ID will overwrite the overlapping
portion of the title.</dd>
- <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a></dt>
+ <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a>,
+ <code class="Fl">--version</code></dt>
<dd>Print the version of the program and exit.</dd>
- <dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a></dt>
+ <dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a>,
+ <code class="Fl">--validate</code></dt>
<dd>Equivalent to <code class="Fl">-f</code> <code class="Cm">lhg</code>.</dd>
</dl>
</section>
@@ -140,19 +173,18 @@
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
Most values in the ROM header are only cosmetic. The bare minimum requirements
- for a workable image are checksums, the Nintendo logo, and (if needed) the
- CGB/SGB flags. It is a good idea to pad the image to a valid size as well
- (“valid” meaning a multiple of 32KiB).
-<p class="Pp">The following will make a plain, no-color Game Boy game without
+ for a workable program are the header checksum, the Nintendo logo, and (if
+ needed) the CGB/SGB flags. It is a good idea to pad the image to a valid size
+ as well (“valid” meaning a power of 2, times 32 KiB).
+<p class="Pp">The following will make a plain, non-color Game Boy game without
checking for a valid size:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent">$ rgbfix -v foo.gb</div>
<p class="Pp">The following will make a SGB-enabled, color-enabled game with a
- title of “foobar”, and pad it to a multiple of 32KiB. (The
- Game Boy itself does not use the title, but some emulators or ROM managers
- might.)</p>
+ title of “foobar”, and pad it to a valid size. (The Game Boy
+ itself does not use the title, but some emulators or ROM managers do.)</p>
<p class="Pp"></p>
-<div class="Bd Bd-indent">$ rgbfix -vcs -l 0x33 -p 0 -t foobar baz.gb</div>
+<div class="Bd Bd-indent">$ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb</div>
<p class="Pp">The following will duplicate the header (sans global checksum) of
the game “Survival Kids”:</p>
<p class="Pp"></p>
@@ -160,10 +192,15 @@
SURVIVALKIDAVKE SurvivalKids.gbc</div>
</section>
<section class="Sh">
+<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
+Please report bugs on
+ <a class="Lk" href="https://github.com/rednex/rgbds/issues">GitHub</a>.
+</section>
+<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
-<a class="Xr">rgbasm(1)</a>, <a class="Xr">rgblink(1)</a>,
- <a class="Xr">rgbds(7)</a>
+<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.1.html">rgblink(1)</a>,
+ <a class="Xr" href="rgbds.7.html">rgbds(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
@@ -175,8 +212,8 @@
</div>
<table class="foot">
<tr>
- <td class="foot-date">March 11, 2018</td>
- <td class="foot-os">RGBDS Manual</td>
+ <td class="foot-date">December 5, 2019</td>
+ <td class="foot-os">General</td>
</tr>
</table>
</body>
--- a/docs/rgbgfx.1.html
+++ b/docs/rgbgfx.1.html
@@ -8,8 +8,10 @@
SPDX-License-Identifier: MIT
-->
<head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+ <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
<title>RGBGFX(1)</title>
</head>
<body>
@@ -24,7 +26,7 @@
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgbgfx</code> —
-<div class="Nd">Game Boy graphics converter</div>
+<span class="Nd">Game Boy graphics converter</span>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
@@ -31,13 +33,16 @@
<table class="Nm">
<tr>
<td><code class="Nm">rgbgfx</code></td>
- <td>[<code class="Fl">-ADfFhmPTuVv</code>] [<code class="Fl">-o</code>
- <var class="Ar">outfile</var>] [<code class="Fl">-a</code>
- <var class="Ar">attrmap</var>] [<code class="Fl">-d</code>
- <var class="Ar">depth</var>] [<code class="Fl">-p</code>
- <var class="Ar">palfile</var>] [<code class="Fl">-t</code>
- <var class="Ar">tilemap</var>] [<code class="Fl">-x</code>
- <var class="Ar">tiles</var>] <var class="Ar">file</var></td>
+ <td>[<code class="Fl"><a href="#C">-C</a><a href="#D">D</a><a href="#h">h</a><a href="#m">m</a><a href="#u">u</a><a href="#V">V</a><a href="#v">v</a></code>] [<code class="Fl"><a href="#f">-f</a></code> |
+ <code class="Fl"><a href="#F">-F</a></code>] [<code class="Fl"><a href="#a">-a</a></code>
+ <var class="Ar">attrmap</var> | <code class="Fl"><a href="#A">-A</a></code>]
+ [<code class="Fl"><a href="#d">-d</a></code> <var class="Ar">depth</var>]
+ [<code class="Fl"><a href="#o">-o</a></code> <var class="Ar">out_file</var>]
+ [<code class="Fl"><a href="#p">-p</a></code> <var class="Ar">pal_file</var> |
+ <code class="Fl"><a href="#P">-P</a></code>] [<code class="Fl"><a href="#t">-t</a></code>
+ <var class="Ar">tilemap</var> | <code class="Fl"><a href="#T">-T</a></code>]
+ [<code class="Fl"><a href="#x">-x</a></code> <var class="Ar">tiles</var>]
+ <var class="Ar">file</var></td>
</tr>
</table>
</section>
@@ -54,9 +59,9 @@
the indices appropriate for each shade. Any undetermined indices are set
to respective default shades of gray. For example: if the bit depth is 2
and the image contains light gray and black, they become the second and
- fourth colors - and the first and third colors get set to default white
- and dark gray. If the image has multiple shades that map to the same
- index, the palette is instead determined as if the image had color.</li>
+ fourth colors, and the first and third colors get set to default white and
+ dark gray. If the image has multiple shades that map to the same index,
+ the palette is instead determined as if the image had color.</li>
<li>If the image has color (or the grayscale method failed), the colors are
sorted from lightest to darkest.</li>
</ul>
@@ -65,8 +70,16 @@
</section>
<section class="Sh">
<h1 class="Sh" id="ARGUMENTS"><a class="permalink" href="#ARGUMENTS">ARGUMENTS</a></h1>
+Note that options can be abbreviated as long as the abbreviation is unambiguous:
+ <code class="Fl">--verb</code> is
+ <code class="Fl">-</code> <code class="Fl">-verbose</code>, but
+ <code class="Fl">--ver</code> is invalid because it
+ could also be <code class="Fl">--version</code>. The
+ arguments are as follows:
<dl class="Bl-tag">
<dt><a class="permalink" href="#a"><code class="Fl" id="a">-a</code></a>
+ <var class="Ar">attrmap,</var>
+ <code class="Fl">--attr-map</code>
<var class="Ar">attrmap</var></dt>
<dd>Generate a file of tile mirroring attributes for OAM or (CGB-only)
background tiles. For each tile in the input file, a byte is written
@@ -73,27 +86,36 @@
representing the dimensions that the associated tile in the output file
should be mirrored. Useful in combination with <code class="Fl">-m</code>
to keep track the mirror direction of mirrored duplicate tiles.</dd>
- <dt><a class="permalink" href="#A"><code class="Fl" id="A">-A</code></a></dt>
+ <dt><a class="permalink" href="#A"><code class="Fl" id="A">-A</code></a>,
+ <code class="Fl">--output-attr-map</code></dt>
<dd>Same as <code class="Fl">-a</code>, but the attrmap file output name is
made by taking the input filename, removing the file extension, and
appending <span class="Pa">.attrmap</span>.</dd>
- <dt><a class="permalink" href="#C"><code class="Fl" id="C">-C</code></a></dt>
+ <dt><a class="permalink" href="#C"><code class="Fl" id="C">-C</code></a>,
+ <code class="Fl">--color-curve</code></dt>
<dd>Use the color curve of the Game Boy Color when generating palettes.</dd>
- <dt><a class="permalink" href="#D"><code class="Fl" id="D">-D</code></a></dt>
+ <dt><a class="permalink" href="#D"><code class="Fl" id="D">-D</code></a>,
+ <code class="Fl">--debug</code></dt>
<dd>Debug features are enabled.</dd>
- <dt><a class="permalink" href="#f"><code class="Fl" id="f">-f</code></a></dt>
- <dd>Fix the input PNG file to be a correctly indexed image.</dd>
- <dt><a class="permalink" href="#F"><code class="Fl" id="F">-F</code></a></dt>
- <dd>Same as <code class="Fl">-f</code>, but additionally, the supplied command
- line parameters are saved within the PNG and will be loaded and
- automatically used next time.</dd>
<dt><a class="permalink" href="#d"><code class="Fl" id="d">-d</code></a>
+ <var class="Ar">depth</var>,
+ <code class="Fl">--depth</code>
<var class="Ar">depth</var></dt>
<dd>The bit depth of the output image (either 1 or 2). By default, the bit
depth is 2 (two bits per pixel).</dd>
- <dt><a class="permalink" href="#h"><code class="Fl" id="h">-h</code></a></dt>
+ <dt><a class="permalink" href="#f"><code class="Fl" id="f">-f</code></a>,
+ <code class="Fl">--fix</code></dt>
+ <dd>Fix the input PNG file to be a correctly indexed image.</dd>
+ <dt><a class="permalink" href="#F"><code class="Fl" id="F">-F</code></a>,
+ <code class="Fl">--fix-and-save</code></dt>
+ <dd>Same as <code class="Fl">-f</code>, but additionally, the supplied command
+ line parameters are saved within the PNG and will be loaded and
+ automatically used next time.</dd>
+ <dt><a class="permalink" href="#h"><code class="Fl" id="h">-h</code></a>,
+ <code class="Fl">--horizontal</code></dt>
<dd>Lay out tiles horizontally rather than vertically.</dd>
- <dt><a class="permalink" href="#m"><code class="Fl" id="m">-m</code></a></dt>
+ <dt><a class="permalink" href="#m"><code class="Fl" id="m">-m</code></a>,
+ <code class="Fl">--mirror-tiles</code></dt>
<dd>Truncate tiles by checking for tiles that are mirrored versions of others
and omitting these from the output file. Useful with tilemaps and attrmaps
together to keep track of the duplicated tiles and the dimension mirrored.
@@ -100,38 +122,51 @@
Tiles are checked for horizontal, vertical, and horizontal-vertical
mirroring. Implies <code class="Fl">-u</code>.</dd>
<dt><a class="permalink" href="#o"><code class="Fl" id="o">-o</code></a>
- <var class="Ar">outfile</var></dt>
+ <var class="Ar">out_file</var>,
+ <code class="Fl">--output</code>
+ <var class="Ar">out_file</var></dt>
<dd>The name of the output file.</dd>
<dt><a class="permalink" href="#p"><code class="Fl" id="p">-p</code></a>
- <var class="Ar">palfile</var></dt>
- <dd>Output the image's palette in standard GBC palette format - bytes (8 bytes
+ <var class="Ar">pal_file</var>,
+ <code class="Fl">--palette</code>
+ <var class="Ar">pal_file</var></dt>
+ <dd>Output the image's palette in standard GBC palette format: bytes (8 bytes
for two bits per pixel, 4 bytes for one bit per pixel) containing the
RGB15 values in little-endian byte order. If the palette contains too few
colors, the remaining entries are set to black.</dd>
- <dt><a class="permalink" href="#P"><code class="Fl" id="P">-P</code></a></dt>
+ <dt><a class="permalink" href="#P"><code class="Fl" id="P">-P</code></a>,
+ <code class="Fl">--output-palette</code></dt>
<dd>Same as <code class="Fl">-p</code>, but the palette file output name is
made by taking the input PNG file's filename, removing the file extension,
and appending <span class="Pa">.pal</span>.</dd>
<dt><a class="permalink" href="#t"><code class="Fl" id="t">-t</code></a>
+ <var class="Ar">tilemap</var>,
+ <code class="Fl">--tilemap</code>
<var class="Ar">tilemap</var></dt>
<dd>Generate a file of tile indices. For each tile in the input file, a byte
is written representing the index of the associated tile in the output
file. Useful in combination with <code class="Fl">-u</code> or
<code class="Fl">-m</code> to keep track of duplicate tiles.</dd>
- <dt><a class="permalink" href="#T"><code class="Fl" id="T">-T</code></a></dt>
+ <dt><a class="permalink" href="#T"><code class="Fl" id="T">-T</code></a>,
+ <code class="Fl">--output-tilemap</code></dt>
<dd>Same as <code class="Fl">-t</code>, but the tilemap file output name is
made by taking the input filename, removing the file extension, and
appending <span class="Pa">.tilemap</span>.</dd>
- <dt><a class="permalink" href="#u"><code class="Fl" id="u">-u</code></a></dt>
+ <dt><a class="permalink" href="#u"><code class="Fl" id="u">-u</code></a>,
+ <code class="Fl">--unique-tiles</code></dt>
<dd>Truncate tiles by checking for tiles that are exact duplicates of others
and omitting these from the output file. Useful with tilemaps to keep
track of the duplicated tiles.</dd>
- <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a></dt>
+ <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a>,
+ <code class="Fl">--version</code></dt>
<dd>Print the version of the program and exit.</dd>
- <dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a></dt>
+ <dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a>,
+ <code class="Fl">--verbose</code></dt>
<dd>Verbose. Print errors when the command line parameters and the parameters
in the PNG file don't match.</dd>
<dt><a class="permalink" href="#x"><code class="Fl" id="x">-x</code></a>
+ <var class="Ar">tiles</var>,
+ <code class="Fl">--trim-end</code>
<var class="Ar">tiles</var></dt>
<dd>Trim the end of the output file by this many tiles.</dd>
</dl>
@@ -147,8 +182,8 @@
<p class="Pp"></p>
<div class="Bd Bd-indent">$ rgbgfx -T -u -o out.2bpp in.png</div>
<p class="Pp">The following creates a planar 2bpp file with only unique tiles
- (accounting for tile mirroring) and its associated tilemap
- <span class="Pa">out.tilemap</span> and attrmap
+ <span class="Pa">accounting for tile mirroring</span> and its associated
+ tilemap <span class="Pa">out.tilemap</span> and attrmap
<span class="Pa">out.attrmap</span>:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent">$ rgbgfx -A -T -m -o out.2bpp in.png</div>
@@ -157,11 +192,16 @@
<div class="Bd Bd-indent">$ rgbgfx in.png</div>
</section>
<section class="Sh">
+<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
+Please report bugs on
+ <a class="Lk" href="https://github.com/rednex/rgbds/issues">GitHub</a>.
+</section>
+<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
-<a class="Xr">rgbds(7)</a>, <a class="Xr">rgbasm(1)</a>,
- <a class="Xr">rgblink(1)</a>, <a class="Xr">rgbfix(1)</a>,
- <a class="Xr">gbz80(7)</a>
+<a class="Xr" href="rgbds.7.html">rgbds(7)</a>, <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>,
+ <a class="Xr" href="rgblink.1.html">rgblink(1)</a>, <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>,
+ <a class="Xr" href="gbz80.7.html">gbz80(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
@@ -172,8 +212,8 @@
</div>
<table class="foot">
<tr>
- <td class="foot-date">January 26, 2018</td>
- <td class="foot-os">RGBDS Manual</td>
+ <td class="foot-date">December 5, 2019</td>
+ <td class="foot-os">General</td>
</tr>
</table>
</body>
--- a/docs/rgblink.1.html
+++ b/docs/rgblink.1.html
@@ -3,13 +3,15 @@
<!-- This is an automatically generated file. Do not edit.
This file is part of RGBDS.
- Copyright (c) 2010-2018, Anthony J. Bentley and RGBDS contributors.
+ Copyright (c) 2010-2019, Anthony J. Bentley and RGBDS contributors.
SPDX-License-Identifier: MIT
-->
<head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+ <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
<title>RGBLINK(1)</title>
</head>
<body>
@@ -24,7 +26,7 @@
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgblink</code> —
-<div class="Nd">Game Boy linker</div>
+<span class="Nd">Game Boy linker</span>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
@@ -31,74 +33,107 @@
<table class="Nm">
<tr>
<td><code class="Nm">rgblink</code></td>
- <td>[<code class="Fl">-dtVw</code>] [<code class="Fl">-m</code>
- <var class="Ar">mapfile</var>] [<code class="Fl">-n</code>
- <var class="Ar">symfile</var>] [<code class="Fl">-O</code>
- <var class="Ar">overlayfile</var>] [<code class="Fl">-o</code>
- <var class="Ar">outfile</var>] [<code class="Fl">-p</code>
- <var class="Ar">pad_value</var>] [<code class="Fl">-s</code>
- <var class="Ar">symbol</var>] [<code class="Fl">-l</code>
- <var class="Ar">linkerscript</var>] <var class="Ar">file ...</var></td>
+ <td>[<code class="Fl"><a href="#d">-d</a><a href="#t">t</a><a href="#V">V</a><a href="#v">v</a><a href="#w">w</a></code>] [<code class="Fl"><a href="#l">-l</a></code>
+ <var class="Ar">linker_script</var>] [<code class="Fl"><a href="#m">-m</a></code>
+ <var class="Ar">map_file</var>] [<code class="Fl"><a href="#n">-n</a></code>
+ <var class="Ar">sym_file</var>] [<code class="Fl"><a href="#O">-O</a></code>
+ <var class="Ar">overlay_file</var>] [<code class="Fl"><a href="#o">-o</a></code>
+ <var class="Ar">out_file</var>] [<code class="Fl"><a href="#p">-p</a></code>
+ <var class="Ar">pad_value</var>] [<code class="Fl"><a href="#s">-s</a></code>
+ <var class="Ar">symbol</var>] <var class="Ar">file ...</var></td>
</tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-The <code class="Nm">rgblink</code> program links objects created by
- <a class="Xr">rgbasm(1)</a> into a single Game Boy ROM file.
-<p class="Pp">By default, ROM0 sections created by the assembler are placed in
- the 16KiB bank 0, and ROMX sections are placed in any bank except bank 0. If
- your ROM will only be 32KiB, you can use the <code class="Fl">-t</code>
- option to override this.</p>
-<p class="Pp">Similarly, WRAM0 sections are placed in the first 4KiB of WRAM
- bank 0 and WRAMX sections are placed in any bank except bank 0. If your ROM
- doesn't use banked WRAM you can use option <code class="Fl">-w</code> option
- to override this.</p>
-<p class="Pp">Also, if your ROM is designed for DMG, you can make sure that you
- don't use any prohibited section by using the option
- <code class="Fl">-d</code>, which implies <code class="Fl">-w</code> but
- also prohibits the use of VRAM bank 1.</p>
-<p class="Pp">The arguments are as follows:</p>
+The <code class="Nm">rgblink</code> program links RGB object files, typically
+ created by <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, into a single Game Boy ROM file. The
+ format is documented in <a class="Xr" href="rgbds.5.html">rgbds(5)</a>.
+<p class="Pp">ROM0 sections are placed in the first 16 KiB of the output ROM,
+ and ROMX sections are placed in any 16 KiB “bank” except the
+ first. If your ROM will only be 32 KiB, you can use the
+ <code class="Fl">-t</code> option to change this.</p>
+<p class="Pp">Similarly, WRAM0 sections are placed in the first 4 KiB of WRAM
+ (“bank 0”), and WRAMX sections are placed in any bank of the
+ last 4 KiB. If your ROM doesn't use banked WRAM, you can use the
+ <code class="Fl">-w</code> option to change this.</p>
+<p class="Pp">Also, if your ROM is designed for a monochrome Game Boy, you can
+ make sure that you don't use any incompatible section by using the
+ <code class="Fl">-d</code> option, which implies <code class="Fl">-w</code>
+ but also prohibits the use of banked VRAM.</p>
+<p class="Pp">Note that options can be abbreviated as long as the abbreviation
+ is unambiguous: <code class="Fl">--verb</code> is
+ <code class="Fl">--verbose</code>, but
+ <code class="Fl">--ver</code> is invalid because it
+ could also be <code class="Fl">--version</code>. The
+ arguments are as follows:</p>
<dl class="Bl-tag">
+ <dt><a class="permalink" href="#d"><code class="Fl" id="d">-d</code></a>,
+ <code class="Fl">--dmg</code></dt>
+ <dd>Enable DMG mode. Prohibit the use of sections that doesn't exist on a DMG,
+ such as WRAMX and VRAM bank 1. This option automatically enables
+ <code class="Fl">-w</code>.</dd>
+ <dt><a class="permalink" href="#l"><code class="Fl" id="l">-l</code></a>
+ <var class="Ar">linker_script,</var>
+ <code class="Fl">--linkerscript</code>
+ <var class="Ar">linker_script</var></dt>
+ <dd>Specify a linker script file that tells the linker how sections must be
+ placed in the ROM. The attributes assigned in the linker script must be
+ consistent with any assigned in the code. See <a class="Xr" href="rgblink.5.html">rgblink(5)</a>
+ for more information about the linker script format.</dd>
<dt><a class="permalink" href="#m"><code class="Fl" id="m">-m</code></a>
- <var class="Ar">mapfile</var></dt>
- <dd>Write a mapfile to the given filename.</dd>
+ <var class="Ar">map_file</var>,
+ <code class="Fl">--map</code>
+ <var class="Ar">map_file</var></dt>
+ <dd>Write a map file to the given filename, listing how sections and symbols
+ were assigned.</dd>
<dt><a class="permalink" href="#n"><code class="Fl" id="n">-n</code></a>
- <var class="Ar">symfile</var></dt>
- <dd>Write a symbol file to the given filename.</dd>
+ <var class="Ar">sym_file</var>,
+ <code class="Fl">--sym</code>
+ <var class="Ar">sym_file</var></dt>
+ <dd>Write a symbol file to the given filename, listing the address of all
+ exported symbols. Several external programs can use this information, for
+ example to help debugging ROMs.</dd>
<dt><a class="permalink" href="#O"><code class="Fl" id="O">-O</code></a>
- <var class="Ar">overlayfile</var></dt>
- <dd>The ROM image to overlay sections over. When an overlay ROM is provided,
- all sections must be fixed. This may be used to patch an existing
- binary.</dd>
+ <var class="Ar">overlay_file</var>,
+ <code class="Fl">--overlay</code>
+ <var class="Ar">overlay_file</var></dt>
+ <dd>If specified, sections will be overlaid "on top" of the provided
+ ROM image. In that case, all sections must be fixed. This may be used to
+ patch an existing binary.</dd>
<dt><a class="permalink" href="#o"><code class="Fl" id="o">-o</code></a>
- <var class="Ar">outfile</var></dt>
- <dd>Write ROM image to the given filename.</dd>
+ <var class="Ar">out_file</var>,
+ <code class="Fl">--output</code>
+ <var class="Ar">out_file</var></dt>
+ <dd>Write the ROM image to the given file.</dd>
<dt><a class="permalink" href="#p"><code class="Fl" id="p">-p</code></a>
+ <var class="Ar">pad_value</var>,
+ <code class="Fl">--pad</code>
<var class="Ar">pad_value</var></dt>
- <dd>When padding an image, pad with this value. The default is 0x00.</dd>
+ <dd>When inserting padding between sections, pad with this value. Has no
+ effect if <code class="Fl">-O</code> is specified. The default is 0.</dd>
<dt><a class="permalink" href="#s"><code class="Fl" id="s">-s</code></a>
- <var class="Ar">symbol</var></dt>
- <dd>???</dd>
- <dt><a class="permalink" href="#w"><code class="Fl" id="w">-w</code></a></dt>
- <dd>Expand the WRAM0 section size from 4KiB to the full 8KiB assigned to WRAM
- and prohibit the use of WRAMX sections.</dd>
- <dt><a class="permalink" href="#d"><code class="Fl" id="d">-d</code></a></dt>
- <dd>Enable DMG mode. Prohibit the use of sections that doesn't exist on a DMG,
- such as WRAMX and VRAM bank 1. This option automatically enables
- <code class="Fl">-w</code>.</dd>
- <dt><a class="permalink" href="#t"><code class="Fl" id="t">-t</code></a></dt>
- <dd>Expand the ROM0 section size from 16KiB to the full 32KiB assigned to ROM
- and prohibit the use of ROMX sections. Useful for ROMs that fit in 32
- KiB.</dd>
- <dt><a class="permalink" href="#l"><code class="Fl" id="l">-l</code></a>
- <var class="Ar">linkerscript</var></dt>
- <dd>Specify a linkerscript file that tells the linker how sections must be
- placed in the ROM. This file has priority over the attributes assigned in
- the source code, but they have to be consistent. See
- <a class="Xr">rgblink(5)</a> for more information about its format.</dd>
- <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a></dt>
+ <var class="Ar">symbol</var>,
+ <code class="Fl">--smart</code>
+ <var class="Ar">symbol</var></dt>
+ <dd>This option is ignored. It was supposed to perform smart linking but fell
+ into disrepair, and so has been removed. It will be reimplemented at some
+ point.</dd>
+ <dt><a class="permalink" href="#t"><code class="Fl" id="t">-t</code></a>,
+ <code class="Fl">--tiny</code></dt>
+ <dd>Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to
+ ROM and prohibit the use of ROMX sections. Useful for ROMs that fit in 32
+ KiB.</dd>
+ <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a>,
+ <code class="Fl">--version</code></dt>
<dd>Print the version of the program and exit.</dd>
+ <dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a>,
+ <code class="Fl">--verbose</code></dt>
+ <dd>Verbose: enable printing more information to standard error.</dd>
+ <dt><a class="permalink" href="#w"><code class="Fl" id="w">-w</code></a>,
+ <code class="Fl">--wramx</code></dt>
+ <dd>Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to
+ WRAM and prohibit the use of WRAMX sections.</dd>
</dl>
</section>
<section class="Sh">
@@ -107,18 +142,28 @@
image like so:
<p class="Pp"></p>
<div class="Bd Bd-indent">$ rgblink -o bar.gb foo.o</div>
-<p class="Pp">The resulting bar.gb will not have correct checksums (unless you
- put them in the assembly source). You should use <a class="Xr">rgbfix(1)</a>
- to fix these so that the program will actually run in a Game Boy:</p>
+<p class="Pp">The resulting <var class="Ar">bar.gb</var> will not have correct
+ checksums (unless you put them in the assembly source). You should use
+ <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a> to fix these so that the program will actually
+ run in a Game Boy:</p>
<p class="Pp"></p>
-<div class="Bd Bd-indent">$ rgbfix -v bar.gb</div>
+<div class="Bd Bd-indent"><code class="Li">$ rgbfix -v bar.gb</code></div>
+<p class="Pp">Here is a more complete example:</p>
+<p class="Pp"></p>
+<div class="Bd Bd-indent"><code class="Li">$ rgblink -o bin/game.gb -n
+ bin/game.sym -p 0xFF obj/title.o obj/engine.o</code></div>
</section>
<section class="Sh">
+<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
+Please report bugs on
+ <a class="Lk" href="https://github.com/rednex/rgbds/issues">GitHub</a>.
+</section>
+<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
-<a class="Xr">rgbasm(1)</a>, <a class="Xr">rgblink(5)</a>,
- <a class="Xr">rgbfix(1)</a>, <a class="Xr">rgbds(5)</a>,
- <a class="Xr">rgbds(7)</a>
+<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.5.html">rgblink(5)</a>,
+ <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>, <a class="Xr" href="rgbds.5.html">rgbds(5)</a>,
+ <a class="Xr" href="rgbds.7.html">rgbds(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
@@ -130,8 +175,8 @@
</div>
<table class="foot">
<tr>
- <td class="foot-date">January 26, 2018</td>
- <td class="foot-os">RGBDS Manual</td>
+ <td class="foot-date">November 26, 2019</td>
+ <td class="foot-os">General</td>
</tr>
</table>
</body>
--- a/docs/rgblink.5.html
+++ b/docs/rgblink.5.html
@@ -8,8 +8,10 @@
SPDX-License-Identifier: MIT
-->
<head>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+ <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
<title>RGBLINK(5)</title>
</head>
<body>
@@ -24,17 +26,15 @@
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgblink</code> —
-<div class="Nd">linkerscript file format</div>
+<span class="Nd">linker script file format</span>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-The linkerscript is an external file that allows the user to specify the order
- of sections without the need for doing so before assembling each object file.
-<p class="Pp">The placement of sections specified in the linkerscript is done
- before the sections whose placement is defined in the source code.</p>
-<p class="Pp">A linkerscript consists on a series of banks followed by a list of
- sections and, optionally, commands. They can be lowercase or uppercase, it
- is ignored. Any line can contain a comment starting with
+The linker script is an external file that allows the user to specify the order
+ of sections at link time and in a centralized manner.
+<p class="Pp">A linker script consists on a series of banks followed by a list
+ of sections and, optionally, commands. They can be lowercase or uppercase,
+ it is ignored. Any line can contain a comment starting with
‘<code class="Li">;</code>’ that ends at the end of the
line:</p>
<div class="Bd Pp Bd-indent">
@@ -50,42 +50,48 @@
</div>
<p class="Pp">Numbers can be in decimal or hexadecimal format (the prefix is
‘<code class="Li">$</code>’). It is an error if any section
- name or command are found before setting a bank.</p>
-<p class="Pp">Files can be included by using the <var class="Ar">INCLUDE</var>
- keyword followed by a string with the path of the file that has to be
+ name or command is found before setting a bank.</p>
+<p class="Pp">Files can be included by using the <code class="Ic">INCLUDE</code>
+ keyword, followed by a string with the path of the file that has to be
included.</p>
-<p class="Pp">The possible bank types are: <b class="Sy">ROM0</b>,
- <b class="Sy">ROMX</b>, <b class="Sy">VRAM</b>, <b class="Sy">WRAM0</b>,
- <b class="Sy">WRAMX</b>, <b class="Sy">OAM</b> and <b class="Sy">HRAM</b>.
- Types <b class="Sy">ROMX</b>, <b class="Sy">VRAM</b>,
- <b class="Sy">WRAMX</b> and <b class="Sy">SRAM</b> are banked, which means
- that it is needed to specify a bank after the type.</p>
+<p class="Pp">The possible bank types are: <code class="Cm">ROM0</code>,
+ <code class="Cm">ROMX</code>, <code class="Cm">VRAM</code>,
+ <code class="Cm">SRAM</code>, <code class="Cm">WRAM0</code>,
+ <code class="Cm">WRAMX</code>, <code class="Cm">OAM</code> and
+ <code class="Cm">HRAM</code>. Unless there is a single bank, which can occur
+ with types <code class="Cm">ROMX</code>, <code class="Cm">VRAM</code>,
+ <code class="Cm">SRAM</code> and <code class="Cm">WRAMX</code>, it is needed
+ to specify a bank number after the type.</p>
<p class="Pp">When a new bank statement is found, sections found after it will
- be placed right from the beginning of that bank. If the linkerscript
- switches to a different bank and then it comes back to the previous one it
- will continue from the last address that was used.</p>
-<p class="Pp">The only two commands are <var class="Ar">ORG</var> and
- <var class="Ar">ALIGN</var>:</p>
+ be placed right from the beginning of that bank. If the linker script
+ switches to a different bank and then comes back to a previous one, it will
+ continue from the last address that was used.</p>
+<p class="Pp">The only two commands are <code class="Ic">ORG</code> and
+ <code class="Ic">ALIGN</code>:</p>
<ul class="Bl-bullet">
- <li><var class="Ar">ORG</var> sets the address in which new sections will be
- placed. It can not be lower than the current address.</li>
- <li><var class="Ar">ALIGN</var> will increase the address until it is aligned
- to the specified boundary (it tries to set to 0 the number of bits
- specified after the command: <b class="Sy">ALIGN 8</b> will align to
- $100).</li>
+ <li><a class="permalink" href="#ORG"><code class="Ic" id="ORG">ORG</code></a>
+ sets the address in which new sections will be placed. It can not be lower
+ than the current address.</li>
+ <li><a class="permalink" href="#ALIGN"><code class="Ic" id="ALIGN">ALIGN</code></a>
+ will increase the address until it is aligned to the specified boundary
+ (it tries to set to 0 the number of bits specified after the command:
+ ‘<code class="Li">ALIGN 8</code>’ will align to $100).</li>
</ul>
-<p class="Pp">Note: The bank, alignment, address and type of sections can be
- specified both in the source code and in the linkerscript. For a section to
- be able to be placed with the linkerscript the bank must be left unassigned
- in the source code or be the same as the one specified in the linkerscript.
- The address and alignment musn't be set.</p>
+<p class="Pp"><b class="Sy">Note:</b> The bank, alignment, address and type of
+ sections can be specified both in the source code and in the linker script.
+ For a section to be able to be placed with the linker script, the bank,
+ address and alignment must be left unassigned in the source code or be
+ compatible with what is specified in the linker script. For example,
+ ‘<code class="Li">ALIGN[8]</code>’ in the source code is
+ compatible with ‘<code class="Li">ORG $F00</code>’ in the
+ linker script.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
-<a class="Xr">rgbasm(1)</a>, <a class="Xr">rgblink(1)</a>,
- <a class="Xr">rgbfix(1)</a>, <a class="Xr">rgbds(5)</a>,
- <a class="Xr">rgbds(7)</a>
+<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.1.html">rgblink(1)</a>,
+ <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>, <a class="Xr" href="rgbds.5.html">rgbds(5)</a>,
+ <a class="Xr" href="rgbds.7.html">rgbds(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
@@ -97,8 +103,8 @@
</div>
<table class="foot">
<tr>
- <td class="foot-date">January 27, 2018</td>
- <td class="foot-os">RGBDS Manual</td>
+ <td class="foot-date">November 26, 2019</td>
+ <td class="foot-os">General</td>
</tr>
</table>
</body>