shithub: rgbds

ref: eee0e6adc830c45a16454ff618f21c0111750812
dir: /docs/rgbasm.5.html/

View raw version
<!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 charset="utf-8"/>
  <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">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgbasm</code> &#x2014;
<div class="Nd">language documentation</div>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
This is the full description of the language used by
  <a class="Xr">rgbasm(1)</a>. The description of the instructions supported by
  the GameBoy CPU is in <a class="Xr">gbz80(7)</a>.
</section>
<section class="Sh">
<h1 class="Sh" id="GENERAL"><a class="permalink" href="#GENERAL">GENERAL</a></h1>
<section class="Ss">
<h2 class="Ss" id="Syntax"><a class="permalink" href="#Syntax">Syntax</a></h2>
The syntax is line&#x2010;based, just as in any other assembler, meaning that
  you do one instruction or pseudo&#x2010;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 pseudo&#x2010;ops, mnemonics and registers (reserved keywords)
    are case&#x2010;insensitive and all labels are case&#x2010;sensitive.</p>
<p class="Pp">There are two syntaxes for comments. In both cases, a comment ends
    at the end of the line. The most common one is: anything that follows a
    semicolon &#x2018;<code class="Li">;</code>&#x2019; (that isn't inside a
    string) is a comment. There is another format: anything that follows a
    &#x2018;<code class="Li">*</code>&#x2019; that is placed right at the start
    of a line is a comment. The assembler removes all comments from the code
    before doing anything else.</p>
<p class="Pp">Sometimes lines can be too long and it may be necessary to split
    them. The syntax to do so is the following one:</p>
<div class="Bd Pp Bd-indent">
<pre>
    DB 1, 2, 3, 4 \
       5, 6, 7, 8
</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(&quot;Hello &quot;, \
              &quot;world!&quot;)
</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="Sections"><a class="permalink" href="#Sections">Sections</a></h2>
<code class="Ic">SECTION</code> <var class="Ar">name</var>,
  <var class="Ar">type</var>
<p class="Pp"><code class="Ic">SECTION</code> <var class="Ar">name</var>,
    <var class="Ar">type</var>, <var class="Ar">options</var></p>
<p class="Pp"><code class="Ic">SECTION</code> <var class="Ar">name</var>,
    <var class="Ar">type</var>[<var class="Ar">addr</var>]</p>
<p class="Pp"><code class="Ic">SECTION</code> <var class="Ar">name</var>,
    <var class="Ar">type</var>[<var class="Ar">addr</var>],
    <var class="Ar">options</var></p>
<p class="Pp">Before you can start writing code, you must define a section. This
    tells the assembler what kind of information follows and, if it is code,
    where to put it.</p>
<p class="Pp"><var class="Ar">name</var> is a string enclosed in double quotes
    and can be a new name or the name of an existing section. All sections
    assembled at the same time that have the same name and type are considered
    to be the same section, and their code is put together in the object file
    generated by the assembler. All other sections must have a unique name, even
    in different source files, or the linker will treat it as an error.</p>
<p class="Pp">Possible section <var class="Ar">type</var>s are as follows:</p>
<dl class="Bl-tag">
  <dt><a class="permalink" href="#ROM0"><code class="Cm" id="ROM0">ROM0</code></a></dt>
  <dd>A ROM section. <var class="Ar">addr</var> can range from
      $0000&#x2013;$3FFF (or $0000&#x2013;$7FFF if tiny ROM mode is enabled in
      <a class="Xr">rgblink(1)</a>).</dd>
  <dt><a class="permalink" href="#ROMX"><code class="Cm" id="ROMX">ROMX</code></a></dt>
  <dd>A banked ROM section. <var class="Ar">addr</var> can range from
      $4000&#x2013;$7FFF. <var class="Ar">bank</var> can range from 1 to 511.
      Not available if tiny ROM mode is enabled in
    <a class="Xr">rgblink(1)</a>.</dd>
  <dt><a class="permalink" href="#VRAM"><code class="Cm" id="VRAM">VRAM</code></a></dt>
  <dd>A banked video RAM section. <var class="Ar">addr</var> can range from
      $8000&#x2013;$9FFF. <var class="Ar">bank</var> can be 0 or 1 but bank 1 is
      unavailable if DMG mode is enabled in <a class="Xr">rgblink(1)</a>. Memory
      in this section can only be allocated with <b class="Sy">DS</b>, not
      filled with data.</dd>
  <dt><a class="permalink" href="#SRAM"><code class="Cm" id="SRAM">SRAM</code></a></dt>
  <dd>A banked external (save) RAM section. <var class="Ar">addr</var> can range
      from $A000&#x2013;$BFFF. <var class="Ar">bank</var> can range from 0 to
      15. Memory in this section can only be allocated with
      <b class="Sy">DS</b>, not filled with data.</dd>
  <dt><a class="permalink" href="#WRAM0"><code class="Cm" id="WRAM0">WRAM0</code></a></dt>
  <dd>A general-purpose RAM section. <var class="Ar">addr</var> can range from
      $C000&#x2013;$CFFF, or $C000&#x2013;$DFFF if DMG mode is enabled in
      <a class="Xr">rgblink(1)</a>. Memory in this section can only be allocated
      with <b class="Sy">DS</b>, not filled with data.</dd>
  <dt><a class="permalink" href="#WRAMX"><code class="Cm" id="WRAMX">WRAMX</code></a></dt>
  <dd>A banked general-purpose RAM section. <var class="Ar">addr</var> can range
      from $D000&#x2013;$DFFF. <var class="Ar">bank</var> can range from 1 to 7.
      Memory in this section can only be allocated with <b class="Sy">DS</b>,
      not filled with data. Not available if DMG mode is enabled in
      <a class="Xr">rgblink(1)</a>.</dd>
  <dt><a class="permalink" href="#OAM"><code class="Cm" id="OAM">OAM</code></a></dt>
  <dd>An object attributes RAM section. <var class="Ar">addr</var> can range
      from $FE00-$FE9F. Memory in this section can only be allocated with
      <b class="Sy">DS</b>, not filled with data.</dd>
  <dt><a class="permalink" href="#HRAM"><code class="Cm" id="HRAM">HRAM</code></a></dt>
  <dd>A high RAM section. <var class="Ar">addr</var> can range from
      $FF80&#x2013;$FFFE. Memory in this section can only be allocated with
      <b class="Sy">DS</b>, not filled with data.
    <p class="Pp"><b class="Sy">Note</b>: If you use this method of allocating
        HRAM the assembler will <i class="Em">not</i> choose the short
        addressing mode in the LD instructions <b class="Sy">LD [$FF00+n8],A</b>
        and <b class="Sy">LD A,[$FF00+n8]</b> because the actual address
        calculation is done by the linker. If you find this undesirable you can
        use <code class="Ic">RSSET</code>, <code class="Ic">RB</code>, or
        <code class="Ic">RW</code> instead or use the <b class="Sy">LDH
        [$FF00+n8],A</b> and <b class="Sy">LDH A,[$FF00+n8]</b> syntax instead.
        This forces the assembler to emit the correct instruction and the linker
        to check if the value is in the correct range. This optimization can be
        disabled by passing the <code class="Fl">-L</code> flag to
        <a class="Xr">rgbasm(1)</a>.</p>
  </dd>
