ref: 1f5ca39559d15895df8605e631a8581f9387bf61
parent: 5013b64f556fa8b185b09f23cf7f71908c4cd48b
parent: 5039af6af1affd60c71f1253b267972894c08119
author: Eldred Habert <[email protected]>
date: Fri Apr 3 07:56:41 EDT 2020
Merge pull request #494 from ISSOtm/docs Overhaul man pages
--- a/Makefile
+++ b/Makefile
@@ -197,15 +197,15 @@
MANDOC := -Thtml -Ios=General -Oman=%N.%S.html -Ostyle=mandoc.css
wwwman:
- $Qmandoc ${MANDOC} src/rgbds.7 > docs/rgbds.7.html- $Qmandoc ${MANDOC} src/gbz80.7 > docs/gbz80.7.html- $Qmandoc ${MANDOC} src/rgbds.5 > docs/rgbds.5.html- $Qmandoc ${MANDOC} src/asm/rgbasm.1 > docs/rgbasm.1.html- $Qmandoc ${MANDOC} src/asm/rgbasm.5 > docs/rgbasm.5.html- $Qmandoc ${MANDOC} src/fix/rgbfix.1 > docs/rgbfix.1.html- $Qmandoc ${MANDOC} src/link/rgblink.1 > docs/rgblink.1.html- $Qmandoc ${MANDOC} src/link/rgblink.5 > docs/rgblink.5.html- $Qmandoc ${MANDOC} src/gfx/rgbgfx.1 > docs/rgbgfx.1.html+ $Qmandoc ${MANDOC} src/rgbds.7 | src/doc_postproc.awk > docs/rgbds.7.html+ $Qmandoc ${MANDOC} src/gbz80.7 | src/doc_postproc.awk > docs/gbz80.7.html+ $Qmandoc ${MANDOC} src/rgbds.5 | src/doc_postproc.awk > docs/rgbds.5.html+ $Qmandoc ${MANDOC} src/asm/rgbasm.1 | src/doc_postproc.awk > docs/rgbasm.1.html+ $Qmandoc ${MANDOC} src/asm/rgbasm.5 | src/doc_postproc.awk > docs/rgbasm.5.html+ $Qmandoc ${MANDOC} src/fix/rgbfix.1 | src/doc_postproc.awk > docs/rgbfix.1.html+ $Qmandoc ${MANDOC} src/link/rgblink.1 | src/doc_postproc.awk > docs/rgblink.1.html+ $Qmandoc ${MANDOC} src/link/rgblink.5 | src/doc_postproc.awk > docs/rgblink.5.html+ $Qmandoc ${MANDOC} src/gfx/rgbgfx.1 | src/doc_postproc.awk > docs/rgbgfx.1.html# This target is used during development in order to prevent adding new issues
# to the source code. All warnings are treated as errors in order to block the
--- a/docs/mandoc.css
+++ b/docs/mandoc.css
@@ -1,20 +1,33 @@
-/* $Id: mandoc.css,v 1.22 2017/07/16 18:45:00 schwarze Exp $ */
+/* $Id: mandoc.css,v 1.45 2019/03/01 10:57:18 schwarze Exp $ */
/*
* Standard style sheet for mandoc(1) -Thtml and man.cgi(8).
+ *
+ * Written by Ingo Schwarze <[email protected]>.
+ * I place this file into the public domain.
+ * Permission to use, copy, modify, and distribute it for any purpose
+ * with or without fee is hereby granted, without any conditions.
*/
/* Global defaults. */
-html { max-width: 100ex; }+html { max-width: 65em; } body { font-family: Helvetica,Arial,sans-serif; } table { margin-top: 0em;- margin-bottom: 0em; }
-td { vertical-align: top; }+ margin-bottom: 0em;
+ border-collapse: collapse; }
+/* Some browsers set border-color in a browser style for tbody,
+ * but not for table, resulting in inconsistent border styling. */
+tbody { border-color: inherit; }+tr { border-color: inherit; }+td { vertical-align: top;+ padding-left: 0.2em;
+ padding-right: 0.2em;
+ border-color: inherit; }
ul, ol, dl { margin-top: 0em;margin-bottom: 0em; }
li, dt { margin-top: 1em; }-a.selflink { border-bottom: thin dotted;+.permalink { border-bottom: thin dotted;color: inherit;
font: inherit;
text-decoration: inherit; }
@@ -41,7 +54,6 @@
td.head-vol { text-align: center; } td.head-rtitle {text-align: right; }
-span.Nd { } table.foot { width: 100%;border-top: 1px dotted #808080;
@@ -51,147 +63,189 @@
/* Sections and paragraphs. */
-div.manual-text {- margin-left: 5ex; }
-h1.Sh { margin-top: 2ex;- margin-bottom: 1ex;
- margin-left: -4ex;
+.manual-text {+ margin-left: 3.8em; }
+.Nd { }+section.Sh { }+h1.Sh { margin-top: 1.2em;+ margin-bottom: 0.6em;
+ margin-left: -3.2em;
font-size: 110%; }
-h2.Ss { margin-top: 2ex;- margin-bottom: 1ex;
- margin-left: -2ex;
+section.Ss { }+h2.Ss { margin-top: 1.2em;+ margin-bottom: 0.6em;
+ margin-left: -1.2em;
font-size: 105%; }
-div.Pp { margin: 1ex 0ex; }-a.Sx { }-a.Xr { }+.Pp { margin: 0.6em 0em; }+.Sx { }+.Xr { }/* Displays and lists. */
-div.Bd { }-div.D1 { margin-left: 5ex; }+.Bd { }+.Bd-indent { margin-left: 3.8em; }-ul.Bl-bullet { list-style-type: disc;+.Bl-bullet { list-style-type: disc;padding-left: 1em; }
-li.It-bullet { }-ul.Bl-dash { list-style-type: none;+.Bl-bullet > li { }+.Bl-dash { list-style-type: none;padding-left: 0em; }
-li.It-dash:before {+.Bl-dash > li:before {content: "\2014 "; }
-ul.Bl-item { list-style-type: none;+.Bl-item { list-style-type: none;padding-left: 0em; }
-li.It-item { }-ul.Bl-compact > li {- margin-top: 0ex; }
+.Bl-item > li { }+.Bl-compact > li {+ margin-top: 0em; }
-ol.Bl-enum { padding-left: 2em; }-li.It-enum { }-ol.Bl-compact > li {- margin-top: 0ex; }
+.Bl-enum { padding-left: 2em; }+.Bl-enum > li { }+.Bl-compact > li {+ margin-top: 0em; }
-dl.Bl-diag { }-dt.It-diag { }-dd.It-diag { margin-left: 0ex; }-b.It-diag { font-style: normal; }-dl.Bl-hang { }-dt.It-hang { }-dd.It-hang { margin-left: 10.2ex; }-dl.Bl-inset { }-dt.It-inset { }-dd.It-inset { margin-left: 0ex; }-dl.Bl-ohang { }-dt.It-ohang { }-dd.It-ohang { margin-left: 0ex; }-dl.Bl-tag { margin-left: 10.2ex; }-dt.It-tag { float: left;- margin-top: 0ex;
- margin-left: -10.2ex;
- padding-right: 2ex;
+.Bl-diag { }+.Bl-diag > dt {+ font-style: normal;
+ font-weight: bold; }
+.Bl-diag > dd {+ margin-left: 0em; }
+.Bl-hang { }+.Bl-hang > dt { }+.Bl-hang > dd {+ margin-left: 5.5em; }
+.Bl-inset { }+.Bl-inset > dt { }+.Bl-inset > dd {+ margin-left: 0em; }
+.Bl-ohang { }+.Bl-ohang > dt { }+.Bl-ohang > dd {+ margin-left: 0em; }
+.Bl-tag { margin-top: 0.6em;+ margin-left: 5.5em; }
+.Bl-tag > dt {+ float: left;
+ margin-top: 0em;
+ margin-left: -5.5em;
+ padding-right: 0.5em;
vertical-align: top; }
-dd.It-tag { clear: right;+.Bl-tag > dd {+ clear: right;
width: 100%;
- margin-top: 0ex;
- margin-left: 0ex;
+ margin-top: 0em;
+ margin-left: 0em;
+ margin-bottom: 0.6em;
vertical-align: top;
overflow: auto; }
-dl.Bl-compact > dt {- margin-top: 0ex; }
+.Bl-compact { margin-top: 0em; }+.Bl-compact > dd {+ margin-bottom: 0em; }
+.Bl-compact > dt {+ margin-top: 0em; }
-table.Bl-column { }-tr.It-column { }-td.It-column { margin-top: 1em; }-table.Bl-compact > tbody > tr > td {- margin-top: 0ex; }
+.Bl-column { }+.Bl-column > tbody > tr { }+.Bl-column > tbody > tr > td {+ margin-top: 1em; }
+.Bl-compact > tbody > tr > td {+ margin-top: 0em; }
-cite.Rs { font-style: normal;+.Rs { font-style: normal;font-weight: normal; }
-span.RsA { }-i.RsB { font-weight: normal; }-span.RsC { }-span.RsD { }-i.RsI { font-weight: normal; }-i.RsJ { font-weight: normal; }-span.RsN { }-span.RsO { }-span.RsP { }-span.RsQ { }-span.RsR { }-span.RsT { text-decoration: underline; }-a.RsU { }-span.RsV { }+.RsA { }+.RsB { font-style: italic;+ font-weight: normal; }
+.RsC { }+.RsD { }+.RsI { font-style: italic;+ font-weight: normal; }
+.RsJ { font-style: italic;+ font-weight: normal; }
+.RsN { }+.RsO { }+.RsP { }+.RsQ { }+.RsR { }+.RsT { text-decoration: underline; }+.RsU { }+.RsV { }-span.eqn { }-table.tbl { }+.eqn { }+.tbl td { vertical-align: middle; }+.HP { margin-left: 3.8em;+ text-indent: -3.8em; }
+
/* Semantic markup for command line utilities. */
table.Nm { }-b.Nm { font-style: normal; }-b.Fl { font-style: normal; }-b.Cm { font-style: normal; }-var.Ar { font-style: italic;+code.Nm { font-style: normal;+ font-weight: bold;
+ font-family: inherit; }
+.Fl { font-style: normal;+ font-weight: bold;
+ font-family: inherit; }
+.Cm { font-style: normal;+ font-weight: bold;
+ font-family: inherit; }
+.Ar { font-style: italic;font-weight: normal; }
-span.Op { }-b.Ic { font-style: normal; }-code.Ev { font-style: normal;+.Op { display: inline; }+.Ic { font-style: normal;+ font-weight: bold;
+ font-family: inherit; }
+.Ev { font-style: normal;font-weight: normal;
font-family: monospace; }
-i.Pa { font-weight: normal; }+.Pa { font-style: italic;+ font-weight: normal; }
/* Semantic markup for function libraries. */
-span.Lb { }-b.In { font-style: normal; }+.Lb { }+code.In { font-style: normal;+ font-weight: bold;
+ font-family: inherit; }
a.In { }-b.Fd { font-style: normal; }-var.Ft { font-style: italic;+.Fd { font-style: normal;+ font-weight: bold;
+ font-family: inherit; }
+.Ft { font-style: italic;font-weight: normal; }
-b.Fn { font-style: normal; }-var.Fa { font-style: italic;+.Fn { font-style: normal;+ font-weight: bold;
+ font-family: inherit; }
+.Fa { font-style: italic;font-weight: normal; }
-var.Vt { font-style: italic;+.Vt { font-style: italic;font-weight: normal; }
-var.Va { font-style: italic;+.Va { font-style: italic;font-weight: normal; }
-code.Dv { font-style: normal;+.Dv { font-style: normal;font-weight: normal;
font-family: monospace; }
-code.Er { font-style: normal;+.Er { font-style: normal;font-weight: normal;
font-family: monospace; }
/* Various semantic markup. */
-span.An { }-a.Lk { }-a.Mt { }-b.Cd { font-style: normal; }-i.Ad { font-weight: normal; }-b.Ms { font-style: normal; }-span.St { }-a.Ux { }+.An { }+.Lk { }+.Mt { }+.Cd { font-style: normal;+ font-weight: bold;
+ font-family: inherit; }
+.Ad { font-style: italic;+ font-weight: normal; }
+.Ms { font-style: normal;+ font-weight: bold; }
+.St { }+.Ux { }/* Physical markup. */
+.Bf { display: inline; } .No { font-style: normal;font-weight: normal; }
.Em { font-style: italic;@@ -201,3 +255,93 @@
.Li { font-style: normal;font-weight: normal;
font-family: monospace; }
+
+/* Tooltip support. */
+
+h1.Sh, h2.Ss { position: relative; }+.An, .Ar, .Cd, .Cm, .Dv, .Em, .Er, .Ev, .Fa, .Fd, .Fl, .Fn, .Ft,
+.Ic, code.In, .Lb, .Lk, .Ms, .Mt, .Nd, code.Nm, .Pa, .Rs,
+.St, .Sx, .Sy, .Va, .Vt, .Xr {+ display: inline-block;
+ position: relative; }
+
+.An::before { content: "An"; }+.Ar::before { content: "Ar"; }+.Cd::before { content: "Cd"; }+.Cm::before { content: "Cm"; }+.Dv::before { content: "Dv"; }+.Em::before { content: "Em"; }+.Er::before { content: "Er"; }+.Ev::before { content: "Ev"; }+.Fa::before { content: "Fa"; }+.Fd::before { content: "Fd"; }+.Fl::before { content: "Fl"; }+.Fn::before { content: "Fn"; }+.Ft::before { content: "Ft"; }+.Ic::before { content: "Ic"; }+code.In::before { content: "In"; }+.Lb::before { content: "Lb"; }+.Lk::before { content: "Lk"; }+.Ms::before { content: "Ms"; }+.Mt::before { content: "Mt"; }+.Nd::before { content: "Nd"; }+code.Nm::before { content: "Nm"; }+.Pa::before { content: "Pa"; }+.Rs::before { content: "Rs"; }+h1.Sh::before { content: "Sh"; }+h2.Ss::before { content: "Ss"; }+.St::before { content: "St"; }+.Sx::before { content: "Sx"; }+.Sy::before { content: "Sy"; }+.Va::before { content: "Va"; }+.Vt::before { content: "Vt"; }+.Xr::before { content: "Xr"; }+
+.An::before, .Ar::before, .Cd::before, .Cm::before,
+.Dv::before, .Em::before, .Er::before, .Ev::before,
+.Fa::before, .Fd::before, .Fl::before, .Fn::before, .Ft::before,
+.Ic::before, code.In::before, .Lb::before, .Lk::before,
+.Ms::before, .Mt::before, .Nd::before, code.Nm::before,
+.Pa::before, .Rs::before,
+h1.Sh::before, h2.Ss::before, .St::before, .Sx::before, .Sy::before,
+.Va::before, .Vt::before, .Xr::before {+ opacity: 0;
+ transition: .15s ease opacity;
+ pointer-events: none;
+ position: absolute;
+ bottom: 100%;
+ box-shadow: 0 0 .35em #000;
+ padding: .15em .25em;
+ white-space: nowrap;
+ font-family: Helvetica,Arial,sans-serif;
+ font-style: normal;
+ font-weight: bold;
+ color: black;
+ background: #fff; }
+.An:hover::before, .Ar:hover::before, .Cd:hover::before, .Cm:hover::before,
+.Dv:hover::before, .Em:hover::before, .Er:hover::before, .Ev:hover::before,
+.Fa:hover::before, .Fd:hover::before, .Fl:hover::before, .Fn:hover::before,
+.Ft:hover::before, .Ic:hover::before, code.In:hover::before,
+.Lb:hover::before, .Lk:hover::before, .Ms:hover::before, .Mt:hover::before,
+.Nd:hover::before, code.Nm:hover::before, .Pa:hover::before,
+.Rs:hover::before, h1.Sh:hover::before, h2.Ss:hover::before, .St:hover::before,
+.Sx:hover::before, .Sy:hover::before, .Va:hover::before, .Vt:hover::before,
+.Xr:hover::before {+ opacity: 1;
+ pointer-events: inherit; }
+
+/* Overrides to avoid excessive margins on small devices. */
+
+@media (max-width: 37.5em) {+.manual-text {+ margin-left: 0.5em; }
+h1.Sh, h2.Ss { margin-left: 0em; }+.Bd-indent { margin-left: 2em; }+.Bl-hang > dd {+ margin-left: 2em; }
+.Bl-tag { margin-left: 2em; }+.Bl-tag > dt {+ margin-left: -2em; }
+.HP { margin-left: 2em;+ text-indent: -2em; }
+}
--- /dev/null
+++ b/docs/rgbds.css
@@ -1,0 +1,63 @@
+/* Overrides to default mandoc styling for HTML renders of RGBDS man pages */
+
+html {+ /* Reduce contrast */
+ background-color: #f8f8f8;
+ color: #222;
+
+ /* Override `mandoc.css`'s sowe can put it on <body> instead */
+ max-width: none;
+}
+
+body {+ /* Center body horizontally (requires <html> to span full width) */
+ margin: 0 auto;
+ /* `mandoc.css`'s default, but it's applied to <html> there */
+ max-width: 65em;
+
+ /* Improve readability */
+ font-size: 16px;
+ line-height: 1.4;
+ text-align: justify;
+
+ /* Prevent text from bumping sides on mobile devices */
+ padding: 10px 20px 10px 10px;
+}
+@media print {+ body {+ /* Max width doesn't make sense for print */
+ max-width: none;
+ /* Make font slightly smaller for printing */
+ font-size: 14px;
+ }
+}
+
+code, pre {+ font-size: smaller;
+}
+
+pre {+ /* Avoid horizontal page scrolling on mobile */
+ overflow: auto;
+}
+
+/* Separate lines in tables */
+table.Bl-column {+ border-collapse: collapse;
+}
+table.Bl-column tr:not(:first-child) > td,
+table.Bl-column tr:not(:first-child) > th {+ border-top: 1px solid #aaa;
+}
+
+table.Bl-column th {+ /* Apply `.Sy` style to table headers */
+ font-style: normal;
+ font-weight: bold;
+}
+
+table.Bl-column td,
+table.Bl-column th {+ /* Add horizontal spacing between columns */
+ padding: 2px 7px 0;
+}
--- a/src/asm/rgbasm.1
+++ b/src/asm/rgbasm.1
@@ -51,9 +51,9 @@
.It Fl D Ar name Ns Oo = Ns Ar value Oc , Fl Fl define Ar name Ns Oo = Ns Ar value Oc
Add a string symbol to the compiled source code.
This is equivalent to
-.Ql Ar name Ic EQUS Qq Ar value
+.Ql Ar name Ic EQUS \(dq Ns Ar value Ns \(dq
in code, or
-.Ql Ar name Ic EQUS Qq 1
+.Ql Ar name Ic EQUS \(dq1\(dq
if
.Ar value
is not specified.
@@ -153,7 +153,9 @@
Warns when
.Ic WARN Ns No -type
assertions fail. (See
-.Xr rgbasm 5 "Aborting the assembly process"
+.Dq Aborting the assembly process
+in
+.Xr rgbasm 5
for
.Ic ASSERT ) .
.It Fl Wbuiltin-args
@@ -182,37 +184,40 @@
Warn when obsolete constructs such as the
.Ic jp [hl]
instruction or
-.Cm HOME
+.Ic HOME
section type are encountered.
This warning is enabled by
.Fl Wextra .
.It Fl Wshift
-Warn when shifting triggers C undefined behavior, potentially causing unpredictable behavior.
-Shfting behavior will be changed and this warning removed before next release.
+Warn when shifting right a negative value.
+Use a division by 2^N instead.
+.It Fl Wshift-amount
+Warn when a shift's operand is negative or greater than 32.
+.It Fl Wno-truncation
+Warn when an implicit truncation (for example,
+.Ic db )
+loses some bits.
.It Fl Wno-user
-Warns when the
+Warn when the
.Ic WARN
built-in is executed. (See
-.Xr rgbasm 5 "Aborting the assembly process"
+.Dq Aborting the assembly process
+in
+.Xr rgbasm 5
for
.Ic WARN ) .
.El
.Sh EXAMPLES
You can assemble a source file in two ways.
+.Pp
Straightforward way:
+.Dl $ rgbasm -o bar.o foo.asm
.Pp
-.Bd -literal -offset indent
-$ rgbasm -o bar.o foo.asm
-.Ed
-.Pp
Pipes way:
+.Dl $ cat foo.asm | rgbasm -o bar.o -
+.Dl $ rgbasm -o bar.o - < foo.asm
.Pp
-.Bd -literal -offset indent
-$ cat foo.asm | rgbasm -o bar.o -
-$ rgbasm -o bar.o - < foo.asm
-.Ed
-.Pp
-The resulting object file is not yet a usable ROM image \(em it must first be run through
+The resulting object file is not yet a usable ROM image\(emit must first be run through
.Xr rgblink 1
and then
.Xr rgbfix 1 .
--- a/src/asm/rgbasm.5
+++ b/src/asm/rgbasm.5
@@ -12,42 +12,55 @@
.Nm rgbasm
.Nd language documentation
.Sh DESCRIPTION
+.Pp
This is the full description of the language used by
.Xr rgbasm 1 .
The description of the instructions supported by the Game Boy CPU is in
.Xr gbz80 7 .
.Pp
-.Sh GENERAL
-.Ss Syntax
+It is strongly recommended to have some familiarity with the Game Boy hardware before reading this document.
+RGBDS is specifically targeted at the Game Boy, and thus a lot of its features tie directly to its concepts.
+This document is not intended to be a Game Boy hardware reference.
+.Pp
+Generally,
+.Dq the linker
+will refer to
+.Xr rgblink 1 ,
+but any program that processes RGB object files (described in
+.Xr rgbds 5 )
+can be used in its place.
+.Sh SYNTAX
+.Pp
The syntax is line‐based, just as in any other assembler, meaning that you do one instruction or pseudo‐op per line:
.Pp
.Dl Oo Ar label Oc Oo Ar instruction Oc Oo Ar ;\ comment Oc
.Pp
Example:
-.Pp
.Bd -literal -offset indent
John: ld a,87 ;Weee
.Ed
.Pp
-All pseudo‐ops, mnemonics and registers (reserved keywords) are case‐insensitive
-and all labels are case‐sensitive.
+All reserved keywords (pseudo‐ops, mnemonics, registers etc.) are case‐insensitive, all identifiers (symbol names) are case-sensitive.
.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
+Comments are used to give humans information about the code, such as explanations.
+The assembler
+.Em always
+ignores comments and their contents.
+.Pp
+There are two syntaxes for comments. The most common is that anything that follows a semicolon
.Ql \&;
-that isn't inside a string is a comment.
-There is another format: anything that follows a
+not inside a string, is a comment until the end of the line.
+The other is that lines beginning with a
.Ql *
-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.
+(not even spaces before it) are ignored.
+This second syntax is deprecated (will be removed in a future version) and should be replaced with the first one.
.Pp
Sometimes lines can be too long and it may be necessary to split them.
-The syntax to do so is the following one:
-.Pp
+To do so, put a backslash at the end of the line:
.Bd -literal -offset indent
- DB 1, 2, 3, 4 \[rs]
- 5, 6, 7, 8
+ DB 1, 2, 3,\ \[rs]
+ 4, 5, 6,\ \[rs]\ ;\ Put it before any comments
+ 7, 8, 9
.Ed
.Pp
This works anywhere in the code except inside of strings.
@@ -54,26 +67,306 @@
To split strings it is needed to use
.Fn STRCAT
like this:
-.Pp
.Bd -literal -offset indent
- db STRCAT("Hello ", \[rs]+ db STRCAT("Hello ",\ \[rs]"world!")
.Ed
+.Sh EXPRESSIONS
.Pp
-.Ss Sections
-.Ic SECTION Ar name , type
+An expression can be composed of many things.
+Numerical expressions are always evaluated using signed 32-bit math.
+Zero is considered to be the only "false" number, all non-zero numbers (including negative) are "true".
.Pp
-.Ic SECTION Ar name , type , options
+An expression is said to be "constant" if
+.Nm
+knows its value.
+This is generally always the case, unless a label is involved, as explained in the
+.Sx SYMBOLS
+section.
.Pp
-.Ic SECTION Ar name , type Ns Bo Ar addr Bc
+The instructions in the macro-language generally require constant expressions.
+.Ss Numeric Formats
.Pp
-.Ic SECTION Ar name , type Ns Bo Ar addr Bc , Ar options
+There are a number of numeric formats.
.Pp
+.Bl -column -offset indent "Fixed point (16.16)" "Prefix"
+.It Sy Format type Ta Sy Prefix Ta Sy Accepted characters
+.It Hexadecimal Ta $ Ta 0123456789ABCDEF
+.It Decimal Ta none Ta 0123456789
+.It Octal Ta & Ta 01234567
+.It Binary Ta % Ta 01
+.It Fixed point (16.16) Ta none Ta 01234.56789
+.It Character constant Ta none Ta \(dqABYZ\(dq
+.It Gameboy graphics Ta \` Ta 0123
+.El
+.Pp
+The "character constant" form yields the value the character maps to in the current charmap.
+For example, by default
+.Pq refer to Xr ascii 7
+.Sq \(dqA\(dq
+yields 65.
+See
+.Sx Character maps
+for information on charmaps.
+.Pp
+The last one, Gameboy graphics, is quite interesting and useful.
+After the backtick, 8 digits between 0 and 3 are expected, corresponding to pixel values.
+The resulting value is the two bytes of tile data that would produce that row of pixels.
+For example,
+.Sq \`01012323
+is equivalent to
+.Sq $0F55 .
+.Pp
+You can also use symbols, which are implicitly replaced with their value.
+.Ss Operators
+.Pp
+A great number of operators you can use in expressions are available (listed from highest to lowest precedence):
+.Pp
+.Bl -column -offset indent "!= == <= >= < >"
+.It Sy Operator Ta Sy Meaning
+.It Li \&( \&) Ta Precedence override
+.It Li FUNC() Ta Built-in function call
+.It Li ~ + - Ta Unary complement/plus/minus
+.It Li * / % Ta Multiply/divide/modulo
+.It Li << >> Ta Shift left/right
+.It Li & \&| ^ Ta Binary and/or/xor
+.It Li + - Ta Add/subtract
+.It Li != == <= >= < > Ta Comparison
+.It Li && || Ta Boolean and/or
+.It Li \&! Ta Unary not
+.El
+.Pp
+.Ic ~
+complements a value by inverting all its bits.
+.Pp
+.Ic %
+is used to get the remainder of the corresponding division.
+.Sq 5 % 2
+is 1.
+.Pp
+Shifting works by shifting all bits in the left operand either left
+.Pq Sq <<
+or right
+.Pq Sq >>
+by the right operand's amount.
+When shifting left, all newly-inserted bits are reset; when shifting right, they are copies of the original most significant bit instead.
+This makes
+.Sq a << b
+and
+.Sq a >> b
+equivalent to multiplying and dividing by 2 to the power of b, respectively.
+.Pp
+Comparison operators return 0 if the comparison is false, and 1 otherwise.
+.Pp
+Unlike in a lot of languages, and for technical reasons,
+.Nm
+still evaluates both operands of
+.Sq &&
+and
+.Sq || .
+.Pp
+! returns 1 if the operand was 0, and 1 otherwise.
+.Ss Fixed‐point Expressions
+.Pp
+Fixed-point numbers are basically normal (32-bit) integers, which count 65536th's instead of entire units, offering better precision than integers but limiting the range of values.
+The upper 16 bits are used for the integer part and the lower 16 bits are used for the fraction (65536ths).
+Since they are still akin to integers, you can use them in normal integer expressions, and some integer operators like
+.Sq +
+and
+.Sq -
+don't care whether the operands are integers or fixed-point.
+You can easily truncate a fixed-point number into an integer by shifting it right by 16 bits.
+It follows that you can convert an integer to a fixed-point number by shifting it left.
+.Pp
+The following functions are designed to operate with fixed-point numbers:
+.EQ
+delim $$
+.EN
+.Pp
+.Bl -column -offset indent "ATAN2(x, y)"
+.It Sy Name Ta Sy Operation
+.It Fn DIV x y Ta $x \[di] y$
+.It Fn MUL x y Ta $x \[mu] y$
+.It Fn SIN x Ta $sin ( x )$
+.It Fn COS x Ta $cos ( x )$
+.It Fn TAN x Ta $tan ( x )$
+.It Fn ASIN x Ta $asin ( x )$
+.It Fn ACOS x Ta $acos ( x )$
+.It Fn ATAN x Ta $atan ( x )$
+.It Fn ATAN2 x y Ta Angle between $( x , y )$ and $( 1 , 0 )$
+.El
+.EQ
+delim off
+.EN
+.Pp
+These functions are useful for automatic generation of various tables.
+Example: assuming a circle has 65536.0 degrees, and sine values are in range
+.Bq -1.0 ;\ 1.0 :
+.Bd -literal -offset indent
+;\ --
+;\ -- Generate a 256-byte sine table with values between 0 and 128
+;\ --
+ANGLE = 0.0
+ REPT 256
+ db MUL(64.0, SIN(ANGLE) + 1.0) >> 16
+ANGLE = ANGLE + 256.0 ; 256 = 65536 / table_len, with table_len = 256
+ ENDR
+.Ed
+.Ss String Expressions
+.Pp
+The most basic string expression is any number of characters contained in double quotes
+.Pq Ql \&"for instance" .
+The backslash character
+.Ql \[rs]
+is special in that it causes the character following it to be
+.Dq escaped ,
+meaning that it is treated differently from normal.
+There are a number of escape sequences you can use within a string:
+.Pp
+.Bl -column -offset indent "'\1' - '\9'"
+.It Sy String Ta Sy Meaning
+.It Ql \[rs]\[rs] Ta Produces a backslash
+.It Ql \[rs]" Ta Produces a double quote without terminating
+.It Ql \[rs], Ta Comma
+.It Ql \[rs]{ Ta Curly bracket left+.It Ql \[rs]} Ta Curly bracket right
+.It Ql \[rs]n Ta Newline ($0A)
+.It Ql \[rs]r Ta Carriage return ($0D)
+.It Ql \[rs]t Ta Tab ($09)
+.It Qo \[rs]1 Qc \[en] Qo \[rs]9 Qc Ta Macro argument (Only the body of a macro, see Sx Invoking macros )
+.It Ql \[rs]@ Ta Label name suffix (Only in the body of macros and REPTs)
+.El
+(Note that some of those can be used outside of strings, when noted further in this document.)
+.Pp
+A funky feature is
+.Ql {symbol}+within a string, called
+.Dq symbol interpolation .
+This will paste
+.Ar symbol Ap s
+contents as a string.
+If it's a string symbol, the string is simply inserted.
+If it's a numeric symbol, its value is converted to hexadecimal notation with a dollar sign
+.Sq $
+prepended.
+.Bd -literal -offset indent
+TOPIC equs "life, the universe, and everything"
+ANSWER = 42
+;\ Prints "The answer to life, the universe, and everything is $2A"
+PRINTT "The answer to {TOPIC} is {ANSWER}\[rs]n"+.Ed
+.Pp
+Symbol interpolations can be nested, too!
+.Pp
+It's possible to change the way numeric symbols are converted by specifying a print type like so:
+.Ql {d:symbol} .+Valid print types are:
+.Bl -column -offset indent "Print type" "Lowercase hexadecimal" "Example"
+.It Sy Print type Ta Sy Format Ta Sy Example
+.It Ql d Ta Decimal Ta 42
+.It Ql x Ta Lowercase hexadecimal Ta 2a
+.It Ql X Ta Uppercase hexadecimal Ta 2A
+.It Ql b Ta Binary Ta 101010
+.El
+.Pp
+Note that print types should only be used with numeric values, not strings.
+.Pp
+HINT: The
+.Ic {symbol}+construct can also be used outside strings.
+The symbol's value is again inserted directly.
+.Pp
+The following functions operate on string expressions.
+Most of them return a string, however some of these functions actually return an integer and can be used as part of an integer expression!
+.Pp
+.Bl -column "STRSUB(str, pos, len)"
+.It Sy Name Ta Sy Operation
+.It Fn STRLEN string Ta Returns the number of characters in Ar string .
+.It Fn STRCAT str1 str2 Ta Appends Ar str2 No to Ar str1 .
+.It Fn STRCMP str1 str2 Ta Returns negative if Ar str1 No is alphabetically lower than Ar str2 No , zero if they match, positive if Ar str1 No is greater than Ar str2 .
+.It Fn STRIN str1 str2 Ta Returns the position of Ar str2 No in Ar str1 No or zero if it's not present Pq first character is position 1 .
+.It Fn STRSUB str pos len Ta Returns a substring from Ar str No starting at Ar pos Po first character is position 1 Pc and Ar len No characters long.
+.It Fn STRUPR str Ta Converts all characters in Ar str No to capitals and returns the new string.
+.It Fn STRLWR str Ta Converts all characters in Ar str No to lower case and returns the new string.
+.El
+.Ss Character maps
+.Pp
+When writing text that is meant to be displayed in the Game Boy, the characters used in the source code may have a different encoding than the default of ASCII.
+For example, the tiles used for uppercase letters may be placed starting at tile index 128, which makes it difficult to add text strings to the ROM.
+.Pp
+Character maps allow mapping strings up to 16 characters long to an abitrary 8-bit value:
+.Bd -literal -offset indent
+CHARMAP "<LF>", 10
+CHARMAP "í", 20
+CHARMAP "A", 128
+.Ed
+By default, a character map contains ASCII encoding.
+.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
+.Sq main
+and it is automatically selected as the current character map from the beginning.
+There is also a character map stack that can be used to save and restore which character map is currently active.
+.Bl -column "NEWCHARMAP name, basename"
+.It Sy Command Ta Sy Meaning
+.It Ic NEWCHARMAP Ar name Ta Creates a new, empty character map called Ar name .
+.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename .
+.It Ic SETCHARMAP Ar name Ta Switch to character map Ar name .
+.It Ic PUSHC Ta Push the current character map onto the stack.
+.It Ic POPC Ta Pop a character map off the stack and switch to it.
+.El
+.Pp
+.Sy Note:
+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.
+.Pp
+.Sy Note:
+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.
+.Ss Other functions
+.Pp
+There are a few other functions that do various useful things:
+.Pp
+.Bl -column "DEF(label)"
+.It Sy Name Ta Sy Operation
+.It Fn BANK arg Ta Returns a bank number.
+If
+.Ar arg
+is the symbol
+.Ic @ ,
+this function returns the bank of the current section.
+If
+.Ar arg
+is a string, it returns the bank of the section that has that name.
+If
+.Ar arg
+is a label, it returns the bank number the label is in.
+The result may be constant if
+.Nm
+is able to compute it.
+.It Fn DEF label Ta Returns TRUE (1) if
+.Ar label
+has been defined, FALSE (0) otherwise.
+String symbols are not expanded within the parentheses.
+.It Fn HIGH arg Ta Returns the top 8 bits of the operand if Ar arg No is a label or constant, or the top 8-bit register if it is a 16-bit register.
+.It Fn LOW arg Ta Returns the bottom 8 bits of the operand if Ar arg No is a label or constant, or the bottom 8-bit register if it is a 16-bit register Pq Cm AF No isn't a valid register for this function .
+.It Fn ISCONST arg Ta Returns 1 if Ar arg Ap s value is known by RGBASM (e.g. if it can be an argument to
+.Ic IF ) ,
+or 0 if only RGBLINK can compute its value.
+.El
+.Sh SECTIONS
+.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.
.Pp
+.Dl SECTION Ar name , type
+.Dl SECTION Ar name , type , options
+.Dl SECTION Ar name , type Ns Bo Ar addr Bc
+.Dl SECTION Ar name , type Ns Bo Ar addr Bc , Ar options
+.Pp
.Ar name
-is a string enclosed in double quotes and can be a new name or the name of an existing section.
+is a string enclosed in double quotes, and can be a new name or the name of an existing section.
All sections assembled at the same time that have the same name are considered to be the same section, and their code is put together in the object file generated by the assembler.
If the type doesn't match, an error occurs.
All other sections must have a unique name, even in different source files, or the linker will treat it as an error.
@@ -83,7 +376,7 @@
are as follows:
.Pp
.Bl -tag
-.It Cm ROM0
+.It Ic ROM0
A ROM section.
.Ar addr
can range from
@@ -94,9 +387,8 @@
.Ad $0000
to
.Ad $7FFF
-if tiny ROM mode is enabled in
-.Xr rgblink 1 .
-.It Cm ROMX
+if tiny ROM mode is enabled in the linker.
+.It Ic ROMX
A banked ROM section.
.Ar addr
can range from
@@ -105,9 +397,10 @@
.Ad $7FFF .
.Ar bank
can range from 1 to 511.
-Not available if tiny ROM mode is enabled in
-.Xr rgblink 1 .
-.It Cm VRAM
+Becomes an alias for
+.Ic ROM0
+if tiny ROM mode is enabled in the linker.
+.It Ic VRAM
A banked video RAM section.
.Ar addr
can range from
@@ -115,12 +408,8 @@
to
.Ad $9FFF .
.Ar bank
-can be 0 or 1 but bank 1 is unavailable if DMG mode is enabled in
-.Xr rgblink 1 .
-Memory in this section can only be allocated with
-.Sy DS ,
-not filled with data.
-.It Cm SRAM
+can be 0 or 1, but bank 1 is unavailable if DMG mode is enabled in the linker.
+.It Ic SRAM
A banked external (save) RAM section.
.Ar addr
can range from
@@ -129,10 +418,7 @@
.Ad $BFFF .
.Ar bank
can range from 0 to 15.
-Memory in this section can only be allocated with
-.Sy DS ,
-not filled with data.
-.It Cm WRAM0
+.It Ic WRAM0
A general-purpose RAM section.
.Ar addr
can range from
@@ -143,12 +429,8 @@
.Ad $C000
to
.Ad $DFFF
-if DMG mode is enabled in
-.Xr rgblink 1 .
-Memory in this section can only be allocated with
-.Sy DS ,
-not filled with data.
-.It Cm WRAMX
+if WRAM0 mode is enabled in the linker.
+.It Ic WRAMX
A banked general-purpose RAM section.
.Ar addr
can range from
@@ -157,12 +439,10 @@
.Ad $DFFF .
.Ar bank
can range from 1 to 7.
-Not available if DMG mode is enabled in
-.Xr rgblink 1 .
-Memory in this section can only be allocated with
-.Sy DS ,
-not filled with data.
-.It Cm OAM
+Becomes an alias for
+.Ic WRAM0
+if WRAM0 mode is enabled in the linker.
+.It Ic OAM
An object attribute RAM section.
.Ar addr
can range from
@@ -169,52 +449,56 @@
.Ad $FE00
to
.Ad $FE9F .
-Memory in this section can only be allocated with
-.Sy DS ,
-not filled with data.
-.It Cm HRAM
+.It Ic HRAM
A high RAM section.
.Ar addr
can range from
.Ad $FF80
to
-.Ad $FFFE.
-Memory in this section can only be allocated with
-.Sy DS ,
-not filled with data.
+.Ad $FFFE .
.Pp
.Sy Note :
-If you use this method of allocating HRAM the assembler will
-.Em not
-choose the short addressing mode in the LD instructions
-.Ic ld [$FF00+n8],A
-and
-.Ic ld A,[$FF00+n8]
-because the actual address calculation is done by the linker.
-If you find this undesirable you can use
-.Ic RSSET , RB ,
-or
-.Ic RW
-instead or use the
-.Sy ldh [$FF00+n8],A
-and
-.Sy ldh A,[$FF00+n8]
-syntax instead.
-This forces the assembler to emit the correct instruction and the linker to check if the value is in the correct range.
+While
+.Nm
+will automatically optimize
+.Ic ld
+instructions to the smaller and faster
+.Ic ldh
+(see
+.Xr gbz80 7 )
+whenever possible, it is generally unable to do so when a label is involved.
+Using the
+.Ic ldh
+instruction directly is recommended.
+This forces the assembler to emit a
+.Ic ldh
+instruction and the linker to check if the value is in the correct range.
.El
.Pp
+Since RGBDS produces ROMs, code and data can only be placed in
+.Ic ROM0
+and
+.Ic ROMX
+sections.
+To put some in RAM, have it stored in ROM, and copy it to RAM.
+.Pp
.Ar option Ns s are comma-separated and may include:
.Bl -tag
-.It Cm BANK Ns Bq Ar bank
+.It Ic BANK Ns Bq Ar bank
Specify which
.Ar bank
-for the linker to place the section.
-.It Cm ALIGN Ns Bq Ar align
+for the linker to place the section in.
+See above for possible values for
+.Ar bank ,
+depending on
+.Ar type .
+.It Ic ALIGN Ns Bq Ar align
Place the section at an address whose
.Ar align
least‐significant bits are zero.
-It is a syntax error to use this option with
-.Ar addr .
+This option can be used with
+.Ar addr ,
+as long as they don't contradict eachother.
.El
.Pp
If
@@ -223,7 +507,7 @@
.Dq floating ;
the linker will automatically calculate an appropriate address for the section.
Similarly, if
-.Cm BANK Ns Bq Ar bank
+.Ic BANK Ns Bq Ar bank
is not specified, the linker will automatically find a bank with enough space.
.Pp
Sections can also be placed by using a linker script file.
@@ -233,72 +517,57 @@
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.
.Pp
Section examples:
+.Bl -item
+.It
.Bd -literal -offset indent
- SECTION "CoolStuff",ROMX
+SECTION "CoolStuff",ROMX
.Ed
-.Pp
This switches to the section called
-.Dq CoolStuff
-(or creates it if it doesn't already exist) and defines it as a code section.
-.Pp
-The following example defines a section that can be placed anywhere in any ROMX
-bank:
-.Pp
-.Bd -literal -offset indent
- SECTION "CoolStuff",ROMX
-.Ed
-.Pp
+.Dq CoolStuff ,
+creating it if it doesn't already exist.
+It can end up in any ROM bank.
+Code and data may follow.
+.It
If it is needed, the the base address of the section can be specified:
-.Pp
.Bd -literal -offset indent
- SECTION "CoolStuff",ROMX[$4567]
+SECTION "CoolStuff",ROMX[$4567]
.Ed
-.Pp
+.It
An example with a fixed bank:
-.Pp
.Bd -literal -offset indent
- SECTION "CoolStuff",ROMX[$4567],BANK[3]
+SECTION "CoolStuff",ROMX[$4567],BANK[3]
.Ed
-.Pp
-And if you only want to force the section into a certain bank, and not its position within the bank, that's also possible:
-.Pp
+.It
+And if you want to force only the section's bank, and not its position within the bank, that's also possible:
.Bd -literal -offset indent
- SECTION "CoolStuff",ROMX,BANK[7]
+SECTION "CoolStuff",ROMX,BANK[7]
.Ed
-.Pp
+.It
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.
-.Pp
+The first one could be useful for defining an OAM buffer to be DMA'd, since it must be aligned to 256 bytes.
+The second could also be appropriate for GBC HDMA, or for an optimized copy code that requires alignment.
.Bd -literal -offset indent
- SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes
-
- SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ; align to 16 bytes
+SECTION "OAM Data",WRAM0,ALIGN[8] ;\ align to 256 bytes
+SECTION "VRAM Data",ROMX,BANK[2],ALIGN[4] ;\ align to 16 bytes
.Ed
-.Pp
-.Sy Hint :
-If you think this is a lot of typing for doing a simple
-.Dq org
-type thing you can quite easily write an intelligent macro (called
-.Ic ORG
-for example) that uses
-.Ic \[rs]@
-for the section name, and determines the correct section type etc. as arguments for
-.Ic SECTION .
+.El
.Ss Section Stack
+.Pp
.Ic POPS
and
.Ic PUSHS
provide the interface to the section stack.
+The number of entries in the stack is limited only by the amount of memory in your machine.
.Pp
.Ic PUSHS
will push the current section context on the section stack.
.Ic POPS
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.
+Useful for defining sections in included files when you don't want to override the section context at the point the file was included.
.Ss RAM Code
+.Pp
Sometimes you want to have some code in RAM.
-But then you can't simply put it in a RAM section, you have to store it in ROM and copy it to RAM at some time.
+But then you can't simply put it in a RAM section, you have to store it in ROM and copy it to RAM at some point.
.Pp
This means the code (or data) will not be stored in the place it gets executed.
Luckily,
@@ -306,36 +575,36 @@
blocks are the perfect solution to that.
Here's an example of how to use them:
.Bd -literal -offset indent
- SECTION "LOAD example", ROMX
- CopyCode:
- ld de, RAMCode
- ld hl, RAMLocation
- ld c, RAMLocation.end - RAMLocation
- .loop
- ld a, [de]
- inc de
- ld [hli], a
- dec c
- jr nz, .loop
- ret
+SECTION "LOAD example", ROMX
+CopyCode:
+ ld de, RAMCode
+ ld hl, RAMLocation
+ ld c, RAMLocation.end - RAMLocation
+\&.loop
+ ld a, [de]
+ inc de
+ ld [hli], a
+ dec c
+ jr nz, .loop
+ ret
- RAMCode:
- LOAD "RAM code", WRAM0
- RAMLocation:
- ld hl, .string
- ld de, $9864
- .copy
- ld a, [hli]
- ld [de], a
- inc de
- and a
- jr nz, .copy
- ret
+RAMCode:
+ LOAD "RAM code", WRAM0
+RAMLocation:
+ ld hl, .string
+ ld de, $9864
+\&.copy
+ ld a, [hli]
+ ld [de], a
+ inc de
+ and a
+ jr nz, .copy
+ ret
- .string
- db "Hello World!", 0
- .end
- ENDL
+\&.string
+ db "Hello World!", 0
+\&.end
+ ENDL
.Ed
.Pp
A
@@ -343,13 +612,13 @@
block feels similar to a
.Ic SECTION
declaration because it creates a new one.
-All data and code generated within such a block is placed in the current section like usual, but all labels are created as if the it was placed in this newly-created section.
+All data and code generated within such a block is placed in the current section like usual, but all labels are created as if they were placed in this newly-created section.
.Pp
In the example above, all of the code and data will end up in the "LOAD example" section.
You will notice the
-.Ic RAMCode
+.Sq RAMCode
and
-.Ic RAMLocation
+.Sq RAMLocation
labels.
The former is situated in ROM, where the code is stored, the latter in RAM, where the code will be loaded.
.Pp
@@ -356,111 +625,153 @@
You cannot nest
.Ic LOAD
blocks, nor can you change the current section within them.
+.Ss Unionized Sections
+.Pp
+When you're tight on RAM, you may want to define overlapping blocks of variables, as explained in the
+.Sx Unions
+section.
+However, the
+.Ic UNION
+keyword only works within a single file, which prevents e.g. defining temporary variables on a single memory area across several files.
+Unionized sections solve this problem.
+To declare an unionized section, add a
+.Ic UNION
+keyword after the
+.Ic SECTION
+one; the declaration is otherwise not different.
+Unionized sections follow some different rules from normal sections:
+.Bl -bullet -offset indent
+.It
+The same unionized section (= having the same name) can be declared several times per
+.Nm
+invocation, and across several invocations.
+Different declarations are treated and merged identically whether within the same invocation, or different ones.
+.It
+A section cannot be declared both as unionized or non-unionized.
+.It
+All declarations must have the same type.
+For example, even if
+.Xr rgblink 1 Ap s
+.Fl w
+flag is used,
+.Ic WRAM0
+and
+.Ic WRAMX
+types are still considered different.
+.It
+Different constraints (alignment, bank, etc.) can be specified for each unionized section declaration, but they must all be compatible.
+For example, alignment must be compatible with any fixed address, all specified banks must be the same, etc.
+.It
+Unionized sections cannot have type
+.Ic ROM0
+or
+.Ic ROMX .
+.El
+.Pp
+Different declarations of the same unionized section are not appended, but instead overlaid on top of eachother, just like
+.Sx Unions .
+Similarly, the size of an unionized section is the largest of all its declarations.
.Sh SYMBOLS
.Pp
-.Ss Symbols
RGBDS supports several types of symbols:
.Pp
.Bl -hang
.It Sy Label
-Used to give a name to a memory location.
-.It Sy EQUate
-Give a constant a name.
-.It Ic SET
-Almost the same as EQUate, but you can change the value of a SET during assembling.
-.It Sy Structure Pq Sy the RS group
-Define a structure easily.
-.It Sy String equate Pq Ic EQUS
-Give a frequently used string a name.
-Can also be used as a mini-macro, like
-.Fd #define
-in C.
-.It Ic MACRO
-A block of code or pseudo instructions that you invoke like any other mnemonic.
-You can give them arguments too.
+Numerical symbol designating a memory location. May or may not have a value known at assembly time.
+.It Sy Constant
+Numerical symbol whose value has to be known at assembly time.
+.It Sy Macro
+A block of
+.Nm
+code that can be invoked later.
+.It Sy String equate
+String symbol that can be evaluated, similarly to a macro.
.El
.Pp
+Symbol names can contain letters, numbers, underscores, hashes and
+.Sq @ .
+However, they must begin with either a letter, a number, or an underscore.
+Periods are allowed exclusively for labels, as described below.
A symbol cannot have the same name as a reserved keyword.
-.Bl -hang
-.It Sy Label
+.Em \&In the line where a symbol is defined there mustn't be any whitespace before it ,
+otherwise
+.Nm
+will treat it as a macro invocation.
+.Bl -tag -width indent
+.It Sy Label declaration
+One of the assembler's main tasks is to keep track of addresses for you, so you can work with meaningful names instead of "magic" numbers.
.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.
-.Pp
This can be done in a number of ways:
-.Pp
.Bd -literal -offset indent
-GlobalLabel
-AnotherGlobal:
+GlobalLabel ;\ This syntax is deprecated,
+AnotherGlobal: ;\ please use this instead
\&.locallabel
\&.yet_a_local:
AnotherGlobal.with_another_local:
-ThisWillBeExported:: ;note the two colons
+ThisWillBeExported:: ;\ Note the two colons
ThisWillBeExported.too::
.Ed
.Pp
-.Em \&In the line where a label is defined there mustn'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
+Declaring a label (global or local) with
+.Ql ::
+does an
.Ic EXPORT
at the same time.
(See
.Sx Exporting and importing symbols
below).
+.Pp
+Any label whose name does not contain a period is a global label, others are locals.
+Declaring a global label sets it as the current label scope until the next one; any local label whose first character is a period will have the global label's name implicitly prepended.
Local labels can be declared as
-.Ql scope.local
+.Ql scope.local:
or simply as as
-.Ql .local .
-If the former notation is used, the scope must be the actual current scope.
+.Ql .local: .
+If the former notation is used, then
+.Ql scope
+must be the actual current scope.
.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.
+A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants.
+However, if the section in which the label is declared has a fixed base address, its value is known at assembly time.
.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.
-.Pp
+.Nm
+is able to compute the subtraction of two labels either if both are constant as described above, or if both belong to the same section.
.It Ic EQU
-.Pp
-EQUates are constant symbols, and can be imported or exported.
+.Ic EQU
+allows defining constant symbols.
+Unlike
+.Ic SET
+below, constants defined this way cannot be redefined.
They can, for example, be used for things such as bit definitions of hardware registers.
-.Pp
.Bd -literal -offset indent
-SCREEN_WIDTH equ 160 ; In pixels
+SCREEN_WIDTH equ 160 ;\ In pixels
SCREEN_HEIGHT equ 144
.Ed
.Pp
-Note that a colon
+Note that colons
.Ql \&:
-following the name is not allowed.
-They don't change their value during the link process.
-.It Sy SET
-.Pp
-SETs are similar to EQUates, and can be imported and exported as well.
-They are also constant symbols in the sense that their values are defined during the assembly process.
-These symbols are typically used in macros.
-.Pp
+following the name are not allowed.
+.It Ic SET
+.Ic SET ,
+or its synonym
+.Ic = ,
+defines constant symbols like
+.Ic EQU ,
+but those constants can be re-defined.
+This is useful for variables in macros, for counters, etc.
.Bd -literal -offset indent
ARRAY_SIZE EQU 4
COUNT SET 2
COUNT SET ARRAY_SIZE+COUNT
+;\ COUNT now has the value 6
+COUNT = COUNT + 1
.Ed
.Pp
-Note that a colon
+Note that colons
.Ql \&:
-following the name is not allowed.
-Alternatively you can use
-.Ql =
-as a synonym for SET.
-.Pp
-.Bd -literal -offset indent
-COUNT = 2
-.Ed
-.Pp
-.It Sy RSSET , RSRESET , RB , RW
-.Pp
+following the name are not allowed.
+.It Ic RSSET , RSRESET , RB , RW
The RS group of commands is a handy way of defining structures:
-.Pp
.Bd -literal -offset indent
RSRESET
str_pStuff RW 1
@@ -469,42 +780,35 @@
str_SIZEOF RB 0
.Ed
.Pp
-The example defines four equated symbols:
-.Pp
+The example defines four constants as if by:
.Bd -literal -offset indent
-str_pStuff = 0
-str_tData = 2
-str_bCount = 258
-str_SIZEOF = 259
+str_pStuff EQU 0
+str_tData EQU 2
+str_bCount EQU 258
+str_SIZEOF EQU 259
.Ed
.Pp
-There are four commands in the RS group of commands:
+There are five commands in the RS group of commands:
.Pp
.Bl -column "RSSET constexpr"
.It Sy Command Ta Sy Meaning
-.It Ic RSRESET Ta Resets the Ic _RS No counter to zero.
+.It Ic RSRESET Ta Equivalent to Ql RSSET 0 .
.It Ic RSSET Ar constexpr Ta Sets the Ic _RS No counter to Ar constexpr .
.It Ic RB Ar constexpr Ta Sets the preceding symbol to Ic _RS No and adds Ar constexpr No to Ic _RS .
-.It Ic RW Ar constexpr Ta Sets the preceding symbol to Ic _RS No and adds Ar constexpr No * 2 to Ic _RS.
-.It Ic RL Ar constexpr Ta Sets the preceding symbol to Ic _RS No and adds Ar constexpr No * 4 to Ic _RS.
+.It Ic RW Ar constexpr Ta Sets the preceding symbol to Ic _RS No and adds Ar constexpr No * 2 to Ic _RS .
+.It Ic RL Ar constexpr Ta Sets the preceding symbol to Ic _RS No and adds Ar constexpr No * 4 to Ic _RS .
(In practice, this one cannot be used due to a bug).
.El
.Pp
-Note that a colon
+Note that colons
.Ql \&:
-following the name is not allowed.
-.Sy RS
-symbols can be exported and imported.
-They don't change their value during the link process.
-.Pp
+following the name are not allowed.
.It Ic EQUS
-.Pp
.Ic 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 similar to
.Fd #define .
-.Pp
.Bd -literal -offset indent
COUNTREG EQUS "[hl+]"
ld a,COUNTREG
@@ -514,7 +818,6 @@
.Ed
.Pp
This will be interpreted as:
-.Pp
.Bd -literal -offset indent
ld a,[hl+]
db "John"
@@ -521,14 +824,13 @@
.Ed
.Pp
String symbols can also be used to define small one-line macros:
-.Pp
.Bd -literal -offset indent
-PUSHA EQUS "push af\[rs]npush bc\[rs]npush de\[rs]npush hl\[rs]n"
+pusha EQUS "push af\[rs]npush bc\[rs]npush de\[rs]npush hl\[rs]n"
.Ed
.Pp
-Note that a colon
+Note that colons
.Ql \&:
-following the name is not allowed.
+following the name are not allowed.
String equates can't be exported or imported.
.Pp
.Sy Important note :
@@ -545,17 +847,14 @@
.Fl r
command-line option in
.Xr rgbasm 1 .
-Also, a macro can have inside an
+Also, a macro can contain an
.Ic EQUS
-which references the same macro, which has the same problem.
-.Pp
+which calls the same macro, which causes the same problem.
.It Ic MACRO
-.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
+Macros can be called with arguments, and can react depending on input using
.Ic IF
constructs.
-.Pp
.Bd -literal -offset indent
MyMacro: MACRO
ld a,80
@@ -563,173 +862,40 @@
ENDM
.Ed
.Pp
-Note that a colon
+Note that a single colon
.Ql \&:
following the macro's 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).
-.Pp
-The above example is a very simple macro.
-You execute the macro by typing its name.
-.Pp
-.Bd -literal -offset indent
- add a,b
- ld sp,hl
- MyMacro ;This will be expanded
- sub a,87
-.Ed
-.Pp
-When the assembler meets MyMacro it will insert the macro definition (the code enclosed in
-.Ic MACRO
-/
-.Ic ENDM ) .
-.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:
-.Pp
-.Bd -literal -offset indent
-PrintMacro : MACRO
- PRINTT \[rs]1
-ENDM
-
- PrintMacro STRCAT("Hello"\[rs], \[rs]- " world\[rs]\[rs]n")
-.Ed
-.Pp
-Suppose your macro contains a loop.
-.Pp
-.Bd -literal -offset indent
-LoopyMacro: MACRO
- xor a,a
-\&.loop ld [hl+],a
- dec c
- jr nz,.loop
-ENDM
-.Ed
-.Pp
-This is fine, but only if you use the macro no more than once per scope.
-To get around this problem there is a special string equate called
-.Ic \[rs]@
-that you will then expand to a unique string.
-.Pp
-.Ic \[rs]@
-also works in REPT-blocks should you have any loops there.
-.Bd -literal -offset indent
-LoopyMacro: MACRO
- xor a,a
-\&.loop\[rs]@ ld [hl+],a
- dec c
- jr nz,.loop\[rs]@
-ENDM
-.Ed
-.Pp
-.Sy Important note :
-Since a macro can call itself (or a different macro that calls the first one), there can be circular dependency problems.
-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
-.Sy EQUS
-which references the same macro, which has the same problem.
-.Pp
-.Sy Macro Arguments
-.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 then it loads the registers itself.
-.Pp
-And I can do that.
-In macros you can get the arguments by using the special macro string equates
-.Ic \[rs]1
-through
-.Ic \[rs]9 , \[rs]1
-being the first argument specified on the calling of the macro.
-.Pp
-.Bd -literal -offset indent
-LoopyMacro: MACRO
- ld hl,\[rs]1
- ld c,\[rs]2
- xor a,a
-\&.loop\[rs]@ ld [hl+],a
- dec c
- jr nz,.loop\[rs]@
- ENDM
-.Ed
-.Pp
-Now I can call the macro specifying two arguments, the first being the address and the second being a byte count.
-The macro will then reset all bytes in this range.
-.Pp
-.Bd -literal -offset indent
-LoopyMacro MyVars,54
-.Ed
-.Pp
-Arguments are passed as string equates, although there's no need to enclose them in quotes.
-Thus, an expression will not be evaluated first but passed directly.
-This means that it's probably a very good idea to use brackets around
-.Ic \[rs]1
-to
-.Ic \[rs]9
-if you perform further calculations on them.
-For instance, consider the following:
-.Pp
-.Bd -literal -offset indent
-print_double: MACRO
- PRINTV \1 * 2
-ENDM
- print_double 1 + 2
-.Ed
-.Pp
-The
-.Ic PRINTV
-statement will expand to
-.Ql PRINTV 1 + 2 * 2 ,
-which will print 5 and not 6 as you might have expected.
-.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
-.Ic SHIFT .
-.Pp
-.Ic SHIFT
-is a special command only available in macros.
-Very useful in REPT-blocks.
-It will shift the arguments by one to the left.
-.Ic \[rs]1
-will get the value of
-.Ic \[rs]2 , \[rs]2
-will get the value in
-.Ic \[rs]3
-and so forth.
-.Pp
-This is the only way of accessing the value of arguments from 10 to 256.
-.Pp
.El
.Ss Exporting and importing symbols
+.Pp
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.
.Pp
-Exporting of symbols has to be done manually, importing is done automatically if the assembler doesn't know where a symbol is defined.
-.Bd -literal -offset indent
-.Ic EXPORT Ar symbol1 Bq , Ar symbol2 , No ...
-.Ed
+Exporting of symbols has to be done manually, importing is done automatically if
+.Nm
+finds a symbol it does not know about.
.Pp
-The assembler will make
+The following will cause
.Ar symbol1 , symbol2
-and so on accessible to other files during the link process.
-.Bd -literal -offset indent
-.Ic GLOBAL Ar symbol1 Bq , ...
-.Ed
+and so on to be accessible to other files during the link process:
+.Dl Ic EXPORT Ar symbol1 Bq , Ar symbol2 , No ...
.Pp
-If
-.Ar symbol
-is already defined, it will be exported, otherwise it will be imported.
-Note that, since importing is done automatically, this keyword has the same effect as
-.Ic EXPORT .
+.Ic GLOBAL
+is a deprecated synonym for
+.Ic EXPORT ,
+do not use it.
+.Pp
Note also that only exported symbols will appear in symbol and map files produced by
.Xr rgblink 1 .
.Ss Purging symbols
+.Pp
.Ic PURGE
allows you to completely remove a symbol from the symbol table as if it had never existed.
.Em USE WITH EXTREME CAUTION!!!
-I can't stress this enough, you seriously need to know what you are doing.
+I can't stress this enough,
+.Sy you seriously need to know what you are doing .
DON'T purge a 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.
-.Pp
+When not sure, it's probably not safe to purge anything other than string symbols, macros, and constants.
.Bd -literal -offset indent
Kamikaze EQUS "I don't want to live anymore"
AOLer EQUS "Me too"
@@ -736,39 +902,39 @@
PURGE Kamikaze, AOLer
.Ed
.Pp
-Note that string symbols that are part of a
+Note that, as an exception, string symbols in the argument list of a
.Ic PURGE
command
-.Em will not be expanded
-as the ONLY exception to the rule.
+.Em will not be expanded .
.Ss Predeclared Symbols
+.Pp
The following symbols are defined by the assembler:
.Pp
.Bl -column -offset indent "EQUS" "__ISO_8601_LOCAL__"
.It Sy Type Ta Sy Name Ta Sy Contents
-.It Ic EQU Ta Ic @ Ta PC value
-.It Ic EQU Ta Ic _PI Ta Fixed point \[*p]
-.It Ic SET Ta Ic _RS Ta _RS Counter
-.It Ic EQU Ta Ic _NARG Ta Number of arguments passed to macro
-.It Ic EQU Ta Ic __LINE__ Ta The current line number
-.It Ic EQUS Ta Ic __FILE__ Ta The current filename
-.It Ic EQUS Ta Ic __DATE__ Ta Today's date
-.It Ic EQUS Ta Ic __TIME__ Ta The current time
-.It Ic EQUS Ta Ic __ISO_8601_LOCAL__ Ta ISO 8601 timestamp (local)
-.It Ic EQUS Ta Ic __ISO_8601_UTC__ Ta ISO 8601 timestamp (UTC)
-.It Ic EQU Ta Ic __UTC_YEAR__ Ta Today's year
-.It Ic EQU Ta Ic __UTC_MONTH__ Ta Today's month number, 1-12
-.It Ic EQU Ta Ic __UTC_DAY__ Ta Today's day of the month, 1-31
-.It Ic EQU Ta Ic __UTC_HOUR__ Ta Current hour, 0-23
-.It Ic EQU Ta Ic __UTC_MINUTE__ Ta Current minute, 0-59
-.It Ic EQU Ta Ic __UTC_SECOND__ Ta Current second, 0-59
-.It Ic EQU Ta Ic __RGBDS_MAJOR__ Ta Major version number of RGBDS.
-.It Ic EQU Ta Ic __RGBDS_MINOR__ Ta Minor version number of RGBDS.
-.It Ic EQU Ta Ic __RGBDS_PATCH__ Ta Patch version number of RGBDS.
+.It Ic EQU Ta Dv @ Ta PC value
+.It Ic EQU Ta Dv _PI Ta Fixed point \[*p]
+.It Ic SET Ta Dv _RS Ta _RS Counter
+.It Ic EQU Ta Dv _NARG Ta Number of arguments passed to macro
+.It Ic EQU Ta Dv __LINE__ Ta The current line number
+.It Ic EQUS Ta Dv __FILE__ Ta The current filename
+.It Ic EQUS Ta Dv __DATE__ Ta Today's date
+.It Ic EQUS Ta Dv __TIME__ Ta The current time
+.It Ic EQUS Ta Dv __ISO_8601_LOCAL__ Ta ISO 8601 timestamp (local)
+.It Ic EQUS Ta Dv __ISO_8601_UTC__ Ta ISO 8601 timestamp (UTC)
+.It Ic EQU Ta Dv __UTC_YEAR__ Ta Today's year
+.It Ic EQU Ta Dv __UTC_MONTH__ Ta Today's month number, 1\[en]12
+.It Ic EQU Ta Dv __UTC_DAY__ Ta Today's day of the month, 1\[en]31
+.It Ic EQU Ta Dv __UTC_HOUR__ Ta Current hour, 0\[en]23
+.It Ic EQU Ta Dv __UTC_MINUTE__ Ta Current minute, 0\[en]59
+.It Ic EQU Ta Dv __UTC_SECOND__ Ta Current second, 0\[en]59
+.It Ic EQU Ta Dv __RGBDS_MAJOR__ Ta Major version number of RGBDS
+.It Ic EQU Ta Dv __RGBDS_MINOR__ Ta Minor version number of RGBDS
+.It Ic EQU Ta Dv __RGBDS_PATCH__ Ta Patch version number of RGBDS
.El
-.Pp
.Sh DEFINING DATA
.Ss Declaring variables in a RAM section
+.Pp
.Ic DS
allocates a number of empty bytes.
This is the preferred method of allocating space in a RAM section.
@@ -779,9 +945,8 @@
without any arguments instead (see
.Sx Defining constant data
below).
-.Pp
.Bd -literal -offset indent
-DS 42 ; Allocates 42 bytes
+DS 42 ;\ Allocates 42 bytes
.Ed
.Pp
Empty space in RAM sections will not be initialized.
@@ -790,11 +955,11 @@
command-line option, except when using overlays with
.Fl O .
.Ss Defining constant data
+.Pp
.Ic DB
defines a list of bytes that will be stored in the final image.
Ideal for tables and text.
Note that strings are not zero-terminated!
-.Pp
.Bd -literal -offset indent
DB 1,2,3,4,"This is a string"
.Ed
@@ -802,7 +967,6 @@
.Ic DS
can also be used to fill a region of memory with some value.
The following produces 42 times the byte $FF:
-.Pp
.Bd -literal -offset indent
DS 42, $FF
.Ed
@@ -823,34 +987,36 @@
.Ic DL
without arguments, or leaving empty elements at any point in the list.
This works exactly like
-.Sy DS 1 ,
-.Sy DS 2
+.Ic DS 1 , DS 2
and
-.Sy DS 4
+.Ic DS 4
respectively.
-Consequently,
-.Ic DB ,
-.Ic DW
+Consequently, no-argument
+.Ic DB , DW
and
.Ic DL
can be used in a
-.Cm WRAM0
+.Ic WRAM0
/
-.Cm WRAMX
+.Ic WRAMX
/
-.Cm HRAM
+.Ic HRAM
/
-.Cm VRAM
+.Ic VRAM
/
-.Cm SRAM
+.Ic SRAM
section.
.Ss Including binary files
+.Pp
You probably have some graphics, level data, etc. you'd like to include.
Use
.Ic INCBIN
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.
-.Pp
+If the file isn't found in the current directory, the include-path list passed to
+.Xr rgbasm 1
+(see the
+.Fl i
+option) on the command line will be searched.
.Bd -literal -offset indent
INCBIN "titlepic.bin"
INCBIN "sprites/hero.bin"
@@ -858,53 +1024,215 @@
.Pp
You can also include only part of a file with
.Ic INCBIN .
-The example below includes 256 bytes from data.bin starting from byte 78.
-.Pp
+The example below includes 256 bytes from data.bin, starting from byte 78.
.Bd -literal -offset indent
INCBIN "data.bin",78,256
.Ed
.Ss Unions
-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.
.Pp
-You create unions using the
-.Ic UNION , NEXTU
-and
+Unions allow multiple memory allocations to overlap, like unions in C.
+This does not increase the amount of memory available, but allows re-using the same memory region for different purposes.
+.Pp
+A union starts with a
+.Ic UNION
+keyword, and ends at the corresponding
.Ic ENDU
-keywords.
+keyword.
.Ic NEXTU
-lets you create a new block of allocations, and you may use it as many times within a union as necessary.
-.Pp
+separates each block of allocations, and you may use it as many times within a union as necessary.
.Bd -literal -offset indent
- UNION
+ ; Let's say PC = $C0DE here
+ UNION
+ ; Here, PC = $C0DE
Name: ds 8
+ ; PC = $C0E6
Nickname: ds 8
- NEXTU
+ ; PC = $C0EE
+ NEXTU
+ ; PC is back to $C0DE
Health: dw
-Something: ds 3
+ ; PC = $C0E0
+Something: ds 6
+ ; And so on
Lives: db
- NEXTU
-Temporary: ds 19
- ENDU
+ NEXTU
+VideoBuffer: ds 19
+ ENDU
.Ed
.Pp
-This union will use up 19 bytes, as this is the size of the largest block
-.Pq the last one, containing Sq Temporary .
-Of course, as
-.Sq Name ,
-.Sq Health ,
+In the example above,
+.Sq Name , Health , VideoBuffer
+all have the same value, as do
+.Sq Nickname
and
-.Sq Temporary
-all point to the same memory
-locations, writes to any one of these will affect values read from the others.
+.Sq Lives .
+Thus, keep in mind that
+.Ic ld [Health], a
+is identical to
+.Ic ld [Name], a .
.Pp
-Unions may be used in any section, but code and data may not be included.
+The size of this union is 19 bytes, as this is the size of the largest block (the last one, containing
+.Sq VideoBuffer ) .
+Nesting unions is possible, with each inner union's size being considered as described above.
+.Pp
+Unions may be used in any section, but inside them may only be
+.Ic DS -
+like commands (see
+.Sx Declaring variables in a RAM section ) .
.Sh THE MACRO LANGUAGE
+.Ss Invoking macros
.Pp
+You execute the macro by inserting its name.
+.Bd -literal -offset indent
+ add a,b
+ ld sp,hl
+ MyMacro ;\ This will be expanded
+ sub a,87
+.Ed
+.Pp
+It's valid to call a macro from a macro (yes, even the same one).
+.Pp
+When
+.Nm
+sees
+.Ic MyMacro
+it will insert the macro definition (the code enclosed in
+.Ic MACRO
+/
+.Ic ENDM ) .
+.Pp
+Suppose your macro contains a loop.
+.Bd -literal -offset indent
+LoopyMacro: MACRO
+ xor a,a
+\&.loop ld [hl+],a
+ dec c
+ jr nz,.loop
+ENDM
+.Ed
+.Pp
+This is fine, but only if you use the macro no more than once per scope.
+To get around this problem, there is the escape sequence
+.Ic \[rs]@
+that expands to a unique string.
+.Pp
+.Ic \[rs]@
+also works in
+.Ic REPT
+blocks.
+.Bd -literal -offset indent
+LoopyMacro: MACRO
+ xor a,a
+\&.loop\[rs]@ ld [hl+],a
+ dec c
+ jr nz,.loop\[rs]@
+ENDM
+.Ed
+.Pp
+.Sy Important note :
+Since a macro can call itself (or a different macro that calls the first one), there can be circular dependency problems.
+If this creates an infinite loop,
+.Nm
+will error out once a certain depth is
+reached.
+See the
+.Fl r
+command-line option in
+.Xr rgbasm 1 .
+Also, a macro can have inside an
+.Sy EQUS
+which references the same macro, which has the same problem.
+.Pp
+.Pp
+It's possible to pass arguments to macros as well!
+You retrieve the arguments by using the escape sequences
+.Ic \[rs]1
+through
+.Ic \[rs]9 , \[rs]1
+being the first argument specified on the macro invocation.
+.Bd -literal -offset indent
+LoopyMacro: MACRO
+ ld hl,\[rs]1
+ ld c,\[rs]2
+ xor a,a
+\&.loop\[rs]@ ld [hl+],a
+ dec c
+ jr nz,.loop\[rs]@
+ ENDM
+.Ed
+.Pp
+Now I can call the macro specifying two arguments, the first being the address and the second being a byte count.
+The generated code will then reset all bytes in this range.
+.Bd -literal -offset indent
+LoopyMacro MyVars,54
+.Ed
+.Pp
+Arguments are passed as string equates, although there's no need to enclose them in quotes.
+Thus, an expression will not be evaluated first but kind of copy-pasted.
+This means that it's probably a very good idea to use brackets around
+.Ic \[rs]1
+to
+.Ic \[rs]9
+if you perform further calculations on them.
+For instance, consider the following:
+.Bd -literal -offset indent
+print_double: MACRO
+ PRINTV \[rs]1 * 2
+ENDM
+ print_double 1 + 2
+.Ed
+.Pp
+The
+.Ic PRINTV
+statement will expand to
+.Ql PRINTV 1 + 2 * 2 ,
+which will print 5 and not 6 as you might have expected.
+.Pp
+Line continuations work as usual inside macros or lists of macro arguments.
+However, some characters need to be escaped, as in the following example:
+.Bd -literal -offset indent
+PrintMacro: MACRO
+ PRINTT \[rs]1
+ENDM
+
+ PrintMacro STRCAT("Hello "\[rs], \[rs]+ "world\[rs]\[rs]n")
+.Ed
+.Pp
+The comma needs to be escaped to avoid it being treated as separating the macro's arguments.
+The backslash
+.Sq \[rs]
+.Pq from Sq \[rs]n
+also needs to be escaped because of the way
+.Nm
+processes macro arguments.
+.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
+.Ic SHIFT
+command.
+.Pp
+.Ic SHIFT
+is a special command only available in macros.
+Very useful in
+.Ic REPT
+blocks.
+It will shift the arguments by one to the left.
+.Ic \[rs]1
+will get the value of
+.Ic \[rs]2 , \[rs]2
+will get the value of
+.Ic \[rs]3 ,
+and so forth.
+.Pp
+This is the only way of accessing the value of arguments from 10 to 256.
+.Pp
+.Ic SHIFT
+can optionally be given an integer parameter, and will apply the above shifting that number of times.
.Ss Printing things during assembly
-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.
.Pp
+The next four commands print text and values to the standard output.
+Useful for debugging macros, or wherever you may feel the need to tell yourself some important information.
.Bd -literal -offset indent
PRINTT "I'm the greatest programmer in the whole wide world\[rs]n"
PRINTI (2 + 3) / 5
@@ -926,22 +1254,25 @@
.It Ic PRINTF
prints out a fixed point value.
.El
+.Pp
+Be careful that none of those automatically print a line feed; if you need one, use
+.Ic PRINTT "\[rs]n" .
.Ss Automatically repeating blocks of code
+.Pp
Suppose you want to unroll a time consuming loop without copy-pasting it.
.Ic REPT
is here for that purpose.
Everything between
.Ic REPT
-and
+and the matching
.Ic ENDR
will be repeated a number of times just as if you had done a copy/paste operation yourself.
The following example will assemble
.Ql add a,c
four times:
-.Pp
.Bd -literal -offset indent
REPT 4
-add a,c
+ add a,c
ENDR
.Ed
.Pp
@@ -948,11 +1279,10 @@
You can also use
.Ic REPT
to generate tables on the fly:
-.Pp
.Bd -literal -offset indent
-; --
-; -- Generate a 256 byte sine table with values between 0 and 128
-; --
+;\ --
+;\ -- Generate a 256 byte sine table with values between 0 and 128
+;\ --
ANGLE = 0.0
REPT 256
db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
@@ -960,12 +1290,12 @@
ENDR
.Ed
.Pp
-.Ic REPT
-is also very useful in recursive macros and, as in macros, you can also use the special string symbol
+As in macros, you can also use the escape sequence
.Ic \[rs]@ .
.Ic REPT
blocks can be nested.
.Ss Aborting the assembly process
+.Pp
.Ic FAIL
and
.Ic WARN
@@ -1028,7 +1358,7 @@
If the assertion fails,
.Ic WARN
will cause a simple warning (controlled by
-.Xr rgbasm 1 DIAGNOSTICS
+.Xr rgbasm 1
flag
.Fl Wassert )
to be emitted;
@@ -1037,25 +1367,31 @@
.Ic FATAL
immediately aborts.
.Ss Including other source files
+.Pp
Use
.Ic INCLUDE
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.
+If the file isn't found in the current directory the include path list (see the
+.Fl i
+option in
+.Xr rgbasm 1 )
+will be searched.
You may nest
.Ic INCLUDE
calls infinitely (or until you run out of memory, whichever comes first).
-.Pp
.Bd -literal -offset indent
INCLUDE "irq.inc"
.Ed
.Ss Conditional assembling
+.Pp
The four commands
.Ic IF , ELIF , ELSE ,
and
.Ic ENDC
-are used to conditionally assemble parts of your file.
+let you have
+.Nm
+skip over parts of your code depending on a condition.
This is a powerful feature commonly used in macros.
-.Pp
.Bd -literal -offset indent
IF NUM < 0
PRINTT "NUM < 0\[rs]n"
@@ -1068,7 +1404,7 @@
.Pp
The
.Ic ELIF
-and
+(standing for "else if") and
.Ic ELSE
blocks are optional.
.Ic IF
@@ -1095,240 +1431,14 @@
Also, if there is more than one
.Ic ELSE
block, all of them but the first one are ignored.
-.Ss Integer and boolean expressions
-An expression can be composed of many things.
-Expressions are always evaluated using signed 32-bit math.
-.Pp
-The most basic expression is just a single number.
-.Pp
-.Sy Numeric Formats
-.Pp
-There are a number of numeric formats.
-.Pp
-.Bl -column -offset indent "Fixed point (16.16)" "Prefix"
-.It Sy Format type Ta Sy Prefix Ta Sy Accepted characters
-.It Hexadecimal Ta $ Ta 0123456789ABCDEF
-.It Decimal Ta none Ta 0123456789
-.It Octal Ta & Ta 01234567
-.It Binary Ta % Ta 01
-.It Fixed point (16.16) Ta none Ta 01234.56789
-.It Character constant Ta none Ta Qq ABYZ
-.It Gameboy graphics Ta \` Ta 0123
-.El
-.Pp
-The last one, Gameboy graphics, is quite interesting and useful.
-The values are actually pixel values and it converts the
-.Do chunky Dc data to Do planar Dc data as used in the Game Boy.
-.Pp
-.Bd -literal -offset indent
- DW \`01012323
-.Ed
-.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.
-.Pp
-.Sy Operators
-.Pp
-A great number of operators you can use in expressions are available (listed from highest to lowest precedence):
-.Pp
-.Bl -column -offset indent "Operator"
-.It Sy Operator Ta Sy Meaning
-.It Li \&( \&) Ta Precedence override
-.It Li FUNC() Ta Function call
-.It Li ~ + - Ta Unary not/plus/minus
-.It Li * / % Ta Multiply/divide/modulo
-.It Li << >> Ta Shift left/right
-.It Li & \&| ^ Ta Binary and/or/xor
-.It Li + - Ta Add/subtract
-.It Li != == <= Ta Boolean comparison
-.It Li >= < > Ta Boolean comparison (Same precedence as the others)
-.It Li && || Ta Boolean and/or
-.It Li \&! Ta Unary Boolean not
-.El
-.Pp
-The result of the boolean operators is zero when FALSE and non-zero when TRUE.
-It is legal to use an integer as the condition for
-.Sy IF
-blocks.
-You can use symbols instead of numbers in your expression if you wish.
-.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 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 deferred to the linker).
-In this case, the result is a constant that can be calculated at assembly time.
-The instructions in the macro-language all require expressions that are constant.
-.Pp
-.Ss Fixed‐point Expressions
-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 expressions, 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 by 16 bits.
-It follows that you can convert an integer to a fixed-point number by shifting it left.
-.Pp
-Some things are different for fixed-point math, though, which is why you have the following functions to use:
-.EQ
-delim $$
-.EN
-.Pp
-.Bl -column -offset indent "ATAN2(x, y)"
-.It Sy Name Ta Sy Operation
-.It Fn DIV x y Ta $x \[di] y$
-.It Fn MUL x y Ta $x \[mu] y$
-.It Fn SIN x Ta $sin ( x )$
-.It Fn COS x Ta $cos ( x )$
-.It Fn TAN x Ta $tan ( x )$
-.It Fn ASIN x Ta $asin ( x )$
-.It Fn ACOS x Ta $acos ( x )$
-.It Fn ATAN x Ta $atan ( x )$
-.It Fn ATAN2 x y Ta Angle between $( x , y )$ and $( 1 , 0 )$
-.El
-.EQ
-delim off
-.EN
-.Pp
-These functions are useful for automatic generation of various tables.
-Example: assuming a circle has 65536.0 degrees, and sine values are between
-.Bq -1.0 ; 1.0 :
-.Pp
-.Bd -literal -offset indent
-; --
-; -- 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
-.Ed
-.Pp
-.Ss String Expressions
-The most basic string expression is any number of characters contained in double quotes
-.Pq Ql \&"for instance" .
-Like in C, the escape character is \[rs], and there are a number of commands you can use within a string:
-.Pp
-.Bl -column -offset indent "String"
-.It Sy String Ta Sy Meaning
-.It Li \[rs]\[rs] Ta Backslash
-.It Li \[rs]" Ta Double quote
-.It Li \[rs], Ta Comma
-.It Li \[rs]{ Ta Curly bracket left-.It Li \[rs]} Ta Curly bracket right
-.It Li \[rs]n Ta Newline ($0A)
-.It Li \[rs]t Ta Tab ($09)
-.It Li \[rs]1 - \[rs]9 Ta Macro argument (Only the body of a macros)
-.It Li \[rs]@ Ta Label name suffix (Only in the body of macros and REPTs)
-.El
-.Pp
-A funky feature is
-.Ql {symbol}-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 sign
-.Sq $
-prepended.
-.Pp
-It's possible to change the way numeric symbols are converted by specifying a print type like so:
-.Ql {d:symbol} .-Valid print types are:
-.Bl -column -offset indent "Print type" "Lowercase hexadecimal" "Example"
-.It Sy Print type Ta Sy Format Ta Sy Example
-.It Li d Ta Decimal Ta 42
-.It Li x Ta Lowercase hexadecimal Ta 2a
-.It Li X Ta Uppercase hexadecimal Ta 2A
-.It Li b Ta Binary Ta 101010
-.El
-.Pp
-Note that print types should only be used with numeric values, not strings.
-.Pp
-HINT: The
-.Ic {symbol}-construct can also be used outside strings.
-The symbol's value is again inserted directly.
-.Pp
-Whenever the macro-language expects a string you can actually use a string expression.
-This consists of one or more of these functions (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!
-.Pp
-.Bl -column "STRSUB_str,_pos,_len"
-.It Sy Name Ta Sy Operation
-.It Fn STRLEN string Ta Returns the number of characters in Ar string .
-.It Fn STRCAT str1 str2 Ta Appends Ar str2 No to Ar str1 .
-.It Fn STRCMP str1 str2 Ta Returns negative if Ar str1 No is alphabetically lower than Ar str2 No , zero if they match, positive if Ar str1 No is greater than Ar str2 .
-.It Fn STRIN str1 str2 Ta Returns the position of Ar str2 No in Ar str1 No or zero if it's not present Pq first character is position 1 .
-.It Fn STRSUB str pos len Ta Returns a substring from Ar str No starting at Ar pos Po first character is position 1 Pc and with Ar len No characters.
-.It Fn STRUPR str Ta Converts all characters in Ar str No to capitals and returns the new string.
-.It Fn STRLWR str Ta Converts all characters in Ar str No to lower case and returns the new string.
-.El
-.Ss Character maps
-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.
-.Pp
-Character maps allow the code to map strings up to 16 characters long to an abitrary 8-bit value:
-.Pp
-.Bd -literal -offset indent
-CHARMAP "<LF>", 10
-CHARMAP "í", 20
-CHARMAP "A", 128
-.Ed
-.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
-.Sy main
-and it is automatically selected as the current character map from the beginning.
-There is also a character map stack that can be used to save and restore which character map is currently active.
-.Bl -column "NEWCHARMAP name, basename"
-.It Sy Command Ta Sy Meaning
-.It Ic NEWCHARMAP Ar name Ta Creates a new, empty character map called Ar name .
-.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename .
-.It Ic SETCHARMAP Ar name Ta Switch to character map Ar name .
-.It Ic PUSHC Ta Push the current character map onto the stack.
-.It Ic POPC Ta Pop a character map off the stack and switch to it.
-.El
-.Pp
-.Sy Note:
-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.
-.Pp
-.Sy Note:
-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.
-.Pp
-.Ss Other functions
-There are a few other functions that do various useful things:
-.Pp
-.Bl -column "BANK(arg)"
-.It Sy Name Ta Sy Operation
-.It Fn BANK arg Ta Returns a bank number.
-If
-.Ar arg
-is the symbol
-.Ic @ ,
-this function returns the bank of the current section.
-If
-.Ar arg
-is a string, it returns the bank of the section that has that name.
-If
-.Ar arg
-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.
-.It Fn DEF label Ta Returns TRUE if
-.Ar label
-has been defined.
-.It Fn HIGH arg Ta Returns the top 8 bits of the operand if Ar arg No is a label or constant, or the top 8-bit register if it is a 16-bit register.
-.It Fn LOW arg Ta Returns the bottom 8 bits of the operand if Ar arg No is a label or constant, or the bottom 8-bit register if it is a 16-bit register Pq Cm AF No isn't a valid register for this function .
-.It Fn ISCONST arg Ta Returns 1 if Ar arg Ns No 's value is known by RGBASM (e.g. if it can be an argument to
-.Ic IF ) ,
-or 0 if only RGBLINK can compute its value.
-.El
.Sh MISCELLANEOUS
.Ss Changing options while assembling
+.Pp
.Ic OPT
can be used to change some of the options during assembling from within the source, instead of defining them on the command-line.
.Pp
.Ic OPT
takes a comma-separated list of options as its argument:
-.Pp
.Bd -literal -offset indent
PUSHO
OPT g.oOX ;Set the GB graphics constants to use these characters
@@ -1362,6 +1472,7 @@
.Xr rgbds 7 ,
.Xr gbz80 7
.Sh HISTORY
+.Pp
.Nm
was originally written by Carsten S\(/orensen as part of the ASMotor package,
and was later packaged in RGBDS by Justin Lloyd.
--- /dev/null
+++ b/src/doc_postproc.awk
@@ -1,0 +1,85 @@
+#!/usr/bin/awk -f
+
+/^\s+<td><b class="Sy">.+<\/b><\/td>$/ {+ # Assuming that all cells whose contents are bold are heading cells,
+ # use the HTML tag for those
+ sub(/td><b class="Sy"/, "th");
+ sub(/b><\/td/, "th");
+}
+
+BEGIN {+ in_synopsis = 0
+}
+/<table class="Nm">/ {+ in_synopsis = 1
+}
+/<\/table>/ {+ # Resets synopsis state even when already reset, but whatever
+ in_synopsis = 0
+}
+/<code class="Fl">-[a-zA-Z]/ {+ # Add links to arg descr in synopsis section
+ if (in_synopsis) {+ while (match($0, /<code class="Fl">-[a-zA-Z]+/)) {+ # 123456789012345678 -> 18 chars
+ optchars = substr($0, RSTART + 18, RLENGTH - 18)
+ i = length(optchars)
+ while (i) {+ end = RSTART + 18 + i
+ i -= 1
+ len = i ? 1 : 2
+ $0 = sprintf("%s<a href=\"#%s\">%s</a>%s",+ substr($0, 0, end - len - 1),
+ substr($0, end - 1, 1),
+ substr($0, end - len, len),
+ substr($0, end))
+ }
+ }
+ }
+}
+
+/<div class="Nd">/ {+ # Make the description blurb inline, as with terminal output
+ gsub(/div/, "span")
+}
+
+BEGIN {+ pages["gbz80", 7] = 1
+ pages["rgbds", 5] = 1
+ pages["rgbds", 7] = 1
+ pages["rgbasm", 1] = 1
+ pages["rgbasm", 5] = 1
+ pages["rgblink",1] = 1
+ pages["rgblink",5] = 1
+ pages["rgbfix", 1] = 1
+ pages["rgbgfx", 1] = 1
+}
+/<a class="Xr">/ {+ # Link to other pages in the doc
+ for (i in pages) {+ split(i, page, SUBSEP)
+ name = page[1]
+ section = page[2]
+ gsub(sprintf("<a class=\"Xr\">%s\\(%d\\)", name, section),+ sprintf("<a class=\"Xr\" href=\"%s.%d.html\">%s(%d)", name, section, name, section))+ }
+}
+
+{+ # Make long opts (defined using `Fl Fl`) into a single tag
+ gsub(/<code class="Fl">-<\/code><code class="Fl">/, "<code class=\"Fl\">-")
+}
+
+{+}
+
+/<head>/ {+ # Add viewport size <meta> tag for mobile users
+ print " <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
+}
+
+/<link/ {+ # Inject our own style overrides
+ print(" <link rel=\"stylesheet\" href=\"rgbds.css\" type=\"text/css\" media=\"all\"/>")+}
--- a/src/gbz80.7
+++ b/src/gbz80.7
@@ -18,8 +18,9 @@
.Pp
Note: All arithmetic/logic operations that use register
.Sy A
-as destination can omit the destination as it is assumed it's register
-.Sy A .
+as destination can omit the destination as it is assumed to be register
+.Sy A
+by default.
The following two lines have the same effect:
.Pp
.Bd -literal -offset indent
@@ -42,7 +43,7 @@
16-bit integer constant.
.It Ar e8
8-bit offset
-.Po Fl Sy 128
+.Po Sy -128
to
.Sy 127
.Pc .
@@ -55,18 +56,18 @@
.It Ar cc
Condition codes:
.Bl -tag -compact
-.It Sy Z :
+.It Sy Z
Execute if Z is set.
-.It Sy NZ :
+.It Sy NZ
Execute if Z is not set.
-.It Sy C :
+.It Sy C
Execute if C is set.
-.It Sy NC :
+.It Sy NC
Execute if C is not set.
.El
.It Ar vec
One of the
-.Ar RST
+.Sy RST
vectors
.Po Sy 0x00 , 0x08 , 0x10 , 0x18 , 0x20 , 0x28 , 0x30
and
@@ -73,7 +74,6 @@
.Sy 0x38
.Pc .
.El
-.Pp
.Sh INSTRUCTION OVERVIEW
.Ss 8-bit Arithmetic and Logic Instructions
.Bl -inset -compact
@@ -154,16 +154,16 @@
.It Sx LD r8,[HL]
.It Sx LD [r16],A
.It Sx LD [n16],A
-.It Sx LD [$FF00+n8],A
-.It Sx LD [$FF00+C],A
+.It Sx LDH [n16],A
+.It Sx LDH [C],A
.It Sx LD A,[r16]
.It Sx LD A,[n16]
-.It Sx LD A,[$FF00+n8]
-.It Sx LD A,[$FF00+C]
-.It Sx LD [HL+],A
-.It Sx LD [HL-],A
-.It Sx LD A,[HL+]
-.It Sx LD A,[HL-]
+.It Sx LDH A,[n16]
+.It Sx LDH A,[C]
+.It Sx LD [HLI],A
+.It Sx LD [HLD],A
+.It Sx LD A,[HLI]
+.It Sx LD A,[HLD]
.El
.Ss Jumps and Subroutines
.Bl -inset -compact
@@ -218,22 +218,18 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
Set if overflow from bit 3.
-.It
-.Sy C :
+.It Sy C
Set if overflow from bit 7.
.El
.Ss ADC A,[HL]
-Add the value pointed by
+Add the byte pointed to by
.Sy HL
plus the carry flag to
.Sy A .
@@ -267,22 +263,18 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
Set if overflow from bit 3.
-.It
-.Sy C :
+.It Sy C
Set if overflow from bit 7.
.El
.Ss ADD A,[HL]
-Add the value pointed by
+Add the byte pointed to by
.Sy HL
to
.Sy A .
@@ -316,15 +308,12 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy N :
+.Bl -hang -compact
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
Set if overflow from bit 11.
-.It
-.Sy C :
+.It Sy C
Set if overflow from bit 15.
.El
.Ss ADD HL,SP
@@ -350,18 +339,14 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
0
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
Set if overflow from bit 3.
-.It
-.Sy C :
+.It Sy C
Set if overflow from bit 7.
.El
.Ss AND A,r8
@@ -375,22 +360,18 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
1
-.It
-.Sy C :
+.It Sy C
0
.El
.Ss AND A,[HL]
-Bitwise AND between the value pointed by
+Bitwise AND between the byte pointed to by
.Sy HL
and
.Sy A .
@@ -425,15 +406,12 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if the selected bit is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
1
.El
.Ss BIT u3,[HL]
@@ -452,6 +430,12 @@
.Ss CALL n16
Call address
.Ar n16 .
+This pushes the address of the instruction after the
+.Sy CALL
+on the stack, such that
+.Sx RET
+can pop it later; then, it executes an implicit
+.Sx JP n16 .
.Pp
Cycles: 6
.Pp
@@ -465,7 +449,7 @@
.Ar cc
is met.
.Pp
-Cycles: 6/3
+Cycles: 6 taken / 3 untaken
.Pp
Bytes: 3
.Pp
@@ -478,16 +462,13 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy N :
+.Bl -hang -compact
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
-Complemented.
+.It Sy C
+Inverted.
.El
.Ss CP A,r8
Subtract the value in
@@ -495,6 +476,7 @@
from
.Sy A
and set flags accordingly, but don't store the result.
+This is useful for ComParing values.
.Pp
Cycles: 1
.Pp
@@ -501,26 +483,21 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
1
-.It
-.Sy H :
+.It Sy H
Set if borrow from bit 4.
-.It
-.Sy C :
-Set if borrow
-.Po set if Ar r8
+.It Sy C
+Set if borrow (i.e. if
+.Ar r8
>
-.Sy A
-.Pc .
+.Sy A ) .
.El
.Ss CP A,[HL]
-Subtract the value pointed by
+Subtract the byte pointed to by
.Sy HL
from
.Sy A
@@ -546,7 +523,7 @@
Flags: See
.Sx CP A,r8
.Ss CPL
-Complement accumulator
+ComPLement accumulator
.Po Sy A
=
.Sy ~A
@@ -557,17 +534,14 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy N :
+.Bl -hang -compact
+.It Sy N
1
-.It
-.Sy H :
+.It Sy H
1
.El
.Ss DAA
-Decimal adjust register A to get a correct BCD representation after an
-arithmetic instruction.
+Decimal Adjust Accumulator to get a correct BCD representation after an arithmetic instruction.
.Pp
Cycles: 1
.Pp
@@ -574,15 +548,12 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set or reset depending on the operation.
.El
.Ss DEC r8
@@ -595,19 +566,16 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
1
-.It
-.Sy H :
+.It Sy H
Set if borrow from bit 4.
.El
.Ss DEC [HL]
-Decrement the value pointed by
+Decrement the byte pointed to by
.Sy HL
by 1.
.Pp
@@ -638,7 +606,9 @@
.Pp
Flags: None affected.
.Ss DI
-Disable Interrupts.
+Disable Interrupts by clearing the
+.Sy IME
+flag.
.Pp
Cycles: 1
.Pp
@@ -646,7 +616,13 @@
.Pp
Flags: None affected.
.Ss EI
-Enable Interrupts.
+Enable Interrupts by setting the
+.Sy IME
+flag.
+The flag is only set
+.Em after
+the instruction following
+.Sy EI .
.Pp
Cycles: 1
.Pp
@@ -654,7 +630,38 @@
.Pp
Flags: None affected.
.Ss HALT
-Enter CPU low power mode.
+Enter CPU low-power consumption mode until an interrupt occurs.
+The exact behavior of this instruction depends on the state of the
+.Sy IME
+flag.
+.Bl -tag -width indent
+.It Sy IME No set
+The CPU enters low-power mode until
+.Em after
+an interrupt is about to be serviced.
+The handler is executed normally, and the CPU resumes execution after the
+.Ic HALT
+when that returns.
+.It Sy IME No not set
+The behavior depends on whether an interrupt is pending (i.e.\&
+.Ql [IE] & [IF]
+is non-zero).
+.Bl -tag -width indent
+.It None pending
+As soon as an interrupt becomes pending, the CPU resumes execution.
+This is like the above, except that the handler is
+.Em not
+called.
+.It Some pending
+The CPU continues execution after the
+.Ic HALT ,
+but the byte after it is read twice in a row
+.Po
+.Sy PC
+is not incremented, due to a hardware bug
+.Pc .
+.El
+.El
.Pp
Cycles: -
.Pp
@@ -671,19 +678,16 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
Set if overflow from bit 3.
.El
.Ss INC [HL]
-Increment the value pointed by
+Increment the byte pointed to by
.Sy HL
by 1.
.Pp
@@ -714,8 +718,12 @@
.Pp
Flags: None affected.
.Ss JP n16
-Absolute jump to address
-.Ar n16 .
+Jump to address
+.Ar n16 ;
+effectively, store
+.Ar n16
+into
+.Sy PC .
.Pp
Cycles: 4
.Pp
@@ -723,13 +731,13 @@
.Pp
Flags: None affected.
.Ss JP cc,n16
-Absolute jump to address
+Jump to address
.Ar n16
if condition
.Ar cc
is met.
.Pp
-Cycles: 4/3
+Cycles: 4 taken / 3 untaken
.Pp
Bytes: 3
.Pp
@@ -736,8 +744,8 @@
Flags: None affected.
.Ss JP HL
Jump to address in
-.Sy HL ,
-that is, load
+.Sy HL ;
+effectively, load
.Sy PC
with value in register
.Sy HL .
@@ -748,9 +756,11 @@
.Pp
Flags: None affected.
.Ss JR e8
-Relative jump by adding
+Relative Jump by adding
.Ar e8
-to the current address.
+to the address of the instruction following the
+.Sy JR .
+To clarify, an operand of 0 is equivalent to no jumping.
.Pp
Cycles: 3
.Pp
@@ -758,19 +768,19 @@
.Pp
Flags: None affected.
.Ss JR cc,e8
-Relative jump by adding
+Relative Jump by adding
.Ar e8
to the current address if condition
.Ar cc
is met.
.Pp
-Cycles: 3/2
+Cycles: 3 taken / 2 untaken
.Pp
Bytes: 2
.Pp
Flags: None affected.
.Ss LD r8,r8
-Store value in register on the right into register on the left.
+Load (copy) value in register on the right into register on the left.
.Pp
Cycles: 1
.Pp
@@ -802,7 +812,7 @@
.Ss LD [HL],r8
Store value in register
.Ar r8
-into byte pointed by register
+into byte pointed to by register
.Sy HL .
.Pp
Cycles: 2
@@ -813,7 +823,7 @@
.Ss LD [HL],n8
Store value
.Ar n8
-into byte pointed by register
+into byte pointed to by register
.Sy HL .
.Pp
Cycles: 3
@@ -824,7 +834,7 @@
.Ss LD r8,[HL]
Load value into register
.Ar r8
-from byte pointed by register
+from byte pointed to by register
.Sy HL .
.Pp
Cycles: 2
@@ -835,7 +845,7 @@
.Ss LD [r16],A
Store value in register
.Sy A
-into address pointed by register
+into byte pointed to by register
.Ar r16 .
.Pp
Cycles: 2
@@ -846,7 +856,7 @@
.Ss LD [n16],A
Store value in register
.Sy A
-into address
+into byte at address
.Ar n16 .
.Pp
Cycles: 4
@@ -854,23 +864,31 @@
Bytes: 3
.Pp
Flags: None affected.
-.Ss LD [$FF00+n8],A
+.Ss LDH [n16],A
Store value in register
.Sy A
-into high RAM or I/O registers.
+into byte at address
+.Ar n16 ,
+provided it is between
+.Ad $FF00
+and
+.Ad $FFFF .
.Pp
-The following synonym forces this encoding:
-.Sy LDH [$FF00+n8],A
-.Pp
Cycles: 3
.Pp
Bytes: 2
.Pp
Flags: None affected.
-.Ss LD [$FF00+C],A
+.Pp
+This is sometimes written as
+.Ql ldio [n16], a ,
+or
+.Ql ld [$ff00+n8], a .
+.Ss LDH [C],A
Store value in register
.Sy A
-into high RAM or I/O registers.
+into byte at address
+.Ad $FF00+C .
.Pp
Cycles: 2
.Pp
@@ -877,10 +895,15 @@
Bytes: 1
.Pp
Flags: None affected.
+.Pp
+This is sometimes written as
+.Ql ldio [c], a ,
+or
+.Ql ld [$ff00+c], a .
.Ss LD A,[r16]
Load value in register
.Sy A
-from address pointed by register
+from byte pointed to by register
.Ar r16 .
.Pp
Cycles: 2
@@ -891,7 +914,7 @@
.Ss LD A,[n16]
Load value in register
.Sy A
-from address
+from byte at address
.Ar n16 .
.Pp
Cycles: 4
@@ -899,23 +922,31 @@
Bytes: 3
.Pp
Flags: None affected.
-.Ss LD A,[$FF00+n8]
+.Ss LDH A,[n16]
Load value in register
.Sy A
-from high RAM or I/O registers.
+from byte at address
+.Ar n16 ,
+provided it is between
+.Ad $FF00
+and
+.Ad $FFFF .
.Pp
-The following synonym forces this encoding:
-.Sy LDH A,[$FF00+n8]
-.Pp
Cycles: 3
.Pp
Bytes: 2
.Pp
Flags: None affected.
-.Ss LD A,[$FF00+C]
+.Pp
+This is sometimes written as
+.Ql ldio a, [n16] ,
+or
+.Ql ld a, [$ff00+n8] .
+.Ss LDH A,[C]
Load value in register
.Sy A
-from high RAM or I/O registers.
+from byte at address
+.Ad $FF00+c .
.Pp
Cycles: 2
.Pp
@@ -922,13 +953,19 @@
Bytes: 1
.Pp
Flags: None affected.
-.Ss LD [HL+],A
+.Pp
+This is sometimes written as
+.Ql ldio a, [c] ,
+or
+.Ql ld a, [$ff00+c] .
+.Ss LD [HLI],A
Store value in register
.Sy A
into byte pointed by
.Sy HL
-and post-increment
-.Sy HL .
+and increment
+.Sy HL
+afterwards.
.Pp
Cycles: 2
.Pp
@@ -935,13 +972,14 @@
Bytes: 1
.Pp
Flags: None affected.
-.Ss LD [HL-],A
+.Ss LD [HLD],A
Store value in register
.Sy A
into byte pointed by
.Sy HL
-and post-decrement
-.Sy HL .
+and decrement
+.Sy HL
+afterwards.
.Pp
Cycles: 2
.Pp
@@ -948,13 +986,14 @@
Bytes: 1
.Pp
Flags: None affected.
-.Ss LD A,[HL+]
+.Ss LD A,[HLD]
Load value into register
.Sy A
from byte pointed by
.Sy HL
-and post-increment
-.Sy HL .
+and decrement
+.Sy HL
+afterwards.
.Pp
Cycles: 2
.Pp
@@ -961,13 +1000,14 @@
Bytes: 1
.Pp
Flags: None affected.
-.Ss LD A,[HL-]
+.Ss LD A,[HLI]
Load value into register
.Sy A
from byte pointed by
.Sy HL
-and post-decrement
-.Sy HL .
+and increment
+.Sy HL
+afterwards.
.Pp
Cycles: 2
.Pp
@@ -987,12 +1027,14 @@
Flags: None affected.
.Ss LD [n16],SP
Store
-.Sy SP
-into addresses
+.Sy SP & $FF
+at address
.Ar n16
-(LSB) and
+and
+.Sy SP >> 8
+at address
.Ar n16
-+ 1 (MSB).
++ 1.
.Pp
Cycles: 5
.Pp
@@ -1005,7 +1047,7 @@
to
.Sy SP
and store the result in
-.Sy HL.
+.Sy HL .
.Pp
Cycles: 3
.Pp
@@ -1012,18 +1054,14 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
0
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
Set if overflow from bit 3.
-.It
-.Sy C :
+.It Sy C
Set if overflow from bit 7.
.El
.Ss LD SP,HL
@@ -1038,7 +1076,7 @@
.Pp
Flags: None affected.
.Ss NOP
-No operation.
+No OPeration.
.Pp
Cycles: 1
.Pp
@@ -1046,7 +1084,9 @@
.Pp
Flags: None affected.
.Ss OR A,r8
-Bitwise OR between the value in
+Store into
+.Sy A
+the bitwise OR of the value in
.Ar r8
and
.Sy A .
@@ -1056,22 +1096,20 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
0
.El
.Ss OR A,[HL]
-Bitwise OR between the value pointed by
+Store into
+.Sy A
+the bitwise OR of the byte pointed to by
.Sy HL
and
.Sy A .
@@ -1083,7 +1121,9 @@
Flags: See
.Sx OR A,r8
.Ss OR A,n8
-Bitwise OR between the value in
+Store into
+.Sy A
+the bitwise OR of
.Ar n8
and
.Sy A .
@@ -1098,6 +1138,15 @@
Pop register
.Sy AF
from the stack.
+This is roughly equivalent to the following
+.Em imaginary
+instructions:
+.Bd -literal -offset indent
+inc sp
+ld a, [sp]
+inc sp
+ld f, [sp] ; See below for individual flags
+.Ed
.Pp
Cycles: 3
.Pp
@@ -1104,18 +1153,14 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set from bit 7 of the popped low byte.
-.It
-.Sy N :
+.It Sy N
Set from bit 6 of the popped low byte.
-.It
-.Sy H :
+.It Sy H
Set from bit 5 of the popped low byte.
-.It
-.Sy C :
+.It Sy C
Set from bit 4 of the popped low byte.
.El
.Ss POP r16
@@ -1122,6 +1167,15 @@
Pop register
.Ar r16
from the stack.
+This is roughly equivalent to the following
+.Em imaginary
+instructions:
+.Bd -literal -offset indent
+ld LOW(r16), [sp] ; C, E or L
+inc sp
+ld HIGH(r16), [sp] ; B, D or H
+inc sp
+.Ed
.Pp
Cycles: 3
.Pp
@@ -1131,15 +1185,16 @@
.Ss PUSH AF
Push register
.Sy AF
-into the stack. The low byte's bit 7 corresponds to the
-.Sy Z
-flag, its bit 6 to the
-.Sy N
-flag, bit 5 to the
-.Sy H
-flag, and bit 4 to the
-.Sy C
-flag. Bits 3 to 0 are reset.
+into the stack.
+This is roughly equivalent to the following
+.Em imaginary
+instructions:
+.Bd -literal -offset indent
+dec sp
+ld [sp], a
+dec sp
+ld [sp], flag_Z << 7 | flag_N << 6 | flag_H << 5 | flag_C << 4
+.Ed
.Pp
Cycles: 4
.Pp
@@ -1150,6 +1205,15 @@
Push register
.Ar r16
into the stack.
+This is roughly equivalent to the following
+.Em imaginary
+instructions:
+.Bd -literal -offset indent
+dec sp
+ld [sp], HIGH(r16) ; B, D or H
+dec sp
+ld [sp], LOW(r16) ; C, E or L
+.Ed
.Pp
Cycles: 4
.Pp
@@ -1162,6 +1226,7 @@
in register
.Ar r8
to 0.
+Bit 0 is the rightmost one, bit 7 the leftmost one.
.Pp
Cycles: 2
.Pp
@@ -1174,6 +1239,7 @@
in the byte pointed by
.Sy HL
to 0.
+Bit 0 is the rightmost one, bit 7 the leftmost one.
.Pp
Cycles: 4
.Pp
@@ -1182,6 +1248,14 @@
Flags: None affected.
.Ss RET
Return from subroutine.
+This is basically a
+.Sy POP PC
+(if such an instruction existed).
+See
+.Sx POP r16
+for an explanation of how
+.Sy POP
+works.
.Pp
Cycles: 4
.Pp
@@ -1193,7 +1267,7 @@
.Ar cc
is met.
.Pp
-Cycles: 5/2
+Cycles: 5 taken / 2 untaken
.Pp
Bytes: 1
.Pp
@@ -1200,6 +1274,13 @@
Flags: None affected.
.Ss RETI
Return from subroutine and enable interrupts.
+This is basically equivalent to executing
+.Sx EI
+then
+.Sx RET ,
+meaning that
+.Sy IME
+is set right after this instruction.
.Pp
Cycles: 4
.Pp
@@ -1207,7 +1288,7 @@
.Pp
Flags: None affected.
.Ss RL r8
-Rotate register
+Rotate bits in register
.Ar r8
left through carry.
.Pp
@@ -1218,22 +1299,18 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss RL [HL]
-Rotate value pointed by
+Rotate byte pointed to by
.Sy HL
left through carry.
.Pp
@@ -1257,18 +1334,14 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
0
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss RLC r8
@@ -1283,22 +1356,18 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss RLC [HL]
-Rotate value pointed by
+Rotate byte pointed to by
.Sy HL
left.
.Pp
@@ -1322,18 +1391,14 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
0
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss RR r8
@@ -1348,22 +1413,18 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss RR [HL]
-Rotate value pointed by
+Rotate byte pointed to by
.Sy HL
right through carry.
.Pp
@@ -1387,18 +1448,14 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
0
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss RRC r8
@@ -1413,22 +1470,18 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss RRC [HL]
-Rotate value pointed by
+Rotate byte pointed to by
.Sy HL
right.
.Pp
@@ -1452,23 +1505,23 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
0
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss RST vec
-Call restart vector
+Call address
.Ar vec .
+This is a shorter and faster equivalent to
+.Sx CALL
+for suitable values of
+.Ar vec .
.Pp
Cycles: 4
.Pp
@@ -1486,26 +1539,22 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
1
-.It
-.Sy H :
+.It Sy H
Set if borrow from bit 4.
-.It
-.Sy C :
-Set if borrow
-.Po set if Ar r8
->
-.Sy A
-.Pc .
+.It Sy C
+Set if borrow (i.e. if
+.Po Ar r8
++ carry
+.Pc >
+.Sy A ) .
.El
.Ss SBC A,[HL]
-Subtract the value pointed by
+Subtract the byte pointed to by
.Sy HL
and the carry flag from
.Sy A .
@@ -1536,15 +1585,12 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy N :
+.Bl -hang -compact
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
1
.El
.Ss SET u3,r8
@@ -1553,6 +1599,7 @@
in register
.Ar r8
to 1.
+Bit 0 is the rightmost one, bit 7 the leftmost one.
.Pp
Cycles: 2
.Pp
@@ -1565,6 +1612,7 @@
in the byte pointed by
.Sy HL
to 1.
+Bit 0 is the rightmost one, bit 7 the leftmost one.
.Pp
Cycles: 4
.Pp
@@ -1572,7 +1620,7 @@
.Pp
Flags: None affected.
.Ss SLA r8
-Shift left arithmetic register
+Shift Left Arithmetic register
.Ar r8 .
.Pp
.D1 C <- [7 <- 0] <- 0
@@ -1582,22 +1630,18 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss SLA [HL]
-Shift left arithmetic value pointed by
+Shift Left Arithmetic byte pointed to by
.Sy HL .
.Pp
.D1 C <- [7 <- 0] <- 0
@@ -1609,7 +1653,7 @@
Flags: See
.Sx SLA r8
.Ss SRA r8
-Shift right arithmetic register
+Shift Right Arithmetic register
.Ar r8 .
.Pp
.D1 [7] -> [7 -> 0] -> C
@@ -1619,22 +1663,18 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss SRA [HL]
-Shift right arithmetic value pointed by
+Shift Right Arithmetic byte pointed to by
.Sy HL .
.Pp
.D1 [7] -> [7 -> 0] -> C
@@ -1646,7 +1686,7 @@
Flags: See
.Sx SRA r8
.Ss SRL r8
-Shift right logic register
+Shift Right Logic register
.Ar r8 .
.Pp
.D1 0 -> [7 -> 0] -> C
@@ -1656,22 +1696,18 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
Set according to result.
.El
.Ss SRL [HL]
-Shift right logic value pointed by
+Shift Right Logic byte pointed to by
.Sy HL .
.Pp
.D1 0 -> [7 -> 0] -> C
@@ -1702,26 +1738,21 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
1
-.It
-.Sy H :
+.It Sy H
Set if borrow from bit 4.
-.It
-.Sy C :
-Set if borrow
-.Po set if Ar r8
+.It Sy C
+Set if borrow (set if
+.Ar r8
>
-.Sy A
-.Pc .
+.Sy A ) .
.El
.Ss SUB A,[HL]
-Subtract the value pointed by
+Subtract the byte pointed to by
.Sy HL
from
.Sy A .
@@ -1747,7 +1778,7 @@
.Ss SWAP r8
Swap upper 4 bits in register
.Ar r8
-and the lower ones.
+and the lower 4 ones.
.Pp
Cycles: 2
.Pp
@@ -1754,24 +1785,20 @@
Bytes: 2
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
0
.El
.Ss SWAP [HL]
Swap upper 4 bits in the byte pointed by
.Sy HL
-and the lower ones.
+and the lower 4 ones.
.Pp
Cycles: 4
.Pp
@@ -1790,22 +1817,18 @@
Bytes: 1
.Pp
Flags:
-.Bl -bullet -compact
-.It
-.Sy Z :
+.Bl -hang -compact
+.It Sy Z
Set if result is 0.
-.It
-.Sy N :
+.It Sy N
0
-.It
-.Sy H :
+.It Sy H
0
-.It
-.Sy C :
+.It Sy C
0
.El
.Ss XOR A,[HL]
-Bitwise XOR between the value pointed by
+Bitwise XOR between the byte pointed to by
.Sy HL
and
.Sy A .
--- a/src/link/rgblink.1
+++ b/src/link/rgblink.1
@@ -41,7 +41,7 @@
Similarly, WRAM0 sections are placed in the first 4 KiB of WRAM
.Pq Dq bank 0 ,
and WRAMX sections are placed in any bank of the last 4 KiB.
-If your ROM doesn't use banked, WRAM you can use the
+If your ROM doesn't use banked WRAM, you can use the
.Fl w
option to change this.
.Pp
@@ -93,14 +93,14 @@
This option is ignored.
It was supposed to perform smart linking but fell into disrepair, and so has been removed.
It will be reimplemented at some point.
-.It Fl t , Fl tiny
+.It Fl t , Fl Fl tiny
Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to ROM and prohibit the use of ROMX sections.
Useful for ROMs that fit in 32 KiB.
-.It Fl V , Fl version
+.It Fl V , Fl Fl version
Print the version of the program and exit.
-.It Fl v , Fl verbose
+.It Fl v , Fl Fl verbose
Verbose: enable printing more information to standard error.
-.It Fl w , Fl wramx
+.It Fl w , Fl Fl wramx
Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to WRAM and prohibit the use of WRAMX sections.
.El
.Sh EXAMPLES
@@ -115,11 +115,13 @@
.Xr rgbfix 1
to fix these so that the program will actually run in a Game Boy:
.Pp
-.D1 $ rgbfix -v bar.gb
+.Dl $ rgbfix -v bar.gb
+.Ed
.Pp
Here is a more complete example:
.Pp
-.D1 $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o
+.Dl $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o
+.Ed
.Sh BUGS
Please report bugs on
.Lk https://github.com/rednex/rgbds/issues GitHub .