mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 18:22:07 +00:00
1692 lines
72 KiB
HTML
1692 lines
72 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<!-- This is an automatically generated file. Do not edit.
|
|
This file is part of RGBDS.
|
|
|
|
Copyright (c) 2017-2018, Antonio Nino Diaz 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>RGBASM(5)</title>
|
|
</head>
|
|
<body>
|
|
<table class="head">
|
|
<tr>
|
|
<td class="head-ltitle">RGBASM(5)</td>
|
|
<td class="head-vol">File Formats Manual</td>
|
|
<td class="head-rtitle">RGBASM(5)</td>
|
|
</tr>
|
|
</table>
|
|
<div class="manual-text">
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
|
|
<code class="Nm">rgbasm</code> —
|
|
<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" 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="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>
|
|
<p class="Pp">Example:</p>
|
|
<div class="Bd Pp Bd-indent">
|
|
<pre>
|
|
John: ld a,87 ;Weee
|
|
</pre>
|
|
</div>
|
|
<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. 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, \ ; 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
|
|
strings it is needed to use <code class="Fn">STRCAT</code>() like this:</p>
|
|
<div class="Bd Pp Bd-indent">
|
|
<pre>
|
|
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="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 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="Ic" id="ROM0">ROM0</code></a></dt>
|
|
<dd>A ROM section. <var class="Ar">addr</var> can range from
|
|
<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
|
|
<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
|
|
<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 <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
|
|
<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 <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
|
|
<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">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="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 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. 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="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 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>
|
|
<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. 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 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>
|
|
RGBDS supports several types of symbols:
|
|
<dl class="Bl-hang">
|
|
<dt><b class="Sy">Label</b></dt>
|
|
<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">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 ; This syntax is deprecated,
|
|
AnotherGlobal: ; please use this instead
|
|
.locallabel
|
|
.yet_a_local:
|
|
AnotherGlobal.with_another_local:
|
|
ThisWillBeExported:: ; Note the two colons
|
|
ThisWillBeExported.too::
|
|
</pre>
|
|
</div>
|
|
<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><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>
|
|
SCREEN_WIDTH equ 160 ; In pixels
|
|
SCREEN_HEIGHT equ 144
|
|
</pre>
|
|
</div>
|
|
<p class="Pp">Note that colons ‘<code class="Li">:</code>’
|
|
following the name are not allowed.</p>
|
|
</dd>
|
|
<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 colons ‘<code class="Li">:</code>’
|
|
following the name are not allowed.</p>
|
|
</dd>
|
|
<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
|
|
str_pStuff RW 1
|
|
str_tData RB 256
|
|
str_bCount RB 1
|
|
str_SIZEOF RB 0
|
|
</pre>
|
|
</div>
|
|
<p class="Pp">The example defines four constants as if by:</p>
|
|
<div class="Bd Pp Bd-indent">
|
|
<pre>
|
|
str_pStuff EQU 0
|
|
str_tData EQU 2
|
|
str_bCount EQU 258
|
|
str_SIZEOF EQU 259
|
|
</pre>
|
|
</div>
|
|
<p class="Pp">There are five commands in the RS group of commands:</p>
|
|
<table class="Bl-column">
|
|
<tr>
|
|
<th>Command</th>
|
|
<th>Meaning</th>
|
|
</tr>
|
|
<tr>
|
|
<td><a class="permalink" href="#RSRESET"><code class="Ic" id="RSRESET">RSRESET</code></a></td>
|
|
<td>Equivalent to ‘<code class="Li">RSSET 0</code>’.</td>
|
|
</tr>
|
|
<tr>
|
|
<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>
|
|
</tr>
|
|
<tr>
|
|
<td><a class="permalink" href="#RB"><code class="Ic" id="RB">RB</code></a>
|
|
<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">to</span> <code class="Ic">_RS</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a class="permalink" href="#RW"><code class="Ic" id="RW">RW</code></a>
|
|
<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>
|
|
</tr>
|
|
<tr>
|
|
<td><a class="permalink" href="#RL"><code class="Ic" id="RL">RL</code></a>
|
|
<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>. (In
|
|
practice, this one cannot be used due to a bug).</td>
|
|
</tr>
|
|
</table>
|
|
<p class="Pp">Note that colons ‘<code class="Li">:</code>’
|
|
following the name are not allowed.</p>
|
|
</dd>
|
|
<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+]"
|
|
ld a,COUNTREG
|
|
|
|
PLAYER_NAME EQUS "\"John\""
|
|
db PLAYER_NAME
|
|
</pre>
|
|
</div>
|
|
<p class="Pp">This will be interpreted as:</p>
|
|
<div class="Bd Pp Bd-indent">
|
|
<pre>
|
|
ld a,[hl+]
|
|
db "John"
|
|
</pre>
|
|
</div>
|
|
<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"
|
|
</pre>
|
|
</div>
|
|
<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><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
|
|
ld a,80
|
|
call MyFunc
|
|
ENDM
|
|
</pre>
|
|
</div>
|
|
<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 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
|
|
routine defined in another file.
|
|
<p class="Pp">Exporting of symbols has to be done manually, importing is done
|
|
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. <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"
|
|
AOLer EQUS "Me too"
|
|
PURGE Kamikaze, AOLer
|
|
</pre>
|
|
</div>
|
|
<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
|
|
Symbols</a></h2>
|
|
The following symbols are defined by the assembler:
|
|
<table class="Bl-column Bd-indent">
|
|
<tr>
|
|
<th>Type</th>
|
|
<th>Name</th>
|
|
<th>Contents</th>
|
|
</tr>
|
|
<tr>
|
|
<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_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_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_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_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_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_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_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_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_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_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_8"><code class="Ic" id="EQU_8">EQU</code></a></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_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_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="#__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="#__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_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>
|
|
<section class="Sh">
|
|
<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. 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-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
|
|
<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="Including_binary_files"><a class="permalink" href="#Including_binary_files">Including
|
|
binary files</a></h2>
|
|
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
|
|
<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"
|
|
</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>
|
|
<div class="Bd Pp Bd-indent">
|
|
<pre>
|
|
INCBIN "data.bin",78,256
|
|
</pre>
|
|
</div>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Unions"><a class="permalink" href="#Unions">Unions</a></h2>
|
|
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>
|
|
; Let's say PC = $C0DE here
|
|
UNION
|
|
; Here, PC = $C0DE
|
|
Name: ds 8
|
|
; PC = $C0E6
|
|
Nickname: ds 8
|
|
; PC = $C0EE
|
|
NEXTU
|
|
; PC is back to $C0DE
|
|
Health: dw
|
|
; PC = $C0E0
|
|
Something: ds 6
|
|
; And so on
|
|
Lives: db
|
|
NEXTU
|
|
VideoBuffer: ds 19
|
|
ENDU
|
|
</pre>
|
|
</div>
|
|
<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">
|
|
<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>
|
|
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"
|
|
PRINTI (2 + 3) / 5
|
|
PRINTV $FF00 + $F0
|
|
PRINTF MUL(3.14, 3987.0)
|
|
</pre>
|
|
</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. 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
|
|
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 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 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
|
|
ENDR
|
|
</pre>
|
|
</div>
|
|
<p class="Pp">You can also use <code class="Ic">REPT</code> to generate tables
|
|
on the fly:</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)) + 64.0) >> 16
|
|
ANGLE = ANGLE+256.0
|
|
ENDR
|
|
</pre>
|
|
</div>
|
|
<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
|
|
the assembly process</a></h2>
|
|
<code class="Ic">FAIL</code> and <code class="Ic">WARN</code> can be used to
|
|
print errors and warnings respectively during the assembly process. This is
|
|
especially useful for macros that get an invalid argument.
|
|
<code class="Ic">FAIL</code> and <code class="Ic">WARN</code> take a string as
|
|
the only argument and they will print this string out as a normal error with a
|
|
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
|
|
return to the current file when done. If the file isn't found in the current
|
|
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">
|
|
<pre>
|
|
INCLUDE "irq.inc"
|
|
</pre>
|
|
</div>
|
|
</section>
|
|
<section class="Ss">
|
|
<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> 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
|
|
PRINTT "NUM < 0\n"
|
|
ELIF NUM == 0
|
|
PRINTT "NUM == 0\n"
|
|
ELSE
|
|
PRINTT "NUM > 0\n"
|
|
ENDC
|
|
</pre>
|
|
</div>
|
|
<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
|
|
before the <code class="Ic">ELSE</code> block. Also, if there is more than
|
|
one <code class="Ic">ELSE</code> block, all of them but the first one are
|
|
ignored.</p>
|
|
</section>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="MISCELLANEOUS"><a class="permalink" href="#MISCELLANEOUS">MISCELLANEOUS</a></h1>
|
|
<section class="Ss">
|
|
<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 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>
|
|
PUSHO
|
|
OPT g.oOX ;Set the GB graphics constants to use these characters
|
|
DW `..ooOOXX
|
|
POPO
|
|
DW `00112233
|
|
</pre>
|
|
</div>
|
|
<p class="Pp">The options that OPT can modify are currently:
|
|
<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 stack's
|
|
number of entries is limited only by the amount of memory in your
|
|
machine.</p>
|
|
</section>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
|
|
ALSO</a></h1>
|
|
<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">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>.
|
|
</section>
|
|
</div>
|
|
<table class="foot">
|
|
<tr>
|
|
<td class="foot-date">December 5, 2019</td>
|
|
<td class="foot-os">General</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|