</dl>
<p class="Pp"><var class="Ar">option</var>s are comma separated and may
  include:</p>
<dl class="Bl-tag">
  <dt><a class="permalink" href="#BANK"><code class="Cm" id="BANK">BANK</code></a>[<var class="Ar">bank</var>]</dt>
  <dd>Specify which <var class="Ar">bank</var> for the linker to place the
      section.</dd>
  <dt><a class="permalink" href="#ALIGN"><code class="Cm" id="ALIGN">ALIGN</code></a>[<var class="Ar">align</var>]</dt>
  <dd>Place the section at an address whose <var class="Ar">align</var>
      least&#x2010;significant bits are zero. It is a syntax error to use this
      option with <var class="Ar">addr</var>.</dd>
</dl>
<p class="Pp">If [<var class="Ar">addr</var>] is not specified, the section is
    considered &#x201C;floating&#x201D;; the linker will automatically calculate
    an appropriate address for the section. Similarly, if
    <code class="Cm">BANK</code>[<var class="Ar">bank</var>] is not specified,
    the linker will automatically find a bank with enough space.</p>
<p class="Pp">Sections can also be placed by using a linkerscript file. The
    format is described in <a class="Xr">rgblink(5)</a>. They allow the user to
    place floating sections in the desired bank in the order specified in the
    script. This is useful if the sections can't be placed at an address
    manually because the size may change, but they have to be together.</p>
<p class="Pp">Section examples:</p>
<div class="Bd Pp Bd-indent">
<pre>
    SECTION &quot;CoolStuff&quot;,ROMX
</pre>
</div>
<p class="Pp">This switches to the section called &#x201C;CoolStuff&#x201D; (or
    creates it if it doesn't already exist) and defines it as a code
  section.</p>
<p class="Pp">The following example defines a section that can be placed
    anywhere in any ROMX bank:</p>
<div class="Bd Pp Bd-indent">
<pre>
    SECTION &quot;CoolStuff&quot;,ROMX
</pre>
</div>
<p class="Pp">If it is needed, the the base address of the section can be
    specified:</p>
<div class="Bd Pp Bd-indent">
<pre>
    SECTION &quot;CoolStuff&quot;,ROMX[$4567]
</pre>
</div>
<p class="Pp">An example with a fixed bank:</p>
<div class="Bd Pp Bd-indent">
<pre>
    SECTION &quot;CoolStuff&quot;,ROMX[$4567],BANK[3]
</pre>
</div>
<p class="Pp">And if you only want to force the section into a certain bank, and
    not it's position within the bank, that's also possible:</p>
<div class="Bd Pp Bd-indent">
<pre>
    SECTION &quot;CoolStuff&quot;,ROMX,BANK[7]
</pre>
</div>
<p class="Pp">Alignment examples: one use could be when using DMA to copy data
    or when it is needed to align the start of an array to 256 bytes to optimize
    the code that accesses it.</p>
<div class="Bd Pp Bd-indent">
<pre>
    SECTION &quot;OAM Data&quot;,WRAM0,ALIGN[8] ; align to 256 bytes

    SECTION &quot;VRAM Data&quot;,ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
</pre>
</div>
<p class="Pp"><b class="Sy">Hint</b>: If you think this is a lot of typing for
    doing a simple &#x201C;org&#x201D; type thing you can quite easily write an
    intelligent macro (called <code class="Ic">ORG</code> for example) that uses
    <code class="Ic">@</code> for the section name and determines correct
    section type etc as arguments for <code class="Ic">SECTION</code>.</p>
</section>
<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.
<p class="Pp"><code class="Ic">PUSHS</code> will push the current section
    context on the section stack. <code class="Ic">POPS</code> can then later be
    used to restore it. Useful for defining sections in included files when you
    don't want to destroy the section context for the program that included your
    file. The number of entries in the stack is limited only by the amount of
    memory in your machine.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="SYMBOLS"><a class="permalink" href="#SYMBOLS">SYMBOLS</a></h1>
<section class="Ss">
<h2 class="Ss" id="Symbols"><a class="permalink" href="#Symbols">Symbols</a></h2>
RGBDS supports several types of symbols:
<dl class="Bl-hang">
  <dt><b class="Sy">Label</b></dt>
  <dd>Used to assign a memory location with a name</dd>
  <dt><b class="Sy">EQUate</b></dt>
  <dd>Give a constant a name.</dd>
  <dt><b class="Sy">SET</b></dt>
  <dd>Almost the same as EQUate, but you can change the value of a SET during
      assembling.</dd>
  <dt><b class="Sy">Structure</b> (<b class="Sy">the RS group</b>)</dt>
  <dd>Define a structure easily.</dd>
  <dt><b class="Sy">String equate</b> (<b class="Sy">EQUS</b>)</dt>
  <dd>Give a frequently used string a name. Can also be used as a mini-macro,
      like <code class="Fd">#define</code> in C.</dd>
  <dt><b class="Sy">MACRO</b></dt>
  <dd>A block of code or pseudo instructions that you invoke like any other
      mnemonic. You can give them arguments too.</dd>
</dl>
<p class="Pp">A symbol cannot have the same name as a reserved keyword.</p>
<dl class="Bl-hang">
  <dt><b class="Sy">Label</b></dt>
  <dd>
    <p class="Pp">One of the assembler's main tasks is to keep track of
        addresses for you so you don't have to remember obscure numbers but can
        make do with a meaningful name, a label.</p>
    <p class="Pp">This can be done in a number of ways:</p>
    <div class="Bd Pp Bd-indent">
    <pre>
GlobalLabel
AnotherGlobal:
.locallabel
.yet_a_local:
AnotherGlobal.with_another_local:
ThisWillBeExported:: ;note the two colons
ThisWillBeExported.too::
    </pre>
    </div>
    <p class="Pp">In the line where a label is defined there musn't be any
        whitespace before it. Local labels are only accessible within the scope
        they are defined. A scope starts after a global label and ends at the
        next global label. Declaring a label (global or local) with :: does an
        EXPORT at the same time. Local labels can be declared as scope.local or
        simply as as .local. If the former notation is used, the scope must be
        the actual current scope.</p>
    <p class="Pp">Labels will normally change their value during the link
        process and are thus not constant. The exception is the case in which
        the base address of a section is fixed, so the address of the label is
        known at assembly time.</p>
    <p class="Pp">The subtraction of two labels is only constant (known at
        assembly time) if they are two local labels that belong to the same
        scope, or they are two global labels that belong to sections with fixed
        base addresses.</p>
  </dd>
  <dt><b class="Sy">EQU</b></dt>
  <dd>
    <p class="Pp">EQUates are constant symbols. They can, for example, be used
        for things such as bit-definitions of hardware registers.</p>
    <div class="Bd Pp Bd-indent">
    <pre>
