ref: 3806eb313951425fe557624f8add92689020022c
dir: /docs/rgbasm.5.html/
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<style>
table.head, table.foot { width: 100%; }
td.head-rtitle, td.foot-os { text-align: right; }
td.head-vol { text-align: center; }
div.Pp { margin: 1ex 0ex; }
</style>
<link rel="stylesheet" href="mandoc.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">
<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1>
<b class="Nm" title="Nm">rgbasm</b> —
<span class="Nd" title="Nd">language documentation</span>
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
This is the full description of the language used by
<a class="Xr" title="Xr">rgbasm(1)</a>. The description of the instructions
supported by the GameBoy CPU is in <a class="Xr" title="Xr">gbz80(7)</a>.
<h1 class="Sh" title="Sh" id="GENERAL"><a class="selflink" href="#GENERAL">GENERAL</a></h1>
<h2 class="Ss" title="Ss" id="Syntax"><a class="selflink" href="#Syntax">Syntax</a></h2>
The syntax is line‐based, just as in any other assembler, meaning that
you do one instruction or pseudo‐op per line:
<div class="Pp"></div>
<div class="D1"><code class="Li">[<span class="Op"><var class="Ar" title="Ar">label</var></span>]
[<span class="Op"><var class="Ar" title="Ar">instruction</var></span>]
[<span class="Op"><var class="Ar" title="Ar">;comment</var></span>]</code></div>
<div class="Pp"></div>
Example:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
John: ld a,87 ;Weee
</pre>
</div>
<div class="Pp"></div>
All pseudo‐ops, mnemonics and registers (reserved keywords) are
case‐insensitive and all labels are case‐sensitive.
<div class="Pp"></div>
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.
<div class="Pp"></div>
Sometimes lines can be too long and it may be necessary to split them. The
syntax to do so is the following one:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
DB 1, 2, 3, 4 \
5, 6, 7, 8
</pre>
</div>
<div class="Pp"></div>
This works anywhere in the code except inside of strings. To split strings it is
needed to use <b class="Fn" title="Fn">STRCAT</b>() like this:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
DB STRCAT("Hello ", \
"world!")
</pre>
</div>
<h2 class="Ss" title="Ss" id="Sections"><a class="selflink" href="#Sections">Sections</a></h2>
<b class="Ic" title="Ic">SECTION</b> <var class="Ar" title="Ar">name</var>,
<var class="Ar" title="Ar">type</var>
<div class="Pp"></div>
<b class="Ic" title="Ic">SECTION</b> <var class="Ar" title="Ar">name</var>,
<var class="Ar" title="Ar">type</var>,
<var class="Ar" title="Ar">options</var>
<div class="Pp"></div>
<b class="Ic" title="Ic">SECTION</b> <var class="Ar" title="Ar">name</var>,
<var class="Ar" title="Ar">type</var>[<var class="Ar" title="Ar">addr</var>]
<div class="Pp"></div>
<b class="Ic" title="Ic">SECTION</b> <var class="Ar" title="Ar">name</var>,
<var class="Ar" title="Ar">type</var>[<var class="Ar" title="Ar">addr</var>],
<var class="Ar" title="Ar">options</var>
<div class="Pp"></div>
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.
<div class="Pp"></div>
<var class="Ar" title="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.
<div class="Pp"></div>
Possible section <var class="Ar" title="Ar">type</var>s are as follows:
<dl class="Bl-tag">
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#ROM0"><b class="Cm" title="Cm" id="ROM0">ROM0</b></a></dt>
<dd class="It-tag">A ROM section. <var class="Ar" title="Ar">addr</var> can
range from $0000–$3FFF (or $0000–$7FFF if tiny ROM mode is
enabled in <a class="Xr" title="Xr">rgblink(1)</a>).</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#ROMX"><b class="Cm" title="Cm" id="ROMX">ROMX</b></a></dt>
<dd class="It-tag">A banked ROM section. <var class="Ar" title="Ar">addr</var>
can range from $4000–$7FFF. <var class="Ar" title="Ar">bank</var>
can range from 1 to 511. Not available if tiny ROM mode is enabled in
<a class="Xr" title="Xr">rgblink(1)</a>.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#VRAM"><b class="Cm" title="Cm" id="VRAM">VRAM</b></a></dt>
<dd class="It-tag">A banked video RAM section.
<var class="Ar" title="Ar">addr</var> can range from $8000–$9FFF.
<var class="Ar" title="Ar">bank</var> can be 0 or 1 but bank 1 is
unavailable if DMG mode is enabled in
<a class="Xr" title="Xr">rgblink(1)</a>. Memory in this section can only
be allocated with <b class="Sy" title="Sy">DS</b>, not filled with
data.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#SRAM"><b class="Cm" title="Cm" id="SRAM">SRAM</b></a></dt>
<dd class="It-tag">A banked external (save) RAM section.
<var class="Ar" title="Ar">addr</var> can range from $A000–$BFFF.
<var class="Ar" title="Ar">bank</var> can range from 0 to 15. Memory in
this section can only be allocated with <b class="Sy" title="Sy">DS</b>,
not filled with data.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#WRAM0"><b class="Cm" title="Cm" id="WRAM0">WRAM0</b></a></dt>
<dd class="It-tag">A general-purpose RAM section.
<var class="Ar" title="Ar">addr</var> can range from $C000–$CFFF,
or $C000–$DFFF if DMG mode is enabled in
<a class="Xr" title="Xr">rgblink(1)</a>. Memory in this section can only
be allocated with <b class="Sy" title="Sy">DS</b>, not filled with
data.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#WRAMX"><b class="Cm" title="Cm" id="WRAMX">WRAMX</b></a></dt>
<dd class="It-tag">A banked general-purpose RAM section.
<var class="Ar" title="Ar">addr</var> can range from $D000–$DFFF.
<var class="Ar" title="Ar">bank</var> can range from 1 to 7. Memory in
this section can only be allocated with <b class="Sy" title="Sy">DS</b>,
not filled with data. Not available if DMG mode is enabled in
<a class="Xr" title="Xr">rgblink(1)</a>.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#OAM"><b class="Cm" title="Cm" id="OAM">OAM</b></a></dt>
<dd class="It-tag">An object attributes RAM section.
<var class="Ar" title="Ar">addr</var> can range from $FE00-$FE9F. Memory
in this section can only be allocated with
<b class="Sy" title="Sy">DS</b>, not filled with data.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#HRAM"><b class="Cm" title="Cm" id="HRAM">HRAM</b></a></dt>
<dd class="It-tag">A high RAM section. <var class="Ar" title="Ar">addr</var>
can range from $FF80–$FFFE. Memory in this section can only be
allocated with <b class="Sy" title="Sy">DS</b>, not filled with data.
<div class="Pp"></div>
<b class="Sy" title="Sy">Note</b>: If you use this method of allocating HRAM
the assembler will <i class="Em" title="Em">not</i> choose the short
addressing mode in the LD instructions <b class="Sy" title="Sy">LD
[$FF00+n8],A</b> and <b class="Sy" title="Sy">LD A,[$FF00+n8]</b> because
the actual address calculation is done by the linker. If you find this
undesirable you can use <b class="Ic" title="Ic">RSSET</b>,
<b class="Ic" title="Ic">RB</b>, or <b class="Ic" title="Ic">RW</b>
instead or use the <b class="Sy" title="Sy">LDH [$FF00+n8],A</b> and
<b class="Sy" title="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 <b class="Fl" title="Fl">-L</b> flag to
<a class="Xr" title="Xr">rgbasm(1)</a>.</dd>
</dl>
<div class="Pp"></div>
<var class="Ar" title="Ar">option</var>s are comma separated and may include:
<dl class="Bl-tag">
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#BANK"><b class="Cm" title="Cm" id="BANK">BANK</b></a>[<var class="Ar" title="Ar">bank</var>]</dt>
<dd class="It-tag">Specify which <var class="Ar" title="Ar">bank</var> for the
linker to place the section.</dd>
<dt class="It-tag"> </dt>
<dd class="It-tag"> </dd>
<dt class="It-tag"><a class="selflink" href="#ALIGN"><b class="Cm" title="Cm" id="ALIGN">ALIGN</b></a>[<var class="Ar" title="Ar">align</var>]</dt>
<dd class="It-tag">Place the section at an address whose
<var class="Ar" title="Ar">align</var> least‐significant bits are
zero. It is a syntax error to use this option with
<var class="Ar" title="Ar">addr</var>.</dd>
</dl>
<div class="Pp"></div>
If [<var class="Ar" title="Ar">addr</var>] is not specified, the section is
considered “floating”; the linker will automatically calculate
an appropriate address for the section. Similarly, if
<b class="Cm" title="Cm">BANK</b>[<var class="Ar" title="Ar">bank</var>] is
not specified, the linker will automatically find a bank with enough space.
<div class="Pp"></div>
Sections can also be placed by using a linkerscript file. The format is
described in <a class="Xr" title="Xr">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.
<div class="Pp"></div>
Section examples:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
SECTION "CoolStuff",ROMX
</pre>
</div>
<div class="Pp"></div>
This switches to the section called “CoolStuff” (or creates it if
it doesn't already exist) and defines it as a code section.
<div class="Pp"></div>
The following example defines a section that can be placed anywhere in any ROMX
bank:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
SECTION "CoolStuff",ROMX
</pre>
</div>
<div class="Pp"></div>
If it is needed, the the base address of the section can be specified:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
SECTION "CoolStuff",ROMX[$4567]
</pre>
</div>
<div class="Pp"></div>
An example with a fixed bank:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
SECTION "CoolStuff",ROMX[$4567],BANK[3]
</pre>
</div>
<div class="Pp"></div>
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:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
SECTION "CoolStuff",ROMX,BANK[7]
</pre>
</div>
<div class="Pp"></div>
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.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes
SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
</pre>
</div>
<div class="Pp"></div>
<b class="Sy" title="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 <b class="Ic" title="Ic">ORG</b> for example) that
uses <b class="Ic" title="Ic">@</b> for the section name and determines
correct section type etc as arguments for
<b class="Ic" title="Ic">SECTION</b>.
<h2 class="Ss" title="Ss" id="Section_Stack"><a class="selflink" href="#Section_Stack">Section
Stack</a></h2>
<b class="Ic" title="Ic">POPS</b> and <b class="Ic" title="Ic">PUSHS</b> provide
the interface to the section stack.
<div class="Pp"></div>
<b class="Ic" title="Ic">PUSHS</b> will push the current section context on the
section stack. <b class="Ic" title="Ic">POPS</b> 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.
<h1 class="Sh" title="Sh" id="SYMBOLS"><a class="selflink" href="#SYMBOLS">SYMBOLS</a></h1>
<h2 class="Ss" title="Ss" id="Symbols"><a class="selflink" href="#Symbols">Symbols</a></h2>
RGBDS supports several types of symbols:
<dl class="Bl-hang">
<dt class="It-hang"><b class="Sy" title="Sy">Label</b></dt>
<dd class="It-hang">Used to assign a memory location with a name</dd>
<dt class="It-hang"><b class="Sy" title="Sy">EQUate</b></dt>
<dd class="It-hang">Give a constant a name.</dd>
<dt class="It-hang"><b class="Sy" title="Sy">SET</b></dt>
<dd class="It-hang">Almost the same as EQUate, but you can change the value of
a SET during assembling.</dd>
<dt class="It-hang"><b class="Sy" title="Sy">Structure</b>
(<b class="Sy" title="Sy">the RS group</b>)</dt>
<dd class="It-hang">Define a structure easily.</dd>
<dt class="It-hang"><b class="Sy" title="Sy">String equate</b>
(<b class="Sy" title="Sy">EQUS</b>)</dt>
<dd class="It-hang">Give a frequently used string a name. Can also be used as
a mini-macro, like <b class="Fd" title="Fd">#define</b> in C.</dd>
<dt class="It-hang"><b class="Sy" title="Sy">MACRO</b></dt>
<dd class="It-hang">A block of code or pseudo instructions that you invoke
like any other mnemonic. You can give them arguments too.</dd>
</dl>
<div class="Pp"></div>
A symbol cannot have the same name as a reserved keyword.
<dl class="Bl-hang">
<dt class="It-hang"><b class="Sy" title="Sy">Label</b></dt>
<dd class="It-hang">
<div class="Pp"></div>
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.
<div class="Pp"></div>
This can be done in a number of ways:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
GlobalLabel
AnotherGlobal:
.locallabel
.yet_a_local:
AnotherGlobal.with_another_local:
ThisWillBeExported:: ;note the two colons
ThisWillBeExported.too::
</pre>
</div>
<div class="Pp"></div>
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.
<div class="Pp"></div>
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.
<div class="Pp"></div>
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.</dd>
<dt class="It-hang"><b class="Sy" title="Sy">EQU</b></dt>
<dd class="It-hang">
<div class="Pp"></div>
EQUates are constant symbols. They can, for example, be used for things such
as bit-definitions of hardware registers.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
EXIT_OK EQU $00
EXIT_FAILURE EQU $01
</pre>
</div>
<div class="Pp"></div>
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.</dd>
<dt class="It-hang"><b class="Sy" title="Sy">SET</b></dt>
<dd class="It-hang">
<div class="Pp"></div>
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.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
ARRAY_SIZE EQU 4
COUNT SET 2
COUNT SET ARRAY_SIZE+COUNT
</pre>
</div>
<div class="Pp"></div>
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.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
COUNT = 2
</pre>
</div>
</dd>
<dt class="It-hang"><b class="Sy" title="Sy">RSSET</b>,
<b class="Sy" title="Sy">RSRESET</b>, <b class="Sy" title="Sy">RB</b>,
<b class="Sy" title="Sy">RW</b></dt>
<dd class="It-hang">
<div class="Pp"></div>
The RS group of commands is a handy way of defining structures:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
RSRESET
str_pStuff RW 1
str_tData RB 256
str_bCount RB 1
str_SIZEOF RB 0
</pre>
</div>
<div class="Pp"></div>
The example defines four equated symbols:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
str_pStuff = 0
str_tData = 2
str_bCount = 258
str_SIZEOF = 259
</pre>
</div>
<div class="Pp"></div>
There are four commands in the RS group of commands:
<table class="Bl-column">
<colgroup>
<col style="min-width: 15.00ex;"/>
</colgroup>
<tr class="It-column">
<td class="It-column"><b class="Sy" title="Sy">Command</b></td>
<td class="It-column"><b class="Sy" title="Sy">Meaning</b></td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#RSRESET"><b class="Ic" title="Ic" id="RSRESET">RSRESET</b></a></td>
<td class="It-column">Resets the _RS counter to zero.</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#RSSET"><b class="Ic" title="Ic" id="RSSET">RSSET</b></a>
<var class="Ar" title="Ar">constexpr</var></td>
<td class="It-column">Sets the <b class="Ic" title="Ic">_RS</b>
<span class="No">counter to</span>
<var class="Ar" title="Ar">constexpr</var>.</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#RB"><b class="Ic" title="Ic" id="RB">RB</b></a>
<var class="Ar" title="Ar">constexpr</var></td>
<td class="It-column">Sets the preceding symbol to
<b class="Ic" title="Ic">_RS</b> <span class="No">and adds</span>
<var class="Ar" title="Ar">constexpr</var> <span class="No">to</span>
<b class="Ic" title="Ic">_RS</b>.</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#RW"><b class="Ic" title="Ic" id="RW">RW</b></a>
<var class="Ar" title="Ar">constexpr</var></td>
<td class="It-column">Sets the preceding symbol to
<b class="Ic" title="Ic">_RS</b> <span class="No">and adds</span>
<var class="Ar" title="Ar">constexpr</var> <span class="No">* 2
to</span> <b class="Ic" title="Ic">_RS.</b></td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#RL"><b class="Ic" title="Ic" id="RL">RL</b></a>
<var class="Ar" title="Ar">constexpr</var></td>
<td class="It-column">Sets the preceding symbol to
<b class="Ic" title="Ic">_RS</b> <span class="No">and adds</span>
<var class="Ar" title="Ar">constexpr</var> <span class="No">* 4
to</span> <b class="Ic" title="Ic">_RS.</b></td>
</tr>
</table>
<div class="Pp"></div>
Note that a colon (:) following the symbol-name is not allowed.
<b class="Sy" title="Sy">RS</b> symbols cannot be exported and imported.
They don't change their value during the link process.</dd>
<dt class="It-hang"><b class="Sy" title="Sy">EQUS</b></dt>
<dd class="It-hang">
<div class="Pp"></div>
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 <b class="Fd" title="Fd">#define .</b>
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
COUNTREG EQUS "[hl+]"
ld a,COUNTREG
PLAYER_NAME EQUS "\"John\""
db PLAYER_NAME
</pre>
</div>
<div class="Pp"></div>
Note that : following the label-name is not allowed, and that strings must
be quoted to be useful.
<div class="Pp"></div>
This will be interpreted as:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
ld a,[hl+]
db "John"
</pre>
</div>
<div class="Pp"></div>
String-symbols can also be used to define small one-line macros:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
PUSHA EQUS "push af\npush bc\npush de\npush hl\n"
</pre>
</div>
<div class="Pp"></div>
Note that a colon (:) following the label-name is not allowed. String
equates can't be exported or imported.
<div class="Pp"></div>
<b class="Sy" title="Sy">Important note</b>: An EQUS can be expanded to a
string that contains another EQUS and it will be expanded as well. This
means that, if you aren't careful, you may trap the assembler into an
infinite loop if there's a circular dependency in the expansions. Also, a
MACRO can have inside an EQUS which references the same MACRO, which has
the same problem.</dd>
<dt class="It-hang"><b class="Sy" title="Sy">MACRO</b></dt>
<dd class="It-hang">
<div class="Pp"></div>
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.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
MyMacro: MACRO
ld a,80
call MyFunc
ENDM
</pre>
</div>
<div class="Pp"></div>
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).
<div class="Pp"></div>
The above example is a very simple macro. You execute the macro by typing
its name.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
add a,b
ld sp,hl
MyMacro ;This will be expanded
sub a,87
</pre>
</div>
<div class="Pp"></div>
When the assembler meets MyMacro it will insert the macrodefinition (the
text enclosed in <b class="Ic" title="Ic">MACRO</b> /
<b class="Ic" title="Ic">ENDM</b>).
<div class="Pp"></div>
Suppose your macro contains a loop.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
LoopyMacro: MACRO
xor a,a
.loop ld [hl+],a
dec c
jr nz,.loop
ENDM
</pre>
</div>
<div class="Pp"></div>
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
<b class="Ic" title="Ic">\@</b> that you can append to your labels and it
will then expand to a unique string.
<div class="Pp"></div>
<b class="Ic" title="Ic">\@</b> also works in REPT-blocks should you have
any loops there.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
LoopyMacro: MACRO
xor a,a
.loop\@ ld [hl+],a
dec c
jr nz,.loop\@
ENDM
</pre>
</div>
<div class="Pp"></div>
<b class="Sy" title="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.
<div class="Pp"></div>
<b class="Sy" title="Sy">Macro Arguments</b>
<div class="Pp"></div>
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.
<div class="Pp"></div>
And I can do that. In macros you can get the arguments by using the special
macro string equates <b class="Ic" title="Ic">\1</b> through
<b class="Ic" title="Ic">\9</b>, <b class="Ic" title="Ic">\1</b> being the
first argument specified on the calling of the macro.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
LoopyMacro: MACRO
ld hl,\1
ld c,\2
xor a,a
.loop\@ ld [hl+],a
dec c
jr nz,.loop\@
ENDM
</pre>
</div>
<div class="Pp"></div>
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.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
LoopyMacro MyVars,54
</pre>
</div>
<div class="Pp"></div>
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
<b class="Ic" title="Ic">\1</b> to <b class="Ic" title="Ic">\9</b> if you
perform further calculations on them. For instance, if you pass 1 + 2 as
the first argument and then do <b class="Ic" title="Ic">PRINTV</b>
<b class="Ic" title="Ic">\1</b> * 2 you will get the value 5 on screen and
not 6 as you might have expected.
<div class="Pp"></div>
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 <b class="Ic" title="Ic">SHIFT</b>.
<div class="Pp"></div>
Line continuations work as usual inside macros or lists of arguments of
macros. Strings, however, are a bit trickier. The following example shows
how to use strings as arguments for a macro:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
PrintMacro : MACRO
PRINTT \1
ENDM
PrintMacro STRCAT(\"Hello\"\, \
\" world\\n\")
</pre>
</div>
<div class="Pp"></div>
<b class="Ic" title="Ic">SHIFT</b> is a special command only available in
macros. Very useful in REPT-blocks. It will shift the arguments by one to
the left. <b class="Ic" title="Ic">\1</b> will get the value of
<b class="Ic" title="Ic">\2</b>, <b class="Ic" title="Ic">\2</b> will get
the value in <b class="Ic" title="Ic">\3</b> and so forth.
<div class="Pp"></div>
This is the only way of accessing the value of arguments from 10 to
256.</dd>
</dl>
<h2 class="Ss" title="Ss" id="Exporting_and_importing_symbols"><a class="selflink" 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.
<div class="Pp"></div>
Exporting of symbols has to be done manually, importing is done automatically if
the assembler doesn't know where a symbol is defined.
<div class="Pp"></div>
<b class="Ic" title="Ic">EXPORT</b> <var class="Ar" title="Ar">label</var> [,
<var class="Ar" title="Ar">label</var> , <span class="No">...</span>]
<div class="Pp"></div>
The assembler will make label accessible to other files during the link process.
<div class="Pp"></div>
<b class="Ic" title="Ic">GLOBAL</b> <var class="Ar" title="Ar">label</var> [,
<var class="Ar" title="Ar">label</var> , <span class="No">...</span>]
<div class="Pp"></div>
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
<b class="Ic" title="Ic">EXPORT</b>.
<h2 class="Ss" title="Ss" id="Purging_symbols"><a class="selflink" href="#Purging_symbols">Purging
symbols</a></h2>
<b class="Ic" title="Ic">PURGE</b> 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.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
Kamikaze EQUS "I don't want to live anymore"
AOLer EQUS "Me too"
PURGE Kamikaze, AOLer
</pre>
</div>
<div class="Pp"></div>
Note that string symbols that are part of a <b class="Ic" title="Ic">PURGE</b>
command WILL NOT BE EXPANDED as the ONLY exception to this rule.
<h2 class="Ss" title="Ss" id="Predeclared_Symbols"><a class="selflink" href="#Predeclared_Symbols">Predeclared
Symbols</a></h2>
The following symbols are defined by the assembler:
<table class="Bl-column" style="margin-left: 6.00ex;">
<colgroup>
<col style="width: 7.80ex;"/>
<col style="min-width: 18.00ex;"/>
</colgroup>
<tr class="It-column">
<td class="It-column"><b class="Sy" title="Sy">Type</b></td>
<td class="It-column"><b class="Sy" title="Sy">Name</b></td>
<td class="It-column"><b class="Sy" title="Sy">Contents</b></td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#@"><b class="Ic" title="Ic" id="@">@</b></a></td>
<td class="It-column">PC value</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#_PI"><b class="Ic" title="Ic" id="_PI">_PI</b></a></td>
<td class="It-column">Fixed point π</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#SET"><b class="Ic" title="Ic" id="SET">SET</b></a></td>
<td class="It-column"><a class="selflink" href="#_RS"><b class="Ic" title="Ic" id="_RS">_RS</b></a></td>
<td class="It-column">_RS Counter</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#_NARG"><b class="Ic" title="Ic" id="_NARG">_NARG</b></a></td>
<td class="It-column">Number of arguments passed to macro</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__LINE__"><b class="Ic" title="Ic" id="__LINE__">__LINE__</b></a></td>
<td class="It-column">The current line number</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQUS"><b class="Ic" title="Ic" id="EQUS">EQUS</b></a></td>
<td class="It-column"><a class="selflink" href="#__FILE__"><b class="Ic" title="Ic" id="__FILE__">__FILE__</b></a></td>
<td class="It-column">The current filename</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQUS"><b class="Ic" title="Ic" id="EQUS">EQUS</b></a></td>
<td class="It-column"><a class="selflink" href="#__DATE__"><b class="Ic" title="Ic" id="__DATE__">__DATE__</b></a></td>
<td class="It-column">Today's date</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQUS"><b class="Ic" title="Ic" id="EQUS">EQUS</b></a></td>
<td class="It-column"><a class="selflink" href="#__TIME__"><b class="Ic" title="Ic" id="__TIME__">__TIME__</b></a></td>
<td class="It-column">The current time</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQUS"><b class="Ic" title="Ic" id="EQUS">EQUS</b></a></td>
<td class="It-column"><a class="selflink" href="#__ISO_8601_LOCAL__"><b class="Ic" title="Ic" id="__ISO_8601_LOCAL__">__ISO_8601_LOCAL__</b></a></td>
<td class="It-column">ISO 8601 timestamp (local)</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQUS"><b class="Ic" title="Ic" id="EQUS">EQUS</b></a></td>
<td class="It-column"><a class="selflink" href="#__ISO_8601_UTC__"><b class="Ic" title="Ic" id="__ISO_8601_UTC__">__ISO_8601_UTC__</b></a></td>
<td class="It-column">ISO 8601 timestamp (UTC)</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__UTC_YEAR__"><b class="Ic" title="Ic" id="__UTC_YEAR__">__UTC_YEAR__</b></a></td>
<td class="It-column">Today's year</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__UTC_MONTH__"><b class="Ic" title="Ic" id="__UTC_MONTH__">__UTC_MONTH__</b></a></td>
<td class="It-column">Today's month number, 1-12</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__UTC_DAY__"><b class="Ic" title="Ic" id="__UTC_DAY__">__UTC_DAY__</b></a></td>
<td class="It-column">Today's day of the month, 1-31</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__UTC_HOUR__"><b class="Ic" title="Ic" id="__UTC_HOUR__">__UTC_HOUR__</b></a></td>
<td class="It-column">Current hour, 0-23</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__UTC_MINUTE__"><b class="Ic" title="Ic" id="__UTC_MINUTE__">__UTC_MINUTE__</b></a></td>
<td class="It-column">Current minute, 0-59</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__UTC_SECOND__"><b class="Ic" title="Ic" id="__UTC_SECOND__">__UTC_SECOND__</b></a></td>
<td class="It-column">Current second, 0-59</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__RGBDS_MAJOR__"><b class="Ic" title="Ic" id="__RGBDS_MAJOR__">__RGBDS_MAJOR__</b></a></td>
<td class="It-column">Major version number of RGBDS.</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__RGBDS_MINOR__"><b class="Ic" title="Ic" id="__RGBDS_MINOR__">__RGBDS_MINOR__</b></a></td>
<td class="It-column">Minor version number of RGBDS.</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#EQU"><b class="Ic" title="Ic" id="EQU">EQU</b></a></td>
<td class="It-column"><a class="selflink" href="#__RGBDS_PATCH__"><b class="Ic" title="Ic" id="__RGBDS_PATCH__">__RGBDS_PATCH__</b></a></td>
<td class="It-column">Patch version number of RGBDS.</td>
</tr>
</table>
<h1 class="Sh" title="Sh" id="DEFINING_DATA"><a class="selflink" href="#DEFINING_DATA">DEFINING
DATA</a></h1>
<h2 class="Ss" title="Ss" id="Defining_constant_data"><a class="selflink" href="#Defining_constant_data">Defining
constant data</a></h2>
<b class="Ic" title="Ic">DB</b> defines a list of bytes that will be stored in
the final image. Ideal for tables and text (which is not zero-terminated).
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
DB 1,2,3,4,"This is a string"
</pre>
</div>
<div class="Pp"></div>
Alternatively, you can use <b class="Ic" title="Ic">DW</b> to store a list of
words (16-bits) or <b class="Ic" title="Ic">DL</b> to store a list of
doublewords/longs (32-bits). Strings are not allowed as arguments to
<b class="Ic" title="Ic">DW</b> and <b class="Ic" title="Ic">DL</b>.
<div class="Pp"></div>
You can also use <b class="Ic" title="Ic">DB</b>,
<b class="Ic" title="Ic">DW</b> and <b class="Ic" title="Ic">DL</b> without
arguments, or leaving empty elements at any point in the list. This works
exactly like <b class="Sy" title="Sy">DS 1</b>, <b class="Sy" title="Sy">DS
2</b> and <b class="Sy" title="Sy">DS 4</b> respectively. Consequently,
<b class="Ic" title="Ic">DB</b>, <b class="Ic" title="Ic">DW</b> and
<b class="Ic" title="Ic">DL</b> can be used in a
<b class="Sy" title="Sy">WRAM0</b> <span class="No">/</span>
<b class="Sy" title="Sy">WRAMX</b> <span class="No">/</span>
<b class="Sy" title="Sy">HRAM</b> <span class="No">/</span>
<b class="Sy" title="Sy">VRAM</b> <span class="No">/</span>
<b class="Sy" title="Sy">SRAM</b> section.
<h2 class="Ss" title="Ss" id="Declaring_variables_in_a_RAM_section"><a class="selflink" href="#Declaring_variables_in_a_RAM_section">Declaring
variables in a RAM section</a></h2>
<b class="Ic" title="Ic">DS</b> 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 <b class="Ic" title="Ic">DB</b>,
<b class="Ic" title="Ic">DW</b> and <b class="Ic" title="Ic">DL</b> without
any arguments instead.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
DS str_SIZEOF ;allocate str_SIZEOF bytes
</pre>
</div>
<h2 class="Ss" title="Ss" id="Including_binary_files"><a class="selflink" href="#Including_binary_files">Including
binary files</a></h2>
You probably have some graphics you'd like to include. Use
<b class="Ic" title="Ic">INCBIN</b> 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.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
INCBIN "titlepic.bin"
INCBIN "sprites/hero.bin" ; UNIX
INCBIN "sprites\\hero.bin" ; Windows
</pre>
</div>
<div class="Pp"></div>
You can also include only part of a file with
<b class="Ic" title="Ic">INCBIN</b>. The example below includes 256 bytes from
data.bin starting from byte 78.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
INCBIN "data.bin",78,256
</pre>
</div>
<h2 class="Ss" title="Ss" id="Unions"><a class="selflink" 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.
<div class="Pp"></div>
You create unions using the <b class="Ic" title="Ic">UNION</b>,
<b class="Ic" title="Ic">NEXTU</b> and <b class="Ic" title="Ic">ENDU</b>
keywords. <b class="Ic" title="Ic">NEXTU</b> lets you create a new block of
allocations, and you may use it as many times within a union as necessary.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
UNION
Name: ds 8
Nickname: ds 8
NEXTU
Health: dw
Something: ds 3
Lives: db
NEXTU
Temporary: ds 19
ENDU
</pre>
</div>
<div class="Pp"></div>
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.
<div class="Pp"></div>
Unions may be used in any section, but code and data may not be included.
<h1 class="Sh" title="Sh" id="THE_MACRO_LANGUAGE"><a class="selflink" href="#THE_MACRO_LANGUAGE">THE
MACRO LANGUAGE</a></h1>
<h2 class="Ss" title="Ss" id="Printing_things_during_assembly"><a class="selflink" 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.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
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 class="It-inset"><a class="selflink" href="#PRINTT"><b class="Ic" title="Ic" id="PRINTT">PRINTT</b></a></dt>
<dd class="It-inset">prints out a string.</dd>
<dt class="It-inset"><a class="selflink" href="#PRINTV"><b class="Ic" title="Ic" id="PRINTV">PRINTV</b></a></dt>
<dd class="It-inset">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>
<dt class="It-inset"><a class="selflink" href="#PRINTI"><b class="Ic" title="Ic" id="PRINTI">PRINTI</b></a></dt>
<dd class="It-inset">prints out a signed integer value.</dd>
<dt class="It-inset"><a class="selflink" href="#PRINTF"><b class="Ic" title="Ic" id="PRINTF">PRINTF</b></a></dt>
<dd class="It-inset">prints out a fixed point value.</dd>
</dl>
<h2 class="Ss" title="Ss" id="Automatically_repeating_blocks_of_code"><a class="selflink" 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.
<b class="Ic" title="Ic">REPT</b> is here for that purpose. Everything between
<b class="Ic" title="Ic">REPT</b> and <b class="Ic" title="Ic">ENDR</b> 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" title="Sy">add
a,c</b> four times:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
REPT 4
add a,c
ENDR
</pre>
</div>
<div class="Pp"></div>
You can also use <b class="Ic" title="Ic">REPT</b> to generate tables on the
fly:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
; --
; -- 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>
<div class="Pp"></div>
<b class="Ic" title="Ic">REPT</b> is also very useful in recursive macros and,
as in macros, you can also use the special label operator
<b class="Ic" title="Ic">\@</b>. REPT-blocks can be nested.
<h2 class="Ss" title="Ss" id="Aborting_the_assembly_process"><a class="selflink" href="#Aborting_the_assembly_process">Aborting
the assembly process</a></h2>
<b class="Ic" title="Ic">FAIL</b> and <b class="Ic" title="Ic">WARN</b> can be
used to print errors and warnings respectively during the assembly process.
This is especially useful for macros that get an invalid argument.
<b class="Ic" title="Ic">FAIL</b> and <b class="Ic" title="Ic">WARN</b> take a
string as the only argument and they will print this string out as a normal
error with a line number.
<div class="Pp"></div>
<b class="Ic" title="Ic">FAIL</b> stops assembling immediately while
<b class="Ic" title="Ic">WARN</b> shows the message but continues afterwards.
<h2 class="Ss" title="Ss" id="Including_other_source_files"><a class="selflink" href="#Including_other_source_files">Including
other source files</a></h2>
Use <b class="Ic" title="Ic">INCLUDE</b> 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
<b class="Ic" title="Ic">INCLUDE</b> calls infinitely (or until you run out of
memory, whichever comes first).
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
INCLUDE "irq.inc"
</pre>
</div>
<h2 class="Ss" title="Ss" id="Conditional_assembling"><a class="selflink" href="#Conditional_assembling">Conditional
assembling</a></h2>
The four commands <b class="Ic" title="Ic">IF</b>,
<b class="Ic" title="Ic">ELIF</b>, <b class="Ic" title="Ic">ELSE</b>, and
<b class="Ic" title="Ic">ENDC</b> are used to conditionally assemble parts of
your file. This is a powerful feature commonly used in macros.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
IF NUM < 0
PRINTT "NUM < 0\n"
ELIF NUM == 0
PRINTT "NUM == 0\n"
ELSE
PRINTT "NUM > 0\n"
ENDC
</pre>
</div>
<div class="Pp"></div>
The <b class="Ic" title="Ic">ELIF</b> and <b class="Ic" title="Ic">ELSE</b>
blocks are optional. <b class="Ic" title="Ic">IF</b> <span class="No">/</span>
<b class="Ic" title="Ic">ELIF</b> <span class="No">/</span>
<b class="Ic" title="Ic">ELSE</b> <span class="No">/</span>
<b class="Ic" title="Ic">ENDC</b> blocks can be nested.
<div class="Pp"></div>
Note that if an <b class="Ic" title="Ic">ELSE</b> block is found before an
<b class="Ic" title="Ic">ELIF</b> block, the <b class="Ic" title="Ic">ELIF</b>
block will be ignored. All <b class="Ic" title="Ic">ELIF</b> blocks must go
before the <b class="Ic" title="Ic">ELSE</b> block. Also, if there is more
than one <b class="Ic" title="Ic">ELSE</b> block, all of them but the first
one are ignored.
<h2 class="Ss" title="Ss" id="Integer_and_Boolean_expressions"><a class="selflink" 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.
<div class="Pp"></div>
The most basic expression is just a single number.
<div class="Pp"></div>
<b class="Sy" title="Sy">Numeric Formats</b>
<div class="Pp"></div>
There are a number of numeric formats.
<div class="Pp"></div>
<ul class="Bl-dash Bl-compact">
<li class="It-dash">Hexadecimal: $0123456789ABCDEF. Case-insensitive</li>
<li class="It-dash">Decimal: 0123456789</li>
<li class="It-dash">Octal: &01234567</li>
<li class="It-dash">Binary: %01</li>
<li class="It-dash">Fixedpoint (16.16): 01234.56789</li>
<li class="It-dash">Character constant: "ABYZ"</li>
<li class="It-dash">Gameboy graphics: `0123</li>
</ul>
<div class="Pp"></div>
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.
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
DW `01012323
</pre>
</div>
<div class="Pp"></div>
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.
<div class="Pp"></div>
<b class="Sy" title="Sy">Operators</b>
<div class="Pp"></div>
A great number of operators you can use in expressions are available (listed in
order of precedence):
<table class="Bl-column" style="margin-left: 6.00ex;">
<colgroup>
<col style="min-width: 8.00ex;"/>
</colgroup>
<tr class="It-column">
<td class="It-column"><b class="Sy" title="Sy">Operator</b></td>
<td class="It-column"><b class="Sy" title="Sy">Meaning</b></td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#(_)"><code class="Li" id="(_)">(
)</code></a></td>
<td class="It-column">Precedence override</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#FUNC()"><code class="Li" id="FUNC()">FUNC()</code></a></td>
<td class="It-column">Function call</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#~_+_-"><code class="Li" id="~_+_-">~
+ -</code></a></td>
<td class="It-column">Unary not/plus/minus</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#*_/_%"><code class="Li" id="*_/_%">*
/ %</code></a></td>
<td class="It-column">Multiply/divide/modulo</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#<<_>>"><code class="Li" id="<<_>>"><<
>></code></a></td>
<td class="It-column">Shift left/right</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#&_|_^"><code class="Li" id="&_|_^">&
| ^</code></a></td>
<td class="It-column">Binary and/or/xor</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#+_-"><code class="Li" id="+_-">+
-</code></a></td>
<td class="It-column">Add/subtract</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#!=_==_<="><code class="Li" id="!=_==_<=">!=
== <=</code></a></td>
<td class="It-column">Boolean comparison</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#>=_<_>"><code class="Li" id=">=_<_>">>=
< ></code></a></td>
<td class="It-column">Boolean comparison (Same precedence as the
others)</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#&&_||"><code class="Li" id="&&_||">&&
||</code></a></td>
<td class="It-column">Boolean and/or</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#!"><code class="Li" id="!">!</code></a></td>
<td class="It-column">Unary Boolean not</td>
</tr>
</table>
<div class="Pp"></div>
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.
<div class="Pp"></div>
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.
<h2 class="Ss" title="Ss" id="Fixed‐point_Expressions"><a class="selflink" href="#Fixed‐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.
<div class="Pp"></div>
Some things are different for fixed-point math, though, which is why you have
the following functions to use:
<table class="Bl-column" style="margin-left: 6.00ex;">
<colgroup>
<col style="min-width: 11.00ex;"/>
</colgroup>
<tr class="It-column">
<td class="It-column"><b class="Sy" title="Sy">Name</b></td>
<td class="It-column"><b class="Sy" title="Sy">Operation</b></td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">DIV</b>(<var class="Fa" title="Fa">x</var>,
<var class="Fa" title="Fa">y</var>)</td>
<td class="It-column">
<math class="eqn">
<mrow><mi>x</mi><mo>÷</mo><mi>y</mi></mrow>
</math>
</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">MUL</b>(<var class="Fa" title="Fa">x</var>,
<var class="Fa" title="Fa">y</var>)</td>
<td class="It-column">
<math class="eqn">
<mrow><mi>x</mi><mo>×</mo><mi>y</mi></mrow>
</math>
</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">SIN</b>(<var class="Fa" title="Fa">x</var>)</td>
<td class="It-column">
<math class="eqn">
<mrow><mi>sin</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
</math>
</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">COS</b>(<var class="Fa" title="Fa">x</var>)</td>
<td class="It-column">
<math class="eqn">
<mrow><mi>cos</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
</math>
</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">TAN</b>(<var class="Fa" title="Fa">x</var>)</td>
<td class="It-column">
<math class="eqn">
<mrow><mi>tan</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
</math>
</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">ASIN</b>(<var class="Fa" title="Fa">x</var>)</td>
<td class="It-column">
<math class="eqn">
<mrow><mi>asin</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
</math>
</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">ACOS</b>(<var class="Fa" title="Fa">x</var>)</td>
<td class="It-column">
<math class="eqn">
<mrow><mi>acos</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
</math>
</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">ATAN</b>(<var class="Fa" title="Fa">x</var>)</td>
<td class="It-column">
<math class="eqn">
<mrow><mi>atan</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
</math>
</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">ATAN2</b>(<var class="Fa" title="Fa">x</var>,
<var class="Fa" title="Fa">y</var>)</td>
<td class="It-column">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>
<div class="Pp"></div>
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].
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
; --
; -- 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>
<h2 class="Ss" title="Ss" id="String_Expressions"><a class="selflink" 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" style="margin-left: 6.00ex;">
<colgroup>
<col style="min-width: 6.00ex;"/>
</colgroup>
<tr class="It-column">
<td class="It-column"><b class="Sy" title="Sy">String</b></td>
<td class="It-column"><b class="Sy" title="Sy">Meaning</b></td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#\\"><code class="Li" id="\\">\\</code></a></td>
<td class="It-column">Backslash</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#\""><code class="Li" id="\"">\"</code></a></td>
<td class="It-column">Double quote</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#\,"><code class="Li" id="\,">\,</code></a></td>
<td class="It-column">Comma</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#\{"><code class="Li" id="\{">\{</code></a></td>
<td class="It-column">Curly bracket left</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#\}"><code class="Li" id="\}">\}</code></a></td>
<td class="It-column">Curly bracket right</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#\n"><code class="Li" id="\n">\n</code></a></td>
<td class="It-column">Newline ($0A)</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#\t"><code class="Li" id="\t">\t</code></a></td>
<td class="It-column">Tab ($09)</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#\1_-_\9"><code class="Li" id="\1_-_\9">\1
- \9</code></a></td>
<td class="It-column">Macro argument (Only the body of a macros)</td>
</tr>
<tr class="It-column">
<td class="It-column"><a class="selflink" href="#\@"><code class="Li" id="\@">\@</code></a></td>
<td class="It-column">Label name suffix (Only in the body of macros and
repts)</td>
</tr>
</table>
<div class="Pp"></div>
A funky feature is <b class="Sy" title="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.
<div class="Pp"></div>
HINT: The <b class="Sy" title="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}”.
<div class="Pp"></div>
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!
<table class="Bl-column">
<colgroup>
<col style="min-width: 20.00ex;"/>
</colgroup>
<tr class="It-column">
<td class="It-column"><b class="Sy" title="Sy">Name</b></td>
<td class="It-column"><b class="Sy" title="Sy">Operation</b></td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">STRLEN</b>(<var class="Fa" title="Fa">string</var>)</td>
<td class="It-column">Returns the number of characters in string</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">STRCAT</b>(<var class="Fa" title="Fa">str1</var>,
<var class="Fa" title="Fa">str2</var>)</td>
<td class="It-column">Appends str2 to str1.</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">STRCMP</b>(<var class="Fa" title="Fa">str1</var>,
<var class="Fa" title="Fa">str2</var>)</td>
<td class="It-column">Returns negative if str1 is alphabetically lower than
str2, zero if they match, positive if str1 is greater than str2.</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">STRIN</b>(<var class="Fa" title="Fa">str1</var>,
<var class="Fa" title="Fa">str2</var>)</td>
<td class="It-column">Returns the position of str2 in str1 or zero if it's
not present (first character is position 1).</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">STRSUB</b>(<var class="Fa" title="Fa">str</var>,
<var class="Fa" title="Fa">pos</var>,
<var class="Fa" title="Fa">len</var>)</td>
<td class="It-column">Returns a substring from str starting at pos (first
character is position 1) and with len characters.</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">STRUPR</b>(<var class="Fa" title="Fa">str</var>)</td>
<td class="It-column">Converts all characters in str to capitals and returns
the new string.</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">STRLWR</b>(<var class="Fa" title="Fa">str</var>)</td>
<td class="It-column">Converts all characters in str to lower case and
returns the new string.</td>
</tr>
</table>
<h2 class="Ss" title="Ss" id="Character_maps"><a class="selflink" 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.
<div class="Pp"></div>
Character maps allow the code to map strings up to 16 characters long to an
abitrary 8-bit value:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
CHARMAP "<LF>", 10
CHARMAP "&iacute", 20
CHARMAP "A", 128
</pre>
</div>
<div class="Pp"></div>
<b class="Sy" title="Sy">Note:</b> Character maps affect all strings in the file
from the point in which they are defined. This means that any string that the
code may want to print as debug information will also be affected by it.
<div class="Pp"></div>
<b class="Sy" title="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.
<h2 class="Ss" title="Ss" id="Other_functions"><a class="selflink" href="#Other_functions">Other
functions</a></h2>
There are a few other functions that do various useful things:
<table class="Bl-column">
<colgroup>
<col style="min-width: 9.00ex;"/>
</colgroup>
<tr class="It-column">
<td class="It-column"><b class="Sy" title="Sy">Name</b></td>
<td class="It-column"><b class="Sy" title="Sy">Operation</b></td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">BANK</b>(<var class="Fa" title="Fa">arg</var>)</td>
<td class="It-column">Returns a bank number. If
<var class="Ar" title="Ar">arg</var> is the symbol
<b class="Ic" title="Ic">@</b>, this function returns the bank of the
current section. If <var class="Ar" title="Ar">arg</var> is a string, it
returns the bank of the section that has that name. If
<var class="Ar" title="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 class="It-column">
<td class="It-column"><b class="Fn" title="Fn">DEF</b>(<var class="Fa" title="Fa">label</var>)</td>
<td class="It-column">Returns TRUE if <var class="Ar" title="Ar">label</var>
has been defined.</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">HIGH</b>(<var class="Fa" title="Fa">arg</var>)</td>
<td class="It-column">Returns the top 8 bits of the operand if
<var class="Ar" title="Ar">arg</var> is a label or constant, or the top
8-bit register if it is a 16-bit register.</td>
</tr>
<tr class="It-column">
<td class="It-column"><b class="Fn" title="Fn">LOW</b>(<var class="Fa" title="Fa">arg</var>)</td>
<td class="It-column">Returns the bottom 8 bits of the operand if
<var class="Ar" title="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>
<h1 class="Sh" title="Sh" id="MISCELLANEOUS"><a class="selflink" href="#MISCELLANEOUS">MISCELLANEOUS</a></h1>
<h2 class="Ss" title="Ss" id="Changing_options_while_assembling"><a class="selflink" href="#Changing_options_while_assembling">Changing
options while assembling</a></h2>
<b class="Ic" title="Ic">OPT</b> can be used to change some of the options
during assembling the source instead of defining them on the commandline.
<div class="Pp"></div>
<b class="Ic" title="Ic">OPT</b> takes a comma-seperated list of options as its
argument:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
PUSHO
OPT g.oOX ;Set the GB graphics constants to use these characters
DW `..ooOOXX
POPO
DW `00112233
</pre>
</div>
<div class="Pp"></div>
The options that OPT can modify are currently: <b class="Sy" title="Sy">b</b>,
<b class="Sy" title="Sy">e</b> and <b class="Sy" title="Sy">g</b>.
<div class="Pp"></div>
<b class="Ic" title="Ic">POPO</b> and <b class="Ic" title="Ic">PUSHO</b> provide
the interface to the option stack. <b class="Ic" title="Ic">PUSHO</b> will
push the current set of options on the option stack.
<b class="Ic" title="Ic">POPO</b> 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 number of entries is limited only by the amount of memory in your
machine.
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<a class="Xr" title="Xr">rgbasm(1)</a>, <a class="Xr" title="Xr">rgblink(1)</a>,
<a class="Xr" title="Xr">rgblink(5)</a>,
<a class="Xr" title="Xr">rgbds(5)</a>, <a class="Xr" title="Xr">rgbds(7)</a>,
<a class="Xr" title="Xr">gbz80(7)</a>
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
<b class="Nm" title="Nm">rgbds</b> 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" title="Lk" href="https://github.com/rednex/rgbds">https://github.com/rednex/rgbds</a>.</div>
<table class="foot">
<tr>
<td class="foot-date">March 13, 2018</td>
<td class="foot-os">RGBDS Manual</td>
</tr>
</table>
</body>
</html>