ref: f2b55527d53dcca25bf55976c5cf7921c3db93a1
parent: 84a6899c6c7603cc36e4cedacf97bce7c07c17eb
author: Antonio Niño Díaz <antonio_nd@outlook.com>
date: Fri Feb 23 18:55:58 EST 2018
Update html manpages Signed-off-by: Antonio Niño Díaz <antonio_nd@outlook.com>
--- a/docs/gbz80.7.html
+++ b/docs/gbz80.7.html
@@ -34,8 +34,12 @@
is assumed it's register <b class="Sy" title="Sy">A</b>. The following two
lines have the same effect:
<div class="Pp"></div>
-<div class="D1"><code class="Li">OR A,B</code></div>
-<div class="D1"><code class="Li">OR B</code></div>
+<div class="Bd" style="margin-left: 5.00ex;">
+<pre class="Li">
+OR A,B
+OR B
+</pre>
+</div>
<h1 class="Sh" title="Sh" id="LEGEND"><a class="selflink" href="#LEGEND">LEGEND</a></h1>
List of abbreviations used in this document.
<dl class="Bl-tag">
@@ -1689,7 +1693,7 @@
<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">January 26, 2018</td>
+ <td class="foot-date">February 23, 2018</td>
<td class="foot-os">RGBDS Manual</td>
</tr>
</table>
--- a/docs/rgbasm.5.html
+++ b/docs/rgbasm.5.html
@@ -38,7 +38,11 @@
<div class="Pp"></div>
Example:
<div class="Pp"></div>
-<div class="D1"><code class="Li">John: ld a,87 ;Weee</code></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.
@@ -47,13 +51,40 @@
the line. The most common one is: anything that follows a semicolon
";" (that isn't inside a string) is a comment. There is another
format: anything that follows a "*" that is placed right at the
- start of a line is a comment.
+ 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
+<div> </div>
+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>
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>
-<div class="D1"><code class="Li">SECTION "CoolStuff",ROMX</code></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 it defines it as a code section. All sections
@@ -139,25 +170,38 @@
obligation to follow any specific rules. The following example defines a
section that can be placed anywhere in any ROMX bank:
<div class="Pp"></div>
-<div class="D1"><code class="Li">SECTION "CoolStuff",ROMX</code></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 following syntax can be used to fix the base address of the
section:
<div class="Pp"></div>
-<div class="D1"><code class="Li">SECTION
- "CoolStuff",ROMX[$4567]</code></div>
+<div class="Bd" style="margin-left: 5.00ex;">
+<pre class="Li">
+ SECTION "CoolStuff",ROMX[$4567]
+</pre>
+</div>
<div class="Pp"></div>
It won't, however, fix the bank number, which is left to the linker. If you also
want to specify the bank you can do:
<div class="Pp"></div>
-<div class="D1"><code class="Li">SECTION
- "CoolStuff",ROMX[$4567],BANK[3]</code></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="D1"><code class="Li">SECTION
- "CoolStuff",ROMX,BANK[7]</code></div>
+<div class="Bd" style="margin-left: 5.00ex;">
+<pre class="Li">
+ SECTION "CoolStuff",ROMX,BANK[7]
+</pre>
+</div>
<div class="Pp"></div>
In addition, you can specify byte alignment for a section. This ensures that the
section starts at a memory address where the given number of least-significant
@@ -167,12 +211,14 @@
needed to align the start of an array to 256 bytes to optimize the code that
accesses it.
<div class="Pp"></div>
-<div class="D1"><code class="Li">SECTION "OAM Data",WRAM0,ALIGN[8];
- align to 256 bytes</code></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>
-<div class="D1"><code class="Li">SECTION "VRAM
- Data",ROMX,BANK[2],ALIGN[4]; align to 16 bytes</code></div>
-<div class="Pp"></div>
HINT: If you think this is a lot of typing for doing a simple
<b class="Ic" title="Ic">ORG</b> type thing you can quite easily write an
intelligent macro (called <b class="Ic" title="Ic">ORG</b> for example) that
@@ -260,8 +306,12 @@
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="D1"><code class="Li">EXIT_OK EQU $00</code></div>
- <div class="D1"><code class="Li">EXIT_FAILURE EQU $01</code></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
@@ -285,7 +335,11 @@
be exported and imported. Alternatively you can use = as a synonym for
SET.
<div class="Pp"></div>
- <div class="D1"><code class="Li">COUNT = 2</code></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>,
@@ -378,10 +432,10 @@
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
COUNTREG EQUS "[hl+]"
-ld a,COUNTREG
+ ld a,COUNTREG
PLAYER_NAME EQUS "\"John\""
-db PLAYER_NAME
+ db PLAYER_NAME
</pre>
</div>
<div class="Pp"></div>
@@ -390,13 +444,20 @@
<div class="Pp"></div>
This will be interpreted as:
<div class="Pp"></div>
- <div class="D1"><code class="Li">ld a,[hl+]</code></div>
- <div class="D1"><code class="Li">db "John"</code></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="D1"><code class="Li">PUSHA EQUS "push af\npush bc\npush
- de\npush hl\n"</code></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.
@@ -510,7 +571,11 @@
address and the second being a bytecount. The macro will then reset all
bytes in this range.
<div class="Pp"></div>
- <div class="D1"><code class="Li">LoopyMacro MyVars,54</code></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.
@@ -525,6 +590,21 @@
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>
@@ -710,8 +790,11 @@
<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="D1"><code class="Li">DB 1,2,3,4,"This is a
- string"</code></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
@@ -738,8 +821,11 @@
<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="D1"><code class="Li">DS str_SIZEOF ;allocate str_SIZEOF
- bytes</code></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
@@ -747,17 +833,23 @@
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="D1"><code class="Li">INCBIN "titlepic.bin"</code></div>
-<div class="D1"><code class="Li">INCBIN "sprites/hero.bin" ;
- UNIX</code></div>
-<div class="D1"><code class="Li">INCBIN "sprites\\hero.bin" ;
- Windows</code></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="D1"><code class="Li">INCBIN "data.bin",78,256</code></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,
@@ -872,7 +964,11 @@
<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="D1"><code class="Li">INCLUDE "irq.inc"</code></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>,
@@ -929,7 +1025,11 @@
actually pixel values and it converts the “chunky” data to
“planar” data as used in the Gameboy.
<div class="Pp"></div>
-<div class="D1"><code class="Li">DW `01012323</code></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
@@ -1465,7 +1565,7 @@
<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">February 24, 2018</td>
+ <td class="foot-date">February 26, 2018</td>
<td class="foot-os">RGBDS Manual</td>
</tr>
</table>