EXIT_OK      EQU $00
EXIT_FAILURE EQU $01
    </pre>
    </div>
    <p class="Pp">Note that a colon (:) following the label-name is not allowed.
        EQUates cannot be exported and imported. They don't change their value
        during the link process.</p>
  </dd>
  <dt><b class="Sy">SET</b></dt>
  <dd>
    <p class="Pp">SETs are similar to EQUates. They are also constant symbols in
        the sense that their values are defined during the assembly process.
        These symbols are normally used in macros.</p>
    <div class="Bd Pp Bd-indent">
    <pre>
ARRAY_SIZE EQU 4
COUNT      SET 2
COUNT      SET ARRAY_SIZE+COUNT
    </pre>
    </div>
    <p class="Pp">Note that a colon (:) following the label-name is not allowed.
        SETs cannot be exported and imported. Alternatively you can use = as a
        synonym for SET.</p>
    <div class="Bd Pp Bd-indent">
    <pre>
COUNT = 2
    </pre>
    </div>
  </dd>
  <dt><b class="Sy">RSSET</b>, <b class="Sy">RSRESET</b>, <b class="Sy">RB</b>,
    <b class="Sy">RW</b></dt>
  <dd>
    <p class="Pp">The RS group of commands is a handy way of defining
        structures:</p>
    <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 equated symbols:</p>
    <div class="Bd Pp Bd-indent">
    <pre>
str_pStuff = 0
str_tData  = 2
str_bCount = 258
str_SIZEOF = 259
    </pre>
    </div>
    <p class="Pp">There are four commands in the RS group of commands:</p>
    <table class="Bl-column">
      <tr>
        <td><b class="Sy">Command</b></td>
        <td><b class="Sy">Meaning</b></td>
      </tr>
      <tr>
        <td><a class="permalink" href="#RSRESET"><code class="Ic" id="RSRESET">RSRESET</code></a></td>
        <td>Resets the _RS counter to zero.</td>
      </tr>
      <tr>
        <td><a class="permalink" href="#RSSET"><code class="Ic" id="RSSET">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></td>
      </tr>
    </table>
    <p class="Pp">Note that a colon (:) following the symbol-name is not
        allowed. <b class="Sy">RS</b> symbols cannot be exported and imported.
        They don't change their value during the link process.</p>
  </dd>
  <dt><b class="Sy">EQUS</b></dt>
  <dd>
    <p class="Pp">EQUS is used to define string-symbols. Wherever the assembler
        meets a string symbol its name is replaced with its value. If you are
        familiar with C you can think of it as the same as
        <code class="Fd">#define .</code></p>
    <div class="Bd Pp Bd-indent">
    <pre>
COUNTREG EQUS &quot;[hl+]&quot;
    ld a,COUNTREG

PLAYER_NAME EQUS &quot;\&quot;John\&quot;&quot;
    db PLAYER_NAME
    </pre>
    </div>
    <p class="Pp">Note that : following the label-name is not allowed, and that
        strings must be quoted to be useful.</p>
    <p class="Pp">This will be interpreted as:</p>
    <div class="Bd Pp Bd-indent">
    <pre>
    ld a,[hl+]
    db &quot;John&quot;
    </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 &quot;push af\npush bc\npush de\npush hl\n&quot;
    </pre>
    </div>
    <p class="Pp">Note that a colon (:) following the label-name is not allowed.
        String equates can't be exported or imported.</p>
    <p class="Pp"><b class="Sy">Important note</b>: An EQUS can be expanded to a
        string that contains another EQUS and it will be expanded as well. If
        this creates an infinite loop, RGBASM will error out once a certain
        depth is reached. See the -r command-line option. Also, a MACRO can have
        inside an EQUS which references the same MACRO, which has the same
        problem.</p>
  </dd>
  <dt><b class="Sy">MACRO</b></dt>
  <dd>
    <p class="Pp">One of the best features of an assembler is the ability to
        write macros for it. Macros also provide a method of passing arguments
        to them and they can then react to the input using IF-constructs.</p>
    <div class="Bd Pp Bd-indent">
    <pre>
MyMacro: MACRO
         ld   a,80
         call MyFunc
         ENDM
    </pre>
    </div>
    <p class="Pp">Note that a colon (:) following the macro-name is required.
        Macros can't be exported or imported. It's valid to call a macro from a
        macro (yes, even the same one).</p>
    <p class="Pp">The above example is a very simple macro. You execute the
        macro by typing its name.</p>
    <div class="Bd Pp Bd-indent">
    <pre>
         add  a,b
         ld   sp,hl
         MyMacro ;This will be expanded
         sub  a,87
    </pre>
    </div>
    <p class="Pp">When the assembler meets MyMacro it will insert the
        macrodefinition (the text enclosed in <code class="Ic">MACRO</code> /
        <code class="Ic">ENDM</code>).</p>
    <p class="Pp">Suppose your macro contains a loop.</p>
    <div class="Bd Pp Bd-indent">
    <pre>
LoopyMacro: MACRO
            xor  a,a
.loop       ld   [hl+],a
            dec  c
            jr   nz,.loop
            ENDM
    </pre>
    </div>
    <p class="Pp">This is fine. That is, if you only use the macro once per
        scope. To get around this problem there is a special label string equate
        called <code class="Ic">\@</code> that you can append to your labels and
        it will then expand to a unique string.</p>
    <p class="Pp"><code class="Ic">\@</code> also works in REPT-blocks should
        you have any loops there.</p>
    <div class="Bd Pp Bd-indent">
    <pre>
LoopyMacro: MACRO
            xor  a,a
.loop\@     ld   [hl+],a
            dec  c
            jr   nz,.loop\@
            ENDM
    </pre>
    </div>
    <p class="Pp"><b class="Sy">Important note</b>: Since a MACRO can call
        itself (or a different MACRO that calls the first one) there can be
        problems of circular dependency. They trap the assembler in an infinite
        loop, so you have to be careful when using recursion with MACROs. Also,
        a MACRO can have inside an EQUS which references the same MACRO, which
        has the same problem.</p>
    <p class="Pp"><b class="Sy">Macro Arguments</b></p>
    <p class="Pp">I'd like LoopyMacro a lot better if I didn't have to pre-load
        the registers with values and then call it. What I'd like is the ability
        to pass it arguments and it then loaded the registers itself.</p>
    <p class="Pp">And I can do that. In macros you can get the arguments by
        using the special macro string equates <code class="Ic">\1</code>
        through <code class="Ic">\9</code>, <code class="Ic">\1</code> being the
        first argument specified on the calling of the macro.</p>
    <div class="Bd Pp Bd-indent">
    <pre>
LoopyMacro: MACRO
            ld   hl,\1
            ld   c,\2
            xor  a,a
.loop\@     ld   [hl+],a
            dec  c
            jr   nz,.loop\@
            ENDM
    </pre>
    </div>
    <p class="Pp">Now I can call the macro specifying two arguments. The first
        being the address and the second being a bytecount. The macro will then
        reset all bytes in this range.</p>
    <div class="Bd Pp Bd-indent">
    <pre>
LoopyMacro MyVars,54
    </pre>
    </div>
    <p class="Pp">Arguments are passed as string equates. There's no need to
        enclose them in quotes. An expression will not be evaluated first but
        passed directly. This means that it's probably a very good idea to use
        brackets around <code class="Ic">\1</code> to <code class="Ic">\9</code>
        if you perform further calculations on them. For instance, if you pass 1
        + 2 as the first argument and then do <code class="Ic">PRINTV</code>
        <code class="Ic">\1</code> * 2 you will get the value 5 on screen and
        not 6 as you might have expected.</p>
    <p class="Pp">In reality, up to 256 arguments can be passed to a macro, but
        you can only use the first 9 like this. If you want to use the rest, you
        need to use the keyword <code class="Ic">SHIFT</code>.</p>
    <p class="Pp">Line continuations work as usual inside macros or lists of
        arguments of macros. However, some characters need to be escaped, as in
        the following example:</p>
    <div class="Bd Pp Bd-indent">
    <pre>
PrintMacro : MACRO
    PRINTT \1
ENDM

    PrintMacro STRCAT(&quot;Hello&quot;\,  \
                      &quot; world\\n&quot;)
    </pre>
    </div>
    <p class="Pp"><code class="Ic">SHIFT</code> is a special command only
        available in macros. Very useful in REPT-blocks. It will shift the
        arguments by one to the left. <code class="Ic">\1</code> will get the
        value of <code class="Ic">\2</code>, <code class="Ic">\2</code> will get
        the value in <code class="Ic">\3</code> and so forth.</p>
    <p class="Pp">This is the only way of accessing the value of arguments from
        10 to 256.</p>
  </dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Exporting_and_importing_symbols"><a class="permalink" href="#Exporting_and_importing_symbols">Exporting
  and importing symbols</a></h2>
Importing and exporting of symbols is a feature that is very useful when your
  project spans many source-files and, for example, you need to jump to a
  routine defined in another file.
<p class="Pp">Exporting of symbols has to be done manually, importing is done
    automatically if the assembler doesn't know where a symbol is defined.</p>
<p class="Pp"><code class="Ic">EXPORT</code> <var class="Ar">label</var> [,
    <var class="Ar">label</var> , <span class="No">...</span>]</p>
<p class="Pp">The assembler will make label accessible to other files during the
    link process.</p>
<p class="Pp"><code class="Ic">GLOBAL</code> <var class="Ar">label</var> [,
    <var class="Ar">label</var> , <span class="No">...</span>]</p>
<p class="Pp">If label is defined during the assembly it will be exported, if
    not, it will be imported. Handy (very!) for include-files. Note that, since
    importing is done automatically, this keyword has the same effect as
    <code class="Ic">EXPORT</code>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Purging_symbols"><a class="permalink" href="#Purging_symbols">Purging
  symbols</a></h2>
<code class="Ic">PURGE</code> allows you to completely remove a symbol from the
  symbol table as if it had never existed. USE WITH EXTREME CAUTION!!! I can't
  stress this enough, you seriously need to know what you are doing. DON'T purge
  symbol that you use in expressions the linker needs to calculate. In fact,
  it's probably not even safe to purge anything other than string symbols and
  macros.
<div class="Bd Pp Bd-indent">
<pre>
Kamikaze EQUS  &quot;I don't want to live anymore&quot;
AOLer    EQUS  &quot;Me too&quot;
         PURGE Kamikaze, AOLer
</pre>
</div>
<p class="Pp">Note that string symbols that are part of a
    <code class="Ic">PURGE</code> command WILL NOT BE EXPANDED as the ONLY
    exception to this rule.</p>
</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>
    <td><b class="Sy">Type</b></td>
    <td><b class="Sy">Name</b></td>
    <td><b class="Sy">Contents</b></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU"><code class="Ic" id="EQU">EQU</code></a></td>
    <td><a class="permalink" href="#@"><code class="Ic" id="@">@</code></a></td>
    <td>PC value</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_2"><code class="Ic" id="EQU_2">EQU</code></a></td>
    <td><a class="permalink" href="#_PI"><code class="Ic" id="_PI">_PI</code></a></td>
    <td>Fixed point &#x03C0;</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#SET"><code class="Ic" id="SET">SET</code></a></td>
    <td><a class="permalink" href="#_RS"><code class="Ic" id="_RS">_RS</code></a></td>
    <td>_RS Counter</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_3"><code class="Ic" id="EQU_3">EQU</code></a></td>
    <td><a class="permalink" href="#_NARG"><code class="Ic" id="_NARG">_NARG</code></a></td>
    <td>Number of arguments passed to macro</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_4"><code class="Ic" id="EQU_4">EQU</code></a></td>
    <td><a class="permalink" href="#__LINE__"><code class="Ic" id="__LINE__">__LINE__</code></a></td>
    <td>The current line number</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQUS"><code class="Ic" id="EQUS">EQUS</code></a></td>
    <td><a class="permalink" href="#__FILE__"><code class="Ic" id="__FILE__">__FILE__</code></a></td>
    <td>The current filename</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQUS_2"><code class="Ic" id="EQUS_2">EQUS</code></a></td>
    <td><a class="permalink" href="#__DATE__"><code class="Ic" id="__DATE__">__DATE__</code></a></td>
    <td>Today's date</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQUS_3"><code class="Ic" id="EQUS_3">EQUS</code></a></td>
    <td><a class="permalink" href="#__TIME__"><code class="Ic" id="__TIME__">__TIME__</code></a></td>
    <td>The current time</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQUS_4"><code class="Ic" id="EQUS_4">EQUS</code></a></td>
    <td><a class="permalink" href="#__ISO_8601_LOCAL__"><code class="Ic" id="__ISO_8601_LOCAL__">__ISO_8601_LOCAL__</code></a></td>
    <td>ISO 8601 timestamp (local)</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQUS_5"><code class="Ic" id="EQUS_5">EQUS</code></a></td>
    <td><a class="permalink" href="#__ISO_8601_UTC__"><code class="Ic" id="__ISO_8601_UTC__">__ISO_8601_UTC__</code></a></td>
    <td>ISO 8601 timestamp (UTC)</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_5"><code class="Ic" id="EQU_5">EQU</code></a></td>
    <td><a class="permalink" href="#__UTC_YEAR__"><code class="Ic" id="__UTC_YEAR__">__UTC_YEAR__</code></a></td>
    <td>Today's year</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_6"><code class="Ic" id="EQU_6">EQU</code></a></td>
    <td><a class="permalink" href="#__UTC_MONTH__"><code class="Ic" id="__UTC_MONTH__">__UTC_MONTH__</code></a></td>
    <td>Today's month number, 1-12</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_7"><code class="Ic" id="EQU_7">EQU</code></a></td>
    <td><a class="permalink" href="#__UTC_DAY__"><code class="Ic" id="__UTC_DAY__">__UTC_DAY__</code></a></td>
    <td>Today's day of the month, 1-31</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_8"><code class="Ic" id="EQU_8">EQU</code></a></td>
    <td><a class="permalink" href="#__UTC_HOUR__"><code class="Ic" id="__UTC_HOUR__">__UTC_HOUR__</code></a></td>
    <td>Current hour, 0-23</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_9"><code class="Ic" id="EQU_9">EQU</code></a></td>
    <td><a class="permalink" href="#__UTC_MINUTE__"><code class="Ic" id="__UTC_MINUTE__">__UTC_MINUTE__</code></a></td>
    <td>Current minute, 0-59</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_10"><code class="Ic" id="EQU_10">EQU</code></a></td>
    <td><a class="permalink" href="#__UTC_SECOND__"><code class="Ic" id="__UTC_SECOND__">__UTC_SECOND__</code></a></td>
    <td>Current second, 0-59</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_11"><code class="Ic" id="EQU_11">EQU</code></a></td>
    <td><a class="permalink" href="#__RGBDS_MAJOR__"><code class="Ic" id="__RGBDS_MAJOR__">__RGBDS_MAJOR__</code></a></td>
    <td>Major version number of RGBDS.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_12"><code class="Ic" id="EQU_12">EQU</code></a></td>
    <td><a class="permalink" href="#__RGBDS_MINOR__"><code class="Ic" id="__RGBDS_MINOR__">__RGBDS_MINOR__</code></a></td>
    <td>Minor version number of RGBDS.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#EQU_13"><code class="Ic" id="EQU_13">EQU</code></a></td>
    <td><a class="permalink" href="#__RGBDS_PATCH__"><code class="Ic" id="__RGBDS_PATCH__">__RGBDS_PATCH__</code></a></td>
    <td>Patch version number of RGBDS.</td>
  </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="Defining_constant_data"><a class="permalink" href="#Defining_constant_data">Defining
  constant data</a></h2>
<code class="Ic">DB</code> defines a list of bytes that will be stored in the
  final image. Ideal for tables and text (which is not zero-terminated).
<div class="Bd Pp Bd-indent">
<pre>
DB 1,2,3,4,&quot;This is a string&quot;
</pre>
</div>
<p class="Pp">Alternatively, you can use <code class="Ic">DW</code> to store a
    list of words (16-bits) or <code class="Ic">DL</code> to store a list of
    doublewords/longs (32-bits). Strings are not allowed as arguments to
    <code class="Ic">DW</code> and <code class="Ic">DL</code>.</p>
<p class="Pp">You can also use <code class="Ic">DB</code>,
    <code class="Ic">DW</code> and <code class="Ic">DL</code> without arguments,
    or leaving empty elements at any point in the list. This works exactly like
    <b class="Sy">DS 1</b>, <b class="Sy">DS 2</b> and <b class="Sy">DS 4</b>
    respectively. Consequently, <code class="Ic">DB</code>,
    <code class="Ic">DW</code> and <code class="Ic">DL</code> can be used in a
    <b class="Sy">WRAM0</b> <span class="No">/</span> <b class="Sy">WRAMX</b>
    <span class="No">/</span> <b class="Sy">HRAM</b> <span class="No">/</span>
    <b class="Sy">VRAM</b> <span class="No">/</span> <b class="Sy">SRAM</b>
    section.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Declaring_variables_in_a_RAM_section"><a class="permalink" href="#Declaring_variables_in_a_RAM_section">Declaring
  variables in a RAM section</a></h2>
<code class="Ic">DS</code> allocates a number of bytes. The content is
  undefined. This is the preferred method of allocationg space in a RAM section.
  You can, however, use <code class="Ic">DB</code>, <code class="Ic">DW</code>
  and <code class="Ic">DL</code> without any arguments instead.
<div class="Bd Pp Bd-indent">
<pre>
DS str_SIZEOF ;allocate str_SIZEOF bytes
</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="Including_binary_files"><a class="permalink" href="#Including_binary_files">Including
  binary files</a></h2>
You probably have some graphics you'd like to include. Use
  <code class="Ic">INCBIN</code> to include a raw binary file as it is. If the
  file isn't found in the current directory, the include-path list passed to the
  linker on the command line will be searched.
<div class="Bd Pp Bd-indent">
<pre>
INCBIN &quot;titlepic.bin&quot;
INCBIN &quot;sprites/hero.bin&quot;&#x00A0;; UNIX
INCBIN &quot;sprites\\hero.bin&quot;&#x00A0;; Windows
</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 &quot;data.bin&quot;,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 share the same space in memory, like
  unions in C. This allows you to easily reuse memory for different purposes,
  depending on the game's state.
<p class="Pp">You create unions using the <code class="Ic">UNION</code>,
    <code class="Ic">NEXTU</code> and <code class="Ic">ENDU</code> keywords.
    <code class="Ic">NEXTU</code> lets you create a new block of allocations,
    and you may use it as many times within a union as necessary.</p>
<div class="Bd Pp Bd-indent">
<pre>
UNION
Name: ds 8
Nickname: ds 8
NEXTU
Health: dw
Something: ds 3
Lives: db
NEXTU
Temporary: ds 19
ENDU
</pre>
</div>
<p class="Pp">This union will use up 19 bytes, as this is the size of the
    largest block (the last one, containing 'Temporary'). Of course, as 'Name',
    'Health', and 'Temporary' all point to the same memory locations, writes to
    any one of these will affect values read from the others.</p>
<p class="Pp">Unions may be used in any section, but code and data may not be
    included.</p>
</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="Printing_things_during_assembly"><a class="permalink" href="#Printing_things_during_assembly">Printing
  things during assembly</a></h2>
These three instructions type text and values to stdout. Useful for debugging
  macros or wherever you may feel the need to tell yourself some important
  information.
<div class="Bd Pp Bd-indent">
<pre>
PRINTT &quot;I'm the greatest programmer in the whole wide world\n&quot;
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.</dd>
  <dt><a class="permalink" href="#PRINTV"><code class="Ic" id="PRINTV">PRINTV</code></a></dt>
  <dd>prints out an integer value in hexadecimal or, as in the example, the
      result of a calculation. Unsurprisingly, you can also print out a constant
      symbols value.</dd>
  <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>
</section>
<section class="Ss">
<h2 class="Ss" id="Automatically_repeating_blocks_of_code"><a class="permalink" href="#Automatically_repeating_blocks_of_code">Automatically
  repeating blocks of code</a></h2>
Suppose you're feeling lazy and you want to unroll a time consuming loop.
  <code class="Ic">REPT</code> is here for that purpose. Everything between
  <code class="Ic">REPT</code> and <code class="Ic">ENDR</code> will be repeated
  a number of times just as if you done a copy/paste operation yourself. The
  following example will assemble <b class="Sy">add a,c</b> four times:
<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 SET   0.0
      REPT  256
      DB    (MUL(64.0,SIN(ANGLE))+64.0)&gt;&gt;16
ANGLE SET ANGLE+256.0
      ENDR
</pre>
</div>
<p class="Pp"><code class="Ic">REPT</code> is also very useful in recursive
    macros and, as in macros, you can also use the special label operator
    <code class="Ic">\@</code>. REPT-blocks can be nested.</p>
</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>
</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 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 &quot;irq.inc&quot;
</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> are used to
  conditionally assemble parts of your file. This is a powerful feature commonly
  used in macros.
<div class="Bd Pp Bd-indent">
<pre>
IF NUM &lt; 0
  PRINTT &quot;NUM &lt; 0\n&quot;
ELIF NUM == 0
  PRINTT &quot;NUM == 0\n&quot;
ELSE
  PRINTT &quot;NUM &gt; 0\n&quot;
ENDC
</pre>
</div>
<p class="Pp">The <code class="Ic">ELIF</code> and <code class="Ic">ELSE</code>
    blocks are optional. <code class="Ic">IF</code> <span class="No">/</span>
    <code class="Ic">ELIF</code> <span class="No">/</span>
    <code class="Ic">ELSE</code> <span class="No">/</span>
    <code class="Ic">ENDC</code> blocks can be nested.</p>
<p class="Pp">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 class="Ss">
<h2 class="Ss" id="Integer_and_Boolean_expressions"><a class="permalink" href="#Integer_and_Boolean_expressions">Integer
  and Boolean expressions</a></h2>
An expression can be composed of many things. Expressions are always evaluated
  using signed 32-bit math.
<p class="Pp">The most basic expression is just a single number.</p>
<p class="Pp"><b class="Sy">Numeric Formats</b></p>
<p class="Pp">There are a number of numeric formats.</p>
<p class="Pp"></p>
<ul class="Bl-dash Bl-compact">
  <li>Hexadecimal: $0123456789ABCDEF. Case-insensitive</li>
  <li>Decimal: 0123456789</li>
  <li>Octal: &amp;01234567</li>
  <li>Binary: %01</li>
  <li>Fixedpoint (16.16): 01234.56789</li>
  <li>Character constant: &quot;ABYZ&quot;</li>
  <li>Gameboy graphics: `0123</li>
</ul>
<p class="Pp">The last one, Gameboy graphics, is quite interesting and useful.
    The values are actually pixel values and it converts the
    &#x201C;chunky&#x201D; data to &#x201C;planar&#x201D; data as used in the
    Gameboy.</p>
<div class="Bd Pp Bd-indent">
<pre>
    DW `01012323
</pre>
</div>
<p class="Pp">Admittedly, an expression with just a single number is quite
    boring. To spice things up a bit there are a few operators you can use to
    perform calculations between numbers.</p>
<p class="Pp"><b class="Sy">Operators</b></p>
<p class="Pp">A great number of operators you can use in expressions are
    available (listed in order of precedence):</p>
<table class="Bl-column Bd-indent">
  <tr>
    <td><b class="Sy">Operator</b></td>
    <td><b class="Sy">Meaning</b></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#(__&amp;)"><code class="Li" id="(__&amp;)">(
      )</code></a></td>
    <td>Precedence override</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#FUNC()"><code class="Li" id="FUNC()">FUNC()</code></a></td>
    <td>Function call</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#~_+_-"><code class="Li" id="~_+_-">~ +
      -</code></a></td>
    <td>Unary not/plus/minus</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#*_/__"><code class="Li" id="*_/__">* /
      %</code></a></td>
    <td>Multiply/divide/modulo</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#_____"><code class="Li" id="_____">&lt;&lt;
      &gt;&gt;</code></a></td>
    <td>Shift left/right</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#&amp;__&amp;___"><code class="Li" id="&amp;__&amp;___">&amp;
      | ^</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="!=_==__=">!=
      == &lt;=</code></a></td>
    <td>Boolean comparison</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#_=____"><code class="Li" id="_=____">&gt;=
      &lt; &gt;</code></a></td>
    <td>Boolean comparison (Same precedence as the others)</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#&amp;&amp;___"><code class="Li" id="&amp;&amp;___">&amp;&amp;
      ||</code></a></td>
    <td>Boolean and/or</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#!"><code class="Li" id="!">!</code></a></td>
    <td>Unary Boolean not</td>
  </tr>
</table>
<p class="Pp">The result of the boolean operators is zero if when FALSE and
    non-zero when TRUE. It is legal to use an integer as the condition for IF
    blocks. You can use symbols instead of numbers in your expression if you
    wish.</p>
<p class="Pp">An expression is said to be constant when it doesn't change its
    value during linking. This basically means that you can't use labels in
    those expressions. The instructions in the macro-language all require
    expressions that are constant. The only exception is the subtraction of
    labels in the same section or labels that belong to sections with a fixed
    base addresses, all of which must be defined in the same source file (the
    calculation cannot be passed to the object file generated by the assembler).
    In this case, the result is a constant that can be calculated at assembly
    time.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Fixed__u2010_point_Expressions"><a class="permalink" href="#Fixed__u2010_point_Expressions">Fixed&#x2010;point
  Expressions</a></h2>
Fixed point constants are basically normal 32-bit constants where the upper 16
  bits are used for the integer part and the lower 16 bits are used for the
  fraction (65536ths). This means that you can use them in normal integer
  expression, and some integer operators like plus and minus don't care whether
  the operands are integer or fixed-point. You can easily convert a fixed-point
  number to an integer by shifting it right 16 bits. It follows that you can
  convert an integer to a fixed-point number by shifting it left.
<p class="Pp">Some things are different for fixed-point math, though, which is
    why you have the following functions to use:</p>
<table class="Bl-column Bd-indent">
  <tr>
    <td><b class="Sy">Name</b></td>
    <td><b class="Sy">Operation</b></td>
  </tr>
  <tr>
    <td><code class="Fn">DIV</code>(<var class="Fa">x</var>,
      <var class="Fa">y</var>)</td>
    <td>
    <math class="eqn">
      <mrow><mi>x</mi><mo>&#x00F7;</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>&#x00D7;</mo><mi>y</mi></mrow>
    </math>
    </td>
  </tr>
  <tr>
    <td><code class="Fn">SIN</code>(<var class="Fa">x</var>)</td>
    <td>
    <math class="eqn">
      <mrow><mi>sin</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
    </math>
    </td>
  </tr>
  <tr>
    <td><code class="Fn">COS</code>(<var class="Fa">x</var>)</td>
    <td>
    <math class="eqn">
      <mrow><mi>cos</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
    </math>
    </td>
  </tr>
  <tr>
    <td><code class="Fn">TAN</code>(<var class="Fa">x</var>)</td>
    <td>
    <math class="eqn">
      <mrow><mi>tan</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
    </math>
    </td>
  </tr>
  <tr>
    <td><code class="Fn">ASIN</code>(<var class="Fa">x</var>)</td>
    <td>
    <math class="eqn">
      <mrow><mi>asin</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
    </math>
    </td>
  </tr>
  <tr>
    <td><code class="Fn">ACOS</code>(<var class="Fa">x</var>)</td>
    <td>
    <math class="eqn">
      <mrow><mi>acos</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
    </math>
    </td>
  </tr>
  <tr>
    <td><code class="Fn">ATAN</code>(<var class="Fa">x</var>)</td>
    <td>
    <math class="eqn">
      <mrow><mi>atan</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow>
    </math>
    </td>
  </tr>
  <tr>
    <td><code class="Fn">ATAN2</code>(<var class="Fa">x</var>,
      <var class="Fa">y</var>)</td>
    <td>Angle between
    <math class="eqn">
      <mrow><mo>(</mo><mi>x</mi><mo>,</mo><mi>y</mi><mo>)</mo></mrow>
    </math>
     and
    <math class="eqn">
      <mrow><mo>(</mo><mn>1</mn><mo>,</mo><mn>0</mn><mo>)</mo></mrow>
    </math>
    </td>
  </tr>
</table>
<p class="Pp">These functions are extremely useful for automatic generation of
    various tables. A circle has 65536.0 degrees. Sine values are between [-1.0;
    1.0].</p>
<div class="Bd Pp Bd-indent">
<pre>
; --
; -- Generate a 256 byte sine table with values between 0 and 128
; --
ANGLE SET   0.0
      REPT  256
      DB    (MUL(64.0,SIN(ANGLE))+64.0)&gt;&gt;16
ANGLE SET ANGLE+256.0
      ENDR
</pre>
</div>
</section>
<section class="Ss">
<h2 class="Ss" id="String_Expressions"><a class="permalink" href="#String_Expressions">String
  Expressions</a></h2>
The most basic string expression is any number of characters contained in double
  quotes (&quot;for instance&quot;). Like in C, the escape character is \, and
  there are a number of commands you can use within a string:
<table class="Bl-column Bd-indent">
  <tr>
    <td><b class="Sy">String</b></td>
    <td><b class="Sy">Meaning</b></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#__rs___rs_"><code class="Li" id="__rs___rs_">\\</code></a></td>
    <td>Backslash</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#__rs__"><code class="Li" id="__rs__">\&quot;</code></a></td>
    <td>Double quote</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#__rs_,"><code class="Li" id="__rs_,">\,</code></a></td>
    <td>Comma</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#__rs___2"><code class="Li" id="__rs___2">\{</code></a></td>
    <td>Curly bracket left</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#__rs___3"><code class="Li" id="__rs___3">\}</code></a></td>
    <td>Curly bracket right</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#__rs_n"><code class="Li" id="__rs_n">\n</code></a></td>
    <td>Newline ($0A)</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#__rs_t"><code class="Li" id="__rs_t">\t</code></a></td>
    <td>Tab ($09)</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#__rs_1_-___rs_9"><code class="Li" id="__rs_1_-___rs_9">\1
      - \9</code></a></td>
    <td>Macro argument (Only the body of a macros)</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#__rs_@"><code class="Li" id="__rs_@">\@</code></a></td>
    <td>Label name suffix (Only in the body of macros and repts)</td>
  </tr>
</table>
<p class="Pp">A funky feature is <b class="Sy">{symbol}</b> within a string.
    This will examine the type of the symbol and insert its value accordingly.
    If symbol is a string symbol, the symbols value is simply copied. If it's a
    numeric symbol, the value is converted to hexadecimal notation and inserted
    as a string with a dollar prepended.</p>
<p class="Pp">It's possible to change the way numeric symbols are converted by
    specifying a print type like so: <b class="Sy">{d:symbol}</b> Valid print
    types are:</p>
<table class="Bl-column Bd-indent">
  <tr>
    <td><b class="Sy">Print type</b></td>
    <td><b class="Sy">Format</b></td>
    <td><b class="Sy">Example</b></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#d"><code class="Li" id="d">d</code></a></td>
    <td>Decimal</td>
    <td>42</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#x"><code class="Li" id="x">x</code></a></td>
    <td>Lowercase hexadecimal</td>
    <td>2a</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#X"><code class="Li" id="X">X</code></a></td>
    <td>Uppercase hexadecimal</td>
    <td>2A</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#b"><code class="Li" id="b">b</code></a></td>
    <td>Binary</td>
    <td>101010
    <p class="Pp">Note that print types should only be used with numeric values,
        not strings.</p>
    <p class="Pp">HINT: The <b class="Sy">{symbol}</b> construct can also be
        used outside strings. The symbol's value is again inserted as a string.
        This is just a short way of doing &#x201C;{symbol}&#x201D;.</p>
    <p class="Pp">Whenever the macro-language expects a string you can actually
        use a string expression. This consists of one or more of these function
        (yes, you can nest them). Note that some of these functions actually
        return an integer and can be used as part of an integer expression!</p>
    <table class="Bl-column">
      <tr>
        <td><b class="Sy">Name</b></td>
        <td><b class="Sy">Operation</b></td>
      </tr>
      <tr>
        <td><code class="Fn">STRLEN</code>(<var class="Fa">string</var>)</td>
        <td>Returns the number of characters in string</td>
      </tr>
      <tr>
        <td><code class="Fn">STRCAT</code>(<var class="Fa">str1</var>,
          <var class="Fa">str2</var>)</td>
        <td>Appends str2 to str1.</td>
      </tr>
      <tr>
        <td><code class="Fn">STRCMP</code>(<var class="Fa">str1</var>,
          <var class="Fa">str2</var>)</td>
        <td>Returns negative if str1 is alphabetically lower than str2, zero if
          they match, positive if str1 is greater than str2.</td>
      </tr>
      <tr>
        <td><code class="Fn">STRIN</code>(<var class="Fa">str1</var>,
          <var class="Fa">str2</var>)</td>
        <td>Returns the position of str2 in str1 or zero if it's not present
          (first character is position 1).</td>
      </tr>
      <tr>
        <td><code class="Fn">STRSUB</code>(<var class="Fa">str</var>,
          <var class="Fa">pos</var>, <var class="Fa">len</var>)</td>
        <td>Returns a substring from str starting at pos (first character is
          position 1) and with len characters.</td>
      </tr>
      <tr>
        <td><code class="Fn">STRUPR</code>(<var class="Fa">str</var>)</td>
        <td>Converts all characters in str to capitals and returns the new
          string.</td>
      </tr>
      <tr>
        <td><code class="Fn">STRLWR</code>(<var class="Fa">str</var>)</td>
        <td>Converts all characters in str to lower case and returns the new
          string.</td>
      </tr>
    </table>
    </td>
  </tr>
</table>
</section>
<section class="Ss">
<h2 class="Ss" id="Character_maps"><a class="permalink" href="#Character_maps">Character
  maps</a></h2>
When writing text that is meant to be displayed in the Game Boy, the ASCII
  characters used in the source code may not be the same ones used in the
  tileset used in the ROM. For example, the tiles used for uppercase letters may
  be placed starting at tile index 128, which makes it difficult to add text
  strings to the ROM.
<p class="Pp">Character maps allow the code to map strings up to 16 characters
    long to an abitrary 8-bit value:</p>
<div class="Bd Pp Bd-indent">
<pre>
CHARMAP &quot;&lt;LF&gt;&quot;, 10
CHARMAP &quot;&amp;iacute&quot;, 20
CHARMAP &quot;A&quot;, 128
</pre>
</div>
<p class="Pp">It is possible to create multiple character maps and then switch
    between them as desired. This can be used to encode debug information in
    ASCII and use a different encoding for other purposes, for example.
    Initially, there is one character map called <b class="Sy">main</b> and it
    is automatically selected as the current character map from the beginning.
    There is also a character map stack that can be used to save and restore
    which character map is currently active.</p>
<table class="Bl-column">
  <tr>
    <td><b class="Sy">Command</b></td>
    <td><b class="Sy">Meaning</b></td>
  </tr>
  <tr>
    <td><a class="permalink" href="#NEWCHARMAP"><code class="Ic" id="NEWCHARMAP">NEWCHARMAP</code></a>
      <var class="Ar">name</var></td>
    <td>Creates a new, empty character map called
      <code class="Ic">name</code>.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#NEWCHARMAP_2"><code class="Ic" id="NEWCHARMAP_2">NEWCHARMAP</code></a>
      <var class="Ar">name</var>, <var class="Ar">basename</var></td>
    <td>Creates a new character map called <code class="Ic">name</code>, copied
      from character map <code class="Ic">basename</code>.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#SETCHARMAP"><code class="Ic" id="SETCHARMAP">SETCHARMAP</code></a>
      <var class="Ar">name</var></td>
    <td>Switch to character map <code class="Ic">name</code>.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#PUSHC"><code class="Ic" id="PUSHC">PUSHC</code></a></td>
    <td>Push the current character map onto the stack.</td>
  </tr>
  <tr>
    <td><a class="permalink" href="#POPC"><code class="Ic" id="POPC">POPC</code></a></td>
    <td>Pop a character map off the stack and switch to it.</td>
  </tr>
</table>
<p class="Pp"><b class="Sy">Note:</b> Character maps affect all strings in the
    file from the point in which they are defined, until switching to a
    different character map. This means that any string that the code may want
    to print as debug information will also be affected by it.</p>
<p class="Pp"><b class="Sy">Note:</b> The output value of a mapping can be 0. If
    this happens, the assembler will treat this as the end of the string and the
    rest of it will be trimmed.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Other_functions"><a class="permalink" href="#Other_functions">Other
  functions</a></h2>
There are a few other functions that do various useful things:
<table class="Bl-column">
  <tr>
    <td><b class="Sy">Name</b></td>
    <td><b class="Sy">Operation</b></td>
  </tr>
  <tr>
    <td><code class="Fn">BANK</code>(<var class="Fa">arg</var>)</td>
    <td>Returns a bank number. If <var class="Ar">arg</var> is the symbol
      <code class="Ic">@</code>, this function returns the bank of the current
      section. If <var class="Ar">arg</var> is a string, it returns the bank of
      the section that has that name. If <var class="Ar">arg</var> is a label,
      it returns the bank number the label is in. For labels, as the linker has
      to resolve this, it can't be used when the expression has to be
      constant.</td>
  </tr>
  <tr>
    <td><code class="Fn">DEF</code>(<var class="Fa">label</var>)</td>
    <td>Returns TRUE if <var class="Ar">label</var> has been defined.</td>
  </tr>
  <tr>
    <td><code class="Fn">HIGH</code>(<var class="Fa">arg</var>)</td>
    <td>Returns the top 8 bits of the operand if <var class="Ar">arg</var> is a
      label or constant, or the top 8-bit register if it is a 16-bit
      register.</td>
  </tr>
  <tr>
    <td><code class="Fn">LOW</code>(<var class="Fa">arg</var>)</td>
    <td>Returns the bottom 8 bits of the operand if <var class="Ar">arg</var> is
      a label or constant, or the bottom 8-bit register if it is a 16-bit
      register (AF isn't a valid register for this function).</td>
  </tr>
</table>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="MISCELLANEOUS"><a class="permalink" href="#MISCELLANEOUS">MISCELLANEOUS</a></h1>
<section class="Ss">
<h2 class="Ss" id="Changing_options_while_assembling"><a class="permalink" href="#Changing_options_while_assembling">Changing
  options while assembling</a></h2>
<code class="Ic">OPT</code> can be used to change some of the options during
  assembling the source instead of defining them on the commandline.
<p class="Pp"><code class="Ic">OPT</code> takes a comma-seperated list of
    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:
    <b class="Sy">b</b>, <b class="Sy">e</b> and <b class="Sy">g</b>.</p>
<p class="Pp"><code class="Ic">POPO</code> and <code class="Ic">PUSHO</code>
    provide the interface to the option stack. <code class="Ic">PUSHO</code>
    will push the current set of options on the option stack.
    <code class="Ic">POPO</code> can then later be used to restore them. Useful
    if you want to change some options in an include file and you don't want to
    destroy the options set by the program that included your file. The stacks
    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">rgbasm(1)</a>, <a class="Xr">rgblink(1)</a>,
  <a class="Xr">rgblink(5)</a>, <a class="Xr">rgbds(5)</a>,
  <a class="Xr">rgbds(7)</a>, <a class="Xr">gbz80(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<code class="Nm">rgbds</code> was originally written by Carsten S&#x00F8;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">March 13, 2018</td>
    <td class="foot-os">RGBDS Manual</td>
  </tr>
</table>
</body>
</html>