ref: 7e94ecbfe6aaede61b2c5aff4e5a636fc2b16e26
parent: 0195196425367a446144041dfd3d0f769eb9e375
author: ISSOtm <eldredhabert0@gmail.com>
date: Sun May 15 09:11:20 EDT 2022
Move all man pages to a separate directory Simplifies processing all around, and makes more sense
--- a/.github/actions/get-pages.sh
+++ b/.github/actions/get-pages.sh
@@ -4,7 +4,7 @@
cat <<EOF
Usage: $0 [-h] [-r] <rgbds-www> <version>
Copy renders from RGBDS repository to rgbds-www documentation
-Execute from the root folder of the RGBDS repo, checked out at the desired tag
+Execute from the \`man/\` folder in the RGBDS repo, checked out at the desired tag
<rgbds-www> : Path to the rgbds-www repository
<version> : Version to be copied, such as 'v0.4.1' or 'master'
@@ -35,37 +35,34 @@
usage
exit 1
fi
-shift $(($OPTIND - 1))
+shift $((OPTIND - 1))
-declare -A PAGES
+declare -a PAGES
PAGES=(
- [rgbasm.1.html]=src/asm/rgbasm.1
- [rgbasm.5.html]=src/asm/rgbasm.5
- [rgblink.1.html]=src/link/rgblink.1
- [rgblink.5.html]=src/link/rgblink.5
- [rgbfix.1.html]=src/fix/rgbfix.1
- [rgbgfx.1.html]=src/gfx/rgbgfx.1
- [rgbds.5.html]=src/rgbds.5
- [rgbds.7.html]=src/rgbds.7
- [gbz80.7.html]=src/gbz80.7
+ rgbasm.1
+ rgbasm.5
+ rgblink.1
+ rgblink.5
+ rgbfix.1
+ rgbgfx.1
+ rgbds.5
+ rgbds.7
+ gbz80.7
)
WWWPATH="/docs"
-mkdir -p "$1/_documentation/$2"
+OUTDIR="$1/_documentation/$2"
+mkdir -p "$OUTDIR"
# `mandoc` uses a different format for referring to man pages present in the **current** directory.
# We want that format for RGBDS man pages, and the other one for the rest;
-# we thus need to copy all pages to a temporary directory, and process them there.
+# this script must thus be run from the directory all man pages are in.
-# Copy all pages to current dir
-cp "${PAGES[@]}" .+for page in "${PAGES[@]}"; do+manpage="${page%.?}(${page#*.})" # "rgbasm(5)"+descr="$(awk -v 'FS=.Nd ' '/.Nd/ { print $2; }' "$page")" # "language documentation"-for page in "${!PAGES[@]}"; do-stem="${page%.html}"-manpage="${stem%.?}(${stem#*.})"-descr="$(awk -v 'FS=.Nd ' '/.Nd/ { print $2; }' "${PAGES[$page]}")"-
- cat >"$1/_documentation/$2/$page" <<EOF
+ cat >"$OUTDIR/$page.html" <<EOF
---
layout: doc
title: $manpage [$2]
@@ -73,16 +70,16 @@
---
EOF
options=fragment,man='%N.%S;https://linux.die.net/man/%S/%N'
- if [ $stem = rgbasm.5 ]; then
+ if [[ $page = rgbasm.5 ]]; then
options+=,toc
fi
- mandoc -Thtml -I os=Linux -O$options "${PAGES[$page]##*/}" | .github/actions/doc_postproc.awk >> "$1/_documentation/$2/$page"- groff -Tpdf -mdoc -wall "${PAGES[$page]##*/}" >"$1/_documentation/$2/$stem.pdf"- if [ $is_release -ne 0 ]; then
- cat - >"$1/_documentation/$page" <<EOF
+ mandoc -W warning -Thtml -I os=Linux -O$options "$page" | ../.github/actions/doc_postproc.awk >> "$OUTDIR/$page.html"
+ groff -Tpdf -mdoc -wall "$page" >"$OUTDIR/$page.pdf"
+ if [[ $is_release -ne 0 ]]; then
+ cat - >"$1/_documentation/$page.html" <<EOF
---
-redirect_to: $WWWPATH/$2/${page%.html}-permalink: $WWWPATH/${page%.html}/+redirect_to: $WWWPATH/$2/$page
+permalink: $WWWPATH/$page/
title: $manpage [latest stable]
description: RGBDS latest stable — $descr
---
@@ -90,7 +87,7 @@
fi
done
-cat - >"$1/_documentation/$2/index.html" <<EOF
+cat - >"$OUTDIR/index.html" <<EOF
---
layout: doc_index
permalink: /docs/$2/
@@ -101,13 +98,9 @@
# If making a release, add a new entry right after `master`
-if [ $is_release -ne 0 ]; then
+if [[ $is_release -ne 0 ]]; then
awk '{ print }-/"name": "master"/ { print "\t\t{\"name\": \"'$2'\", \"text\": \"'$2'\" }," }+/"name": "master"/ { print "\t\t{\"name\": \"'"$2"'\", \"text\": \"'"$2"'\" }," }' "$1/_data/doc.json" >"$1/_data/doc.json.tmp"
mv "$1/_data/doc.json"{.tmp,}fi
-
-
-# Clean up
-rm "${PAGES[@]##*/}"--- a/.github/workflows/update-master-docs.yml
+++ b/.github/workflows/update-master-docs.yml
@@ -5,15 +5,15 @@
- master
paths:
- .github/actions/get-pages.sh
- - src/gbz80.7
- - src/rgbds.5
- - src/rgbds.7
- - src/asm/rgbasm.1
- - src/asm/rgbasm.5
- - src/link/rgblink.1
- - src/link/rgblink.5
- - src/fix/rgbfix.1
- - src/gfx/rgbgfx.1
+ - man/gbz80.7
+ - man/rgbds.5
+ - man/rgbds.7
+ - man/rgbasm.1
+ - man/rgbasm.5
+ - man/rgblink.1
+ - man/rgblink.5
+ - man/rgbfix.1
+ - man/rgbgfx.1
jobs:
build:
@@ -43,9 +43,9 @@
make
sudo make install
- name: Update pages
- working-directory: rgbds
+ working-directory: rgbds/man
run: |
- ./.github/actions/get-pages.sh ../rgbds-www master
+ ../.github/actions/get-pages.sh ../../rgbds-www master
- name: Push new pages
working-directory: rgbds-www
run: |
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -97,3 +97,19 @@
message(CHECK_FAIL "no")
endif()
endif()
+
+set(MANDIR "share/man")
+set(man1 "man/rgbasm.1"
+ "man/rgbfix.1"
+ "man/rgbgfx.1"
+ "man/rgblink.1")
+set(man5 "man/rgbasm.5"
+ "man/rgblink.5"
+ "man/rgbds.5")
+set(man7 "man/gbz80.7"
+ "man/rgbds.7")
+
+foreach(SECTION "man1" "man5" "man7")
+ set(DEST "${MANDIR}/${SECTION}")+ install(FILES ${${SECTION}} DESTINATION ${DEST})+endforeach()
--- a/Makefile
+++ b/Makefile
@@ -167,15 +167,15 @@
$Qinstall ${STRIP} -m ${BINMODE} rgblink ${DESTDIR}${bindir}/rgblink $Qinstall ${STRIP} -m ${BINMODE} rgbgfx ${DESTDIR}${bindir}/rgbgfx $Qmkdir -p ${DESTDIR}${mandir}/man1 ${DESTDIR}${mandir}/man5 ${DESTDIR}${mandir}/man7- $Qinstall -m ${MANMODE} src/rgbds.7 ${DESTDIR}${mandir}/man7/rgbds.7- $Qinstall -m ${MANMODE} src/gbz80.7 ${DESTDIR}${mandir}/man7/gbz80.7- $Qinstall -m ${MANMODE} src/rgbds.5 ${DESTDIR}${mandir}/man5/rgbds.5- $Qinstall -m ${MANMODE} src/asm/rgbasm.1 ${DESTDIR}${mandir}/man1/rgbasm.1- $Qinstall -m ${MANMODE} src/asm/rgbasm.5 ${DESTDIR}${mandir}/man5/rgbasm.5- $Qinstall -m ${MANMODE} src/fix/rgbfix.1 ${DESTDIR}${mandir}/man1/rgbfix.1- $Qinstall -m ${MANMODE} src/link/rgblink.1 ${DESTDIR}${mandir}/man1/rgblink.1- $Qinstall -m ${MANMODE} src/link/rgblink.5 ${DESTDIR}${mandir}/man5/rgblink.5- $Qinstall -m ${MANMODE} src/gfx/rgbgfx.1 ${DESTDIR}${mandir}/man1/rgbgfx.1+ $Qinstall -m ${MANMODE} man/rgbds.7 ${DESTDIR}${mandir}/man7/rgbds.7+ $Qinstall -m ${MANMODE} man/gbz80.7 ${DESTDIR}${mandir}/man7/gbz80.7+ $Qinstall -m ${MANMODE} man/rgbds.5 ${DESTDIR}${mandir}/man5/rgbds.5+ $Qinstall -m ${MANMODE} man/rgbasm.1 ${DESTDIR}${mandir}/man1/rgbasm.1+ $Qinstall -m ${MANMODE} man/rgbasm.5 ${DESTDIR}${mandir}/man5/rgbasm.5+ $Qinstall -m ${MANMODE} man/rgbfix.1 ${DESTDIR}${mandir}/man1/rgbfix.1+ $Qinstall -m ${MANMODE} man/rgblink.1 ${DESTDIR}${mandir}/man1/rgblink.1+ $Qinstall -m ${MANMODE} man/rgblink.5 ${DESTDIR}${mandir}/man5/rgblink.5+ $Qinstall -m ${MANMODE} man/rgbgfx.1 ${DESTDIR}${mandir}/man1/rgbgfx.1# Target used to check the coding style of the whole codebase.
# `extern/` is excluded, as it contains external code that should not be patched
--- a/README.rst
+++ b/README.rst
@@ -57,6 +57,8 @@
│ └── ...
├── include/
│ └── ...
+ ├── man/
+ │ └── ...
├── src/
│ ├── asm/
│ │ └── ...
@@ -96,7 +98,9 @@
- ``include/`` - header files for each respective C files in `src`.
-- ``src/`` - source code and manual pages for RGBDS.
+- ``man/`` - manual pages.
+
+- ``src/`` - source code of RGBDS.
* Note that the code unique to each RGBDS tool is stored in its respective subdirectory
(rgbasm -> ``src/asm/``, for example). ``src/extern/`` contains code imported from external sources.
--- /dev/null
+++ b/man/gbz80.7
@@ -1,0 +1,1881 @@
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt GBZ80 7
+.Os
+.Sh NAME
+.Nm gbz80
+.Nd CPU opcode reference
+.Sh DESCRIPTION
+This is the list of opcodes supported by
+.Xr rgbasm 1 ,
+including a short description, the number of bytes needed to encode them and the number of CPU cycles at 1MHz (or 2MHz in GBC dual speed mode) needed to complete them.
+.Pp
+Note: All arithmetic/logic operations that use 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:
+.Bd -literal -offset indent
+OR A,B
+OR B
+.Ed
+.Sh LEGEND
+List of abbreviations used in this document.
+.Bl -tag -width Ds
+.It Ar r8
+Any of the 8-bit registers
+.Pq Sy A , B , C , D , E , H , L .
+.It Ar r16
+Any of the general-purpose 16-bit registers
+.Pq Sy BC , DE , HL .
+.It Ar n8
+8-bit integer constant.
+.It Ar n16
+16-bit integer constant.
+.It Ar e8
+8-bit offset
+.Po Sy -128
+to
+.Sy 127
+.Pc .
+.It Ar u3
+3-bit unsigned integer constant
+.Po Sy 0
+to
+.Sy 7
+.Pc .
+.It Ar cc
+Condition codes:
+.Bl -tag -width Ds -compact
+.It Sy Z
+Execute if Z is set.
+.It Sy NZ
+Execute if Z is not set.
+.It Sy C
+Execute if C is set.
+.It Sy NC
+Execute if C is not set.
+.It Sy ! cc
+Negates a condition code.
+.El
+.It Ar vec
+One of the
+.Sy RST
+vectors
+.Po Ad 0x00 , 0x08 , 0x10 , 0x18 , 0x20 , 0x28 , 0x30 ,
+and
+.Ad 0x38 Pc .
+.El
+.Sh INSTRUCTION OVERVIEW
+.Ss 8-bit Arithmetic and Logic Instructions
+.Bl -inset -compact
+.It Sx ADC A,r8
+.It Sx ADC A,[HL]
+.It Sx ADC A,n8
+.It Sx ADD A,r8
+.It Sx ADD A,[HL]
+.It Sx ADD A,n8
+.It Sx AND A,r8
+.It Sx AND A,[HL]
+.It Sx AND A,n8
+.It Sx CP A,r8
+.It Sx CP A,[HL]
+.It Sx CP A,n8
+.It Sx DEC r8
+.It Sx DEC [HL]
+.It Sx INC r8
+.It Sx INC [HL]
+.It Sx OR A,r8
+.It Sx OR A,[HL]
+.It Sx OR A,n8
+.It Sx SBC A,r8
+.It Sx SBC A,[HL]
+.It Sx SBC A,n8
+.It Sx SUB A,r8
+.It Sx SUB A,[HL]
+.It Sx SUB A,n8
+.It Sx XOR A,r8
+.It Sx XOR A,[HL]
+.It Sx XOR A,n8
+.El
+.Ss 16-bit Arithmetic Instructions
+.Bl -inset -compact
+.It Sx ADD HL,r16
+.It Sx DEC r16
+.It Sx INC r16
+.El
+.Ss Bit Operations Instructions
+.Bl -inset -compact
+.It Sx BIT u3,r8
+.It Sx BIT u3,[HL]
+.It Sx RES u3,r8
+.It Sx RES u3,[HL]
+.It Sx SET u3,r8
+.It Sx SET u3,[HL]
+.It Sx SWAP r8
+.It Sx SWAP [HL]
+.El
+.Ss Bit Shift Instructions
+.Bl -inset -compact
+.It Sx RL r8
+.It Sx RL [HL]
+.It Sx RLA
+.It Sx RLC r8
+.It Sx RLC [HL]
+.It Sx RLCA
+.It Sx RR r8
+.It Sx RR [HL]
+.It Sx RRA
+.It Sx RRC r8
+.It Sx RRC [HL]
+.It Sx RRCA
+.It Sx SLA r8
+.It Sx SLA [HL]
+.It Sx SRA r8
+.It Sx SRA [HL]
+.It Sx SRL r8
+.It Sx SRL [HL]
+.El
+.Ss Load Instructions
+.Bl -inset -compact
+.It Sx LD r8,r8
+.It Sx LD r8,n8
+.It Sx LD r16,n16
+.It Sx LD [HL],r8
+.It Sx LD [HL],n8
+.It Sx LD r8,[HL]
+.It Sx LD [r16],A
+.It Sx LD [n16],A
+.It Sx LDH [n16],A
+.It Sx LDH [C],A
+.It Sx LD A,[r16]
+.It Sx LD A,[n16]
+.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
+.It Sx CALL n16
+.It Sx CALL cc,n16
+.It Sx JP HL
+.It Sx JP n16
+.It Sx JP cc,n16
+.It Sx JR e8
+.It Sx JR cc,e8
+.It Sx RET cc
+.It Sx RET
+.It Sx RETI
+.It Sx RST vec
+.El
+.Ss Stack Operations Instructions
+.Bl -inset -compact
+.It Sx ADD HL,SP
+.It Sx ADD SP,e8
+.It Sx DEC SP
+.It Sx INC SP
+.It Sx LD SP,n16
+.It Sx LD [n16],SP
+.It Sx LD HL,SP+e8
+.It Sx LD SP,HL
+.It Sx POP AF
+.It Sx POP r16
+.It Sx PUSH AF
+.It Sx PUSH r16
+.El
+.Ss Miscellaneous Instructions
+.Bl -inset -compact
+.It Sx CCF
+.It Sx CPL
+.It Sx DAA
+.It Sx DI
+.It Sx EI
+.It Sx HALT
+.It Sx NOP
+.It Sx SCF
+.It Sx STOP
+.El
+.Sh INSTRUCTION REFERENCE
+.Ss ADC A,r8
+Add the value in
+.Ar r8
+plus the carry flag to
+.Sy A .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+Set if overflow from bit 3.
+.It Sy C
+Set if overflow from bit 7.
+.El
+.Ss ADC A,[HL]
+Add the byte pointed to by
+.Sy HL
+plus the carry flag to
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx ADC A,r8
+.Ss ADC A,n8
+Add the value
+.Ar n8
+plus the carry flag to
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx ADC A,r8
+.Ss ADD A,r8
+Add the value in
+.Ar r8
+to
+.Sy A .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+Set if overflow from bit 3.
+.It Sy C
+Set if overflow from bit 7.
+.El
+.Ss ADD A,[HL]
+Add the byte pointed to by
+.Sy HL
+to
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx ADD A,r8
+.Ss ADD A,n8
+Add the value
+.Ar n8
+to
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx ADD A,r8
+.Ss ADD HL,r16
+Add the value in
+.Ar r16
+to
+.Sy HL .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy N
+0
+.It Sy H
+Set if overflow from bit 11.
+.It Sy C
+Set if overflow from bit 15.
+.El
+.Ss ADD HL,SP
+Add the value in
+.Sy SP
+to
+.Sy HL .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx ADD HL,r16
+.Ss ADD SP,e8
+Add the signed value
+.Ar e8
+to
+.Sy SP .
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+0
+.It Sy N
+0
+.It Sy H
+Set if overflow from bit 3.
+.It Sy C
+Set if overflow from bit 7.
+.El
+.Ss AND A,r8
+Bitwise AND between the value in
+.Ar r8
+and
+.Sy A .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+1
+.It Sy C
+0
+.El
+.Ss AND A,[HL]
+Bitwise AND between the byte pointed to by
+.Sy HL
+and
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx AND A,r8
+.Ss AND A,n8
+Bitwise AND between the value in
+.Ar n8
+and
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx AND A,r8
+.Ss BIT u3,r8
+Test bit
+.Ar u3
+in register
+.Ar r8 ,
+set the zero flag if bit not set.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if the selected bit is 0.
+.It Sy N
+0
+.It Sy H
+1
+.El
+.Ss BIT u3,[HL]
+Test bit
+.Ar u3
+in the byte pointed by
+.Sy HL ,
+set the zero flag if bit not set.
+.Pp
+Cycles: 3
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx BIT u3,r8
+.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
+Bytes: 3
+.Pp
+Flags: None affected.
+.Ss CALL cc,n16
+Call address
+.Ar n16
+if condition
+.Ar cc
+is met.
+.Pp
+Cycles: 6 taken / 3 untaken
+.Pp
+Bytes: 3
+.Pp
+Flags: None affected.
+.Ss CCF
+Complement Carry Flag.
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Inverted.
+.El
+.Ss CP A,r8
+Subtract the value in
+.Ar r8
+from
+.Sy A
+and set flags accordingly, but don't store the result.
+This is useful for ComParing values.
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+1
+.It Sy H
+Set if borrow from bit 4.
+.It Sy C
+Set if borrow (i.e. if
+.Ar r8
+>
+.Sy A ) .
+.El
+.Ss CP A,[HL]
+Subtract the byte pointed to by
+.Sy HL
+from
+.Sy A
+and set flags accordingly, but don't store the result.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx CP A,r8
+.Ss CP A,n8
+Subtract the value
+.Ar n8
+from
+.Sy A
+and set flags accordingly, but don't store the result.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx CP A,r8
+.Ss CPL
+ComPLement accumulator
+.Po Sy A
+=
+.Sy ~A
+.Pc .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy N
+1
+.It Sy H
+1
+.El
+.Ss DAA
+Decimal Adjust Accumulator to get a correct BCD representation after an arithmetic instruction.
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy H
+0
+.It Sy C
+Set or reset depending on the operation.
+.El
+.Ss DEC r8
+Decrement value in register
+.Ar r8
+by 1.
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+1
+.It Sy H
+Set if borrow from bit 4.
+.El
+.Ss DEC [HL]
+Decrement the byte pointed to by
+.Sy HL
+by 1.
+.Pp
+Cycles: 3
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx DEC r8
+.Ss DEC r16
+Decrement value in register
+.Ar r16
+by 1.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss DEC SP
+Decrement value in register
+.Sy SP
+by 1.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss DI
+Disable Interrupts by clearing the
+.Sy IME
+flag.
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss EI
+Enable Interrupts by setting the
+.Sy IME
+flag.
+The flag is only set
+.Em after
+the instruction following
+.Sy EI .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss HALT
+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
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss INC r8
+Increment value in register
+.Ar r8
+by 1.
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+Set if overflow from bit 3.
+.El
+.Ss INC [HL]
+Increment the byte pointed to by
+.Sy HL
+by 1.
+.Pp
+Cycles: 3
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx INC r8
+.Ss INC r16
+Increment value in register
+.Ar r16
+by 1.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss INC SP
+Increment value in register
+.Sy SP
+by 1.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss JP n16
+Jump to address
+.Ar n16 ;
+effectively, store
+.Ar n16
+into
+.Sy PC .
+.Pp
+Cycles: 4
+.Pp
+Bytes: 3
+.Pp
+Flags: None affected.
+.Ss JP cc,n16
+Jump to address
+.Ar n16
+if condition
+.Ar cc
+is met.
+.Pp
+Cycles: 4 taken / 3 untaken
+.Pp
+Bytes: 3
+.Pp
+Flags: None affected.
+.Ss JP HL
+Jump to address in
+.Sy HL ;
+effectively, load
+.Sy PC
+with value in register
+.Sy HL .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss JR e8
+Relative Jump by adding
+.Ar e8
+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
+Bytes: 2
+.Pp
+Flags: None affected.
+.Ss JR cc,e8
+Relative Jump by adding
+.Ar e8
+to the current address if condition
+.Ar cc
+is met.
+.Pp
+Cycles: 3 taken / 2 untaken
+.Pp
+Bytes: 2
+.Pp
+Flags: None affected.
+.Ss LD r8,r8
+Load (copy) value in register on the right into register on the left.
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss LD r8,n8
+Load value
+.Ar n8
+into register
+.Ar r8 .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: None affected.
+.Ss LD r16,n16
+Load value
+.Ar n16
+into register
+.Ar r16 .
+.Pp
+Cycles: 3
+.Pp
+Bytes: 3
+.Pp
+Flags: None affected.
+.Ss LD [HL],r8
+Store value in register
+.Ar r8
+into the byte pointed to by register
+.Sy HL .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss LD [HL],n8
+Store value
+.Ar n8
+into the byte pointed to by register
+.Sy HL .
+.Pp
+Cycles: 3
+.Pp
+Bytes: 2
+.Pp
+Flags: None affected.
+.Ss LD r8,[HL]
+Load value into register
+.Ar r8
+from the byte pointed to by register
+.Sy HL .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss LD [r16],A
+Store value in register
+.Sy A
+into the byte pointed to by register
+.Ar r16 .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss LD [n16],A
+Store value in register
+.Sy A
+into the byte at address
+.Ar n16 .
+.Pp
+Cycles: 4
+.Pp
+Bytes: 3
+.Pp
+Flags: None affected.
+.Ss LDH [n16],A
+Store value in register
+.Sy A
+into the byte at address
+.Ar n16 ,
+provided the address is between
+.Ad $FF00
+and
+.Ad $FFFF .
+.Pp
+Cycles: 3
+.Pp
+Bytes: 2
+.Pp
+Flags: None affected.
+.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 the byte at address
+.Ad $FF00+C .
+.Pp
+Cycles: 2
+.Pp
+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 the byte pointed to by register
+.Ar r16 .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss LD A,[n16]
+Load value in register
+.Sy A
+from the byte at address
+.Ar n16 .
+.Pp
+Cycles: 4
+.Pp
+Bytes: 3
+.Pp
+Flags: None affected.
+.Ss LDH A,[n16]
+Load value in register
+.Sy A
+from the byte at address
+.Ar n16 ,
+provided the address is between
+.Ad $FF00
+and
+.Ad $FFFF .
+.Pp
+Cycles: 3
+.Pp
+Bytes: 2
+.Pp
+Flags: None affected.
+.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 the byte at address
+.Ad $FF00+c .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.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 the byte pointed by
+.Sy HL
+and increment
+.Sy HL
+afterwards.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Pp
+This is sometimes written as
+.Ql LD [HL+],A ,
+or
+.Ql LDI [HL],A .
+.Ss LD [HLD],A
+Store value in register
+.Sy A
+into the byte pointed by
+.Sy HL
+and decrement
+.Sy HL
+afterwards.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Pp
+This is sometimes written as
+.Ql LD [HL-],A ,
+or
+.Ql LDD [HL],A .
+.Ss LD A,[HLD]
+Load value into register
+.Sy A
+from the byte pointed by
+.Sy HL
+and decrement
+.Sy HL
+afterwards.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Pp
+This is sometimes written as
+.Ql LD A,[HL-] ,
+or
+.Ql LDD A,[HL] .
+.Ss LD A,[HLI]
+Load value into register
+.Sy A
+from the byte pointed by
+.Sy HL
+and increment
+.Sy HL
+afterwards.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Pp
+This is sometimes written as
+.Ql LD A,[HL+] ,
+or
+.Ql LDI A,[HL] .
+.Ss LD SP,n16
+Load value
+.Ar n16
+into register
+.Sy SP .
+.Pp
+Cycles: 3
+.Pp
+Bytes: 3
+.Pp
+Flags: None affected.
+.Ss LD [n16],SP
+Store
+.Sy SP & $FF
+at address
+.Ar n16
+and
+.Sy SP >> 8
+at address
+.Ar n16
++ 1.
+.Pp
+Cycles: 5
+.Pp
+Bytes: 3
+.Pp
+Flags: None affected.
+.Ss LD HL,SP+e8
+Add the signed value
+.Ar e8
+to
+.Sy SP
+and store the result in
+.Sy HL .
+.Pp
+Cycles: 3
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+0
+.It Sy N
+0
+.It Sy H
+Set if overflow from bit 3.
+.It Sy C
+Set if overflow from bit 7.
+.El
+.Ss LD SP,HL
+Load register
+.Sy HL
+into register
+.Sy SP .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss NOP
+No OPeration.
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss OR A,r8
+Store into
+.Sy A
+the bitwise OR of the value in
+.Ar r8
+and
+.Sy A .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+0
+.El
+.Ss OR A,[HL]
+Store into
+.Sy A
+the bitwise OR of the byte pointed to by
+.Sy HL
+and
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx OR A,r8
+.Ss OR A,n8
+Store into
+.Sy A
+the bitwise OR of
+.Ar n8
+and
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx OR A,r8
+.Ss POP AF
+Pop register
+.Sy AF
+from the stack.
+This is roughly equivalent to the following
+.Em imaginary
+instructions:
+.Bd -literal -offset indent
+ld f, [sp] ; See below for individual flags
+inc sp
+ld a, [sp]
+inc sp
+.Ed
+.Pp
+Cycles: 3
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set from bit 7 of the popped low byte.
+.It Sy N
+Set from bit 6 of the popped low byte.
+.It Sy H
+Set from bit 5 of the popped low byte.
+.It Sy C
+Set from bit 4 of the popped low byte.
+.El
+.Ss POP r16
+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
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss PUSH AF
+Push register
+.Sy AF
+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
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss PUSH r16
+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
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss RES u3,r8
+Set bit
+.Ar u3
+in register
+.Ar r8
+to 0.
+Bit 0 is the rightmost one, bit 7 the leftmost one.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: None affected.
+.Ss RES u3,[HL]
+Set bit
+.Ar u3
+in the byte pointed by
+.Sy HL
+to 0.
+Bit 0 is the rightmost one, bit 7 the leftmost one.
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+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
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss RET cc
+Return from subroutine if condition
+.Ar cc
+is met.
+.Pp
+Cycles: 5 taken / 2 untaken
+.Pp
+Bytes: 1
+.Pp
+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
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss RL r8
+Rotate bits in register
+.Ar r8
+left through carry.
+.Pp
+.D1 C <- [7 <- 0] <- C
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss RL [HL]
+Rotate the byte pointed to by
+.Sy HL
+left through carry.
+.Pp
+.D1 C <- [7 <- 0] <- C
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx RL r8
+.Ss RLA
+Rotate register
+.Sy A
+left through carry.
+.Pp
+.D1 C <- [7 <- 0] <- C
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+0
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss RLC r8
+Rotate register
+.Ar r8
+left.
+.Pp
+.D1 C <- [7 <- 0] <- [7]
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss RLC [HL]
+Rotate the byte pointed to by
+.Sy HL
+left.
+.Pp
+.D1 C <- [7 <- 0] <- [7]
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx RLC r8
+.Ss RLCA
+Rotate register
+.Sy A
+left.
+.Pp
+.D1 C <- [7 <- 0] <- [7]
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+0
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss RR r8
+Rotate register
+.Ar r8
+right through carry.
+.Pp
+.D1 C -> [7 -> 0] -> C
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss RR [HL]
+Rotate the byte pointed to by
+.Sy HL
+right through carry.
+.Pp
+.D1 C -> [7 -> 0] -> C
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx RR r8
+.Ss RRA
+Rotate register
+.Sy A
+right through carry.
+.Pp
+.D1 C -> [7 -> 0] -> C
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+0
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss RRC r8
+Rotate register
+.Ar r8
+right.
+.Pp
+.D1 [0] -> [7 -> 0] -> C
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss RRC [HL]
+Rotate the byte pointed to by
+.Sy HL
+right.
+.Pp
+.D1 [0] -> [7 -> 0] -> C
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx RRC r8
+.Ss RRCA
+Rotate register
+.Sy A
+right.
+.Pp
+.D1 [0] -> [7 -> 0] -> C
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+0
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss RST vec
+Call address
+.Ar vec .
+This is a shorter and faster equivalent to
+.Sx CALL
+for suitable values of
+.Ar vec .
+.Pp
+Cycles: 4
+.Pp
+Bytes: 1
+.Pp
+Flags: None affected.
+.Ss SBC A,r8
+Subtract the value in
+.Ar r8
+and the carry flag from
+.Sy A .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+1
+.It Sy H
+Set if borrow from bit 4.
+.It Sy C
+Set if borrow (i.e. if
+.Po Ar r8
++ carry
+.Pc >
+.Sy A ) .
+.El
+.Ss SBC A,[HL]
+Subtract the byte pointed to by
+.Sy HL
+and the carry flag from
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx SBC A,r8
+.Ss SBC A,n8
+Subtract the value
+.Ar n8
+and the carry flag from
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx SBC A,r8
+.Ss SCF
+Set Carry Flag.
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+1
+.El
+.Ss SET u3,r8
+Set bit
+.Ar u3
+in register
+.Ar r8
+to 1.
+Bit 0 is the rightmost one, bit 7 the leftmost one.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: None affected.
+.Ss SET u3,[HL]
+Set bit
+.Ar u3
+in the byte pointed by
+.Sy HL
+to 1.
+Bit 0 is the rightmost one, bit 7 the leftmost one.
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags: None affected.
+.Ss SLA r8
+Shift Left Arithmetically register
+.Ar r8 .
+.Pp
+.D1 C <- [7 <- 0] <- 0
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss SLA [HL]
+Shift Left Arithmetically the byte pointed to by
+.Sy HL .
+.Pp
+.D1 C <- [7 <- 0] <- 0
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx SLA r8
+.Ss SRA r8
+Shift Right Arithmetically register
+.Ar r8 .
+.Pp
+.D1 [7] -> [7 -> 0] -> C
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss SRA [HL]
+Shift Right Arithmetically the byte pointed to by
+.Sy HL .
+.Pp
+.D1 [7] -> [7 -> 0] -> C
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx SRA r8
+.Ss SRL r8
+Shift Right Logically register
+.Ar r8 .
+.Pp
+.D1 0 -> [7 -> 0] -> C
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+Set according to result.
+.El
+.Ss SRL [HL]
+Shift Right Logically the byte pointed to by
+.Sy HL .
+.Pp
+.D1 0 -> [7 -> 0] -> C
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx SRA r8
+.Ss STOP
+Enter CPU very low power mode.
+Also used to switch between double and normal speed CPU modes in GBC.
+.Pp
+Cycles: -
+.Pp
+Bytes: 2
+.Pp
+Flags: None affected.
+.Ss SUB A,r8
+Subtract the value in
+.Ar r8
+from
+.Sy A .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+1
+.It Sy H
+Set if borrow from bit 4.
+.It Sy C
+Set if borrow (set if
+.Ar r8
+>
+.Sy A ) .
+.El
+.Ss SUB A,[HL]
+Subtract the byte pointed to by
+.Sy HL
+from
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx SUB A,r8
+.Ss SUB A,n8
+Subtract the value
+.Ar n8
+from
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx SUB A,r8
+.Ss SWAP r8
+Swap the upper 4 bits in register
+.Ar r8
+and the lower 4 ones.
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+0
+.El
+.Ss SWAP [HL]
+Swap the upper 4 bits in the byte pointed by
+.Sy HL
+and the lower 4 ones.
+.Pp
+Cycles: 4
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx SWAP r8
+.Ss XOR A,r8
+Bitwise XOR between the value in
+.Ar r8
+and
+.Sy A .
+.Pp
+Cycles: 1
+.Pp
+Bytes: 1
+.Pp
+Flags:
+.Bl -hang -compact
+.It Sy Z
+Set if result is 0.
+.It Sy N
+0
+.It Sy H
+0
+.It Sy C
+0
+.El
+.Ss XOR A,[HL]
+Bitwise XOR between the byte pointed to by
+.Sy HL
+and
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 1
+.Pp
+Flags: See
+.Sx XOR A,r8
+.Ss XOR A,n8
+Bitwise XOR between the value in
+.Ar n8
+and
+.Sy A .
+.Pp
+Cycles: 2
+.Pp
+Bytes: 2
+.Pp
+Flags: See
+.Sx XOR A,r8
+.Sh SEE ALSO
+.Xr rgbasm 1 ,
+.Xr rgbds 7
+.Sh HISTORY
+.Nm rgbds
+was originally written by Carsten S\(/orensen as part of the ASMotor package,
+and was later packaged in RGBDS by Justin Lloyd.
+It is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .
--- /dev/null
+++ b/man/rgbasm.1
@@ -1,0 +1,315 @@
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBASM 1
+.Os
+.Sh NAME
+.Nm rgbasm
+.Nd Game Boy assembler
+.Sh SYNOPSIS
+.Nm
+.Op Fl EhLVvw
+.Op Fl b Ar chars
+.Op Fl D Ar name Ns Op = Ns Ar value
+.Op Fl g Ar chars
+.Op Fl i Ar path
+.Op Fl M Ar depend_file
+.Op Fl MG
+.Op Fl MP
+.Op Fl MT Ar target_file
+.Op Fl MQ Ar target_file
+.Op Fl o Ar out_file
+.Op Fl p Ar pad_value
+.Op Fl r Ar recursion_depth
+.Op Fl W Ar warning
+.Ar
+.Sh DESCRIPTION
+The
+.Nm
+program creates an RGB object file from an assembly source file.
+The input
+.Ar file
+can be a file path, or
+.Cm \-
+denoting
+.Cm stdin .
+.Pp
+Note that options can be abbreviated as long as the abbreviation is unambiguous:
+.Fl Fl verb
+is
+.Fl Fl verbose ,
+but
+.Fl Fl ver
+is invalid because it could also be
+.Fl Fl version .
+The arguments are as follows:
+.Bl -tag -width Ds
+.It Fl b Ar chars , Fl Fl binary-digits Ar chars
+Change the two characters used for binary constants.
+The defaults are 01.
+.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 \(dq Ns Ar value Ns \(dq
+in code, or
+.Ql Ar name Ic EQUS \(dq1\(dq
+if
+.Ar value
+is not specified.
+.It Fl E , Fl Fl export-all
+Export all labels, including unreferenced and local labels.
+.It Fl g Ar chars , Fl Fl gfx-chars Ar chars
+Change the four characters used for gfx constants.
+The defaults are 0123.
+.It Fl h , Fl Fl halt-without-nop
+By default,
+.Nm
+inserts a
+.Ic nop
+instruction immediately after any
+.Ic halt
+instruction.
+The
+.Fl h
+option disables this behavior.
+.It Fl i Ar path , Fl Fl include Ar path
+Add an include path.
+.It Fl L , Fl Fl preserve-ld
+Disable the optimization that turns loads of the form
+.Ic LD [$FF00+n8],A
+into the opcode
+.Ic LDH [$FF00+n8],A
+in order to have full control of the result in the final ROM.
+.It Fl M Ar depend_file , Fl Fl dependfile Ar depend_file
+.Xr make 1
+dependencies to
+.Ar depend_file .
+.It Fl MG
+To be used in conjunction with
+.Fl M .
+This makes
+.Nm
+assume that missing files are auto-generated: when
+.Ic INCLUDE
+or
+.Ic INCBIN
+is attempted on a non-existent file, it is added as a dependency, then
+.Nm
+exits normally instead of erroring out.
+This feature is used in automatic updating of makefiles.
+.It Fl MP
+When enabled, this causes a phony target to be added for each dependency other than the main file.
+This prevents
+.Xr make 1
+from erroring out when dependency files are deleted.
+.It Fl MT Ar target_file
+Add a target to the rules emitted by
+.Fl M .
+The exact string provided will be written, including spaces and special characters.
+.Dl Fl MT No fileA Fl MT No fileB
+is equivalent to
+.Dl Fl MT No 'fileA fileB' .
+If neither this nor
+.Fl MQ
+is specified, the output file name is used.
+.It Fl MQ Ar target_file
+Same as
+.Fl MT ,
+but additionally escapes any special
+.Xr make 1
+characters, essentially
+.Sq $ .
+.It Fl o Ar out_file , Fl Fl output Ar out_file
+Write an object file to the given filename.
+.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
+When padding an image, pad with this value.
+The default is 0x00.
+.It Fl r Ar recursion_depth , Fl Fl recursion-depth Ar recursion_depth
+Specifies the recursion depth at which RGBASM will assume being in an infinite loop.
+.It Fl V , Fl Fl version
+Print the version of the program and exit.
+.It Fl v , Fl Fl verbose
+Be verbose.
+.It Fl W Ar warning , Fl Fl warning Ar warning
+Set warning flag
+.Ar warning .
+A warning message will be printed if
+.Ar warning
+is an unknown warning flag.
+See the
+.Sx DIAGNOSTICS
+section for a list of warnings.
+.It Fl w
+Disable all warning output, even when turned into errors.
+.El
+.Sh DIAGNOSTICS
+Warnings are diagnostic messages that indicate possibly erroneous behavior that does not necessarily compromise the assembling process.
+The following options alter the way warnings are processed.
+.Bl -tag -width Ds
+.It Fl Werror
+Make all warnings into errors.
+.It Fl Werror=
+Make the specified warning into an error.
+A warning's name is appended
+.Pq example: Fl Werror=obsolete ,
+and this warning is implicitly enabled and turned into an error.
+This is an error if used with a meta warning, such as
+.Fl Werror=all .
+.El
+.Pp
+The following warnings are
+.Dq meta
+warnings, that enable a collection of other warnings.
+If a specific warning is toggled via a meta flag and a specific one, the more specific one takes priority.
+The position on the command-line acts as a tie breaker, the last one taking effect.
+.Bl -tag -width Ds
+.It Fl Wall
+This enables warnings that are likely to indicate an error or undesired behavior, and that can easily be fixed.
+.It Fl Wextra
+This enables extra warnings that are less likely to pose a problem, but that may still be wanted.
+.It Fl Weverything
+Enables literally every warning.
+.El
+.Pp
+The following warnings are actual warning flags; with each description, the corresponding warning flag is included.
+Note that each of these flag also has a negation (for example,
+.Fl Wcharmap-redef
+enables the warning that
+.Fl Wno-charmap-redef
+disables).
+Only the non-default flag is listed here.
+Ignoring the
+.Dq no-
+prefix, entries are listed alphabetically.
+.Bl -tag -width Ds
+.It Fl Wno-assert
+Warn when
+.Ic WARN Ns No -type
+assertions fail. (See
+.Dq Aborting the assembly process
+in
+.Xr rgbasm 5
+for
+.Ic ASSERT ) .
+.It Fl Wbackwards-for
+Warn when
+.Ic FOR
+loops have their start and stop values switched according to the step value.
+This warning is enabled by
+.Fl Wall .
+.It Fl Wbuiltin-args
+Warn about incorrect arguments to built-in functions, such as
+.Fn STRSUB
+with indexes outside of the string's bounds.
+This warning is enabled by
+.Fl Wall .
+.It Fl Wcharmap-redef
+Warn when re-defining a charmap mapping.
+This warning is enabled by
+.Fl Wall .
+.It Fl Wdiv
+Warn when dividing the smallest negative integer (-2**31) by -1, which yields itself due to integer overflow.
+.It Fl Wempty-macro-arg
+Warn when a macro argument is empty.
+This warning is enabled by
+.Fl Wextra .
+.It Fl Wempty-strrpl
+Warn when
+.Fn STRRPL
+is called with an empty string as its second argument (the substring to replace).
+This warning is enabled by
+.Fl Wall .
+.It Fl Wlarge-constant
+Warn when a constant too large to fit in a signed 32-bit integer is encountered.
+This warning is enabled by
+.Fl Wall .
+.It Fl Wlong-string
+Warn when a string too long to fit in internal buffers is encountered.
+This warning is enabled by
+.Fl Wall .
+.It Fl Wmacro-shift
+Warn when shifting macro arguments past their limits.
+This warning is enabled by
+.Fl Wextra .
+.It Fl Wno-obsolete
+Warn when obsolete constructs such as the
+.Ic _PI
+constant or
+.Ic PRINTT
+directive are encountered.
+.It Fl Wnumeric-string=
+Warn when a multi-character string is treated as a number.
+.Fl Wnumeric-string=0
+or
+.Fl Wno-numeric-string
+disables this warning.
+.Fl Wnumeric-string=1
+or just
+.Fl Wnumeric-string
+warns about strings longer than four characters, since four or fewer characters fit within a 32-bit integer.
+.Fl Wnumeric-string=2
+warns about any multi-character string.
+.It Fl Wshift
+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 Wtruncation=
+Warn when an implicit truncation (for example,
+.Ic db
+to an 8-bit value) loses some bits.
+.Fl Wtruncation=0
+or
+.Fl Wno-truncation
+disables this warning.
+.Fl Wtruncation=1
+warns when an N-bit value's absolute value is 2**N or greater.
+.Fl Wtruncation=2
+or just
+.Fl Wtruncation
+also warns when an N-bit value is less than -2**(N-1), which will not fit in two's complement encoding.
+.It Fl Wno-user
+Warn when the
+.Ic WARN
+built-in is executed. (See
+.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
+Pipes way:
+.Dl $ cat foo.asm | rgbasm -o bar.o -
+.Dl $ rgbasm -o bar.o - < foo.asm
+.Pp
+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 .
+.Sh BUGS
+Please report bugs on
+.Lk https://github.com/gbdev/rgbds/issues GitHub .
+.Sh SEE ALSO
+.Xr rgbasm 5 ,
+.Xr rgbfix 1 ,
+.Xr rgblink 1 ,
+.Xr rgbds 5 ,
+.Xr rgbds 7 ,
+.Xr gbz80 7
+.Sh HISTORY
+.Nm
+was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
+It is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .
--- /dev/null
+++ b/man/rgbasm.5
@@ -1,0 +1,2071 @@
+'\" e
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBASM 5
+.Os
+.Sh NAME
+.Nm rgbasm
+.Nd language documentation
+.Sh DESCRIPTION
+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
+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 RGBDS object files (described in
+.Xr rgbds 5 )
+can be used in its place.
+.Sh SYNTAX
+The syntax is line-based, just as in any other assembler, meaning that you do one instruction or directive per line:
+.Pp
+.Dl Oo Ar label Oc Oo Ar instruction Oc Oo Ar ;\ comment Oc
+.Pp
+Example:
+.Bd -literal -offset indent
+John: ld a,87 ;Weee
+.Ed
+.Pp
+All reserved keywords (directives, mnemonics, registers, etc.) are case-insensitive;
+all identifiers (symbol names) are case-sensitive.
+.Pp
+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 \&;
+not inside a string, is a comment until the end of the line.
+The second is a block comment, beginning with
+.Ql /*
+and ending with
+.Ql */ .
+It can be split across multiple lines, or occur in the middle of an expression:
+.Bd -literal -offset indent
+X = /* the value of x
+ should be 3 */ 3
+.Ed
+.Pp
+Sometimes lines can be too long and it may be necessary to split them.
+To do so, put a backslash at the end of the line:
+.Bd -literal -offset indent
+ DB 1, 2, 3,\ \[rs]
+ 4, 5, 6,\ \[rs]\ ;\ Put it before any comments
+ 7, 8, 9
+ DB "Hello,\ \[rs]\ \ ;\ Space before the \[rs] is included
+world!"\ \ \ \ \ \ \ \ \ \ \ ;\ Any leading space is included
+.Ed
+.Ss Symbol interpolation
+A funky feature is
+.Ql {symbol}+within a string, called
+.Dq symbol interpolation .
+This will paste the contents of
+.Ql symbol
+as if they were part of the source file.
+If it is a string symbol, its characters are simply inserted as-is.
+If it is a numeric symbol, its value is converted to hexadecimal notation with a dollar sign
+.Sq $
+prepended.
+.Pp
+Symbol interpolations can be nested, too!
+.Bd -literal -offset indent
+DEF topic EQUS "life, the universe, and \[rs]"everything\[rs]""
+DEF meaning EQUS "answer"
+;\ Defines answer = 42
+DEF {meaning} = 42+;\ Prints "The answer to life, the universe, and "everything" is $2A"
+PRINTLN "The {meaning} to {topic} is {{meaning}}"+PURGE topic, meaning, {meaning}+.Ed
+.Pp
+Symbols can be
+.Em interpolated
+even in the contexts that disable automatic
+.Em expansion
+of string constants:
+.Ql name
+will be expanded in all of
+.Ql DEF({name}) ,+.Ql DEF {name} EQU/=/EQUS/etc ... ,+.Ql PURGE {name} ,+and
+.Ql MACRO {name} ,+but, for example, won't be in
+.Ql DEF(name) .
+.Pp
+It's possible to change the way symbols are printed by specifying a print format like so:
+.Ql {fmt:symbol} .+The
+.Ql fmt
+specifier consists of these parts:
+.Ql <sign><prefix><align><pad><width><frac><type> .
+These parts are:
+.Bl -column "<prefix>"
+.It Sy Part Ta Sy Meaning
+.It Ql <sign> Ta May be
+.Ql +
+or
+.Ql \ .
+If specified, prints this character in front of non-negative numbers.
+.It Ql <prefix> Ta May be
+.Ql # .
+If specified, prints the appropriate prefix for numbers,
+.Ql $ ,
+.Ql & ,
+or
+.Ql % .
+.It Ql <align> Ta May be
+.Ql - .
+If specified, aligns left instead of right.
+.It Ql <pad> Ta May be
+.Ql 0 .
+If specified, pads right-aligned numbers with zeros instead of spaces.
+.It Ql <width> Ta May be one or more
+.Ql 0
+\[en]
+.Ql 9 .
+If specified, pads the value to this width, right-aligned with spaces by default.
+.It Ql <frac> Ta May be
+.Ql \&.
+followed by one or more
+.Ql 0
+\[en]
+.Ql 9 .
+If specified, prints this many digits of a fixed-point fraction.
+Defaults to 5 digits, maximum 255 digits.
+.It Ql <type> Ta Specifies the type of value.
+.El
+.Pp
+All the format specifier parts are optional except the
+.Ql <type> .
+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 Signed decimal Ta -42
+.It Ql u Ta Unsigned 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
+.It Ql o Ta Octal Ta 52
+.It Ql f Ta Fixed-point Ta 1234.56789
+.It Ql s Ta String Ta \&"example\&"
+.El
+.Pp
+Examples:
+.Bd -literal -offset indent
+SECTION "Test", ROM0[2]
+X: ;\ This works with labels **whose address is known**
+Y = 3 ;\ This also works with variables
+SUM equ X + Y ;\ And likewise with numeric constants
+; Prints "%0010 + $3 == 5"
+PRINTLN "{#05b:X} + {#x:Y} == {d:SUM}"+
+rsset 32
+PERCENT rb 1 ;\ Same with offset constants
+VALUE = 20
+RESULT = MUL(20.0, 0.32)
+; Prints "32% of 20 = 6.40"
+PRINTLN "{d:PERCENT}% of {d:VALUE} = {f:RESULT}"+
+WHO equs STRLWR("WORLD")+; Prints "Hello world!"
+PRINTLN "Hello {s:WHO}!"+.Ed
+.Pp
+Although, for these examples,
+.Ic STRFMT
+would be more approriate; see
+.Sx String expressions
+further below.
+.Sh EXPRESSIONS
+An expression can be composed of many things.
+Numeric 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
+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
+The instructions in the macro-language generally require constant expressions.
+.Ss Numeric formats
+There are a number of numeric formats.
+.Bl -column -offset indent "Fixed point (Q16.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 (Q16.16) Ta none Ta 01234.56789
+.It Character constant Ta none Ta \(dqABYZ\(dq
+.It Gameboy graphics Ta \` Ta 0123
+.El
+.Pp
+Underscores are also accepted in numbers, except at the beginning of one.
+This can be useful for grouping digits, like
+.Ql 123_456
+or
+.Ql %1100_1001 .
+.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
+A great number of operators you can use in expressions are available (listed from highest to lowest precedence):
+.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 Exponent
+.It Li ~ + - Ta Unary complement/plus/minus
+.It Li * / % Ta Multiply/divide/modulo
+.It Li << Ta Shift left
+.It Li >> Ta Signed shift right (sign-extension)
+.It Li >>> Ta Unsigned shift right (zero-extension)
+.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, so that
+.Sq a / b * b + a % b == a
+is always true.
+The result has the same sign as the divisor.
+This makes
+.Sq a % b .
+equal to
+.Sq (a + b) % b
+or
+.Sq (a - b) % b .
+.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
+.Ic \&!
+returns 1 if the operand was 0, and 0 otherwise.
+.Ss Fixed-point expressions
+Fixed-point numbers are basically normal (32-bit) integers, which count 65536ths 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
+.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 POW x y Ta $x$ to the $y$ power
+.It Fn LOG x y Ta Logarithm of $x$ to the base $y$
+.It Fn ROUND x Ta Round $x$ to the nearest integer
+.It Fn CEIL x Ta Round $x$ up to an integer
+.It Fn FLOOR x Ta Round $x$ down to an integer
+.It Fn SIN x Ta Sine of $x$
+.It Fn COS x Ta Cosine of $x$
+.It Fn TAN x Ta Tangent of $x$
+.It Fn ASIN x Ta Inverse sine of $x$
+.It Fn ACOS x Ta Inverse cosine of $x$
+.It Fn ATAN x Ta Inverse tangent of $x$
+.It Fn ATAN2 x y Ta Angle between $( x , y )$ and $( 1 , 0 )$
+.El
+.EQ
+delim off
+.EN
+.Pp
+The trigonometry functions (
+.Ic SIN ,
+.Ic COS ,
+.Ic TAN ,
+etc) are defined in terms of a circle divided into 65535.0 degrees.
+.Pp
+These functions are useful for automatic generation of various tables.
+For example:
+.Bd -literal -offset indent
+; Generate a 256-byte sine table with values in the range [0, 128]
+; (shifted and scaled from the range [-1.0, 1.0])
+ANGLE = 0.0
+ REPT 256
+ db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
+ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
+ ENDR
+.Ed
+.Ss String expressions
+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:
+.Bl -column -offset indent "Qo \[rs]1 Qc \[en] Qo \[rs]9 Qc"
+.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 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 in the body of a macro; see Sx Invoking macros )
+.It Ql \[rs]# Ta All Dv _NARG No macro arguments, separated by commas (Only in the body of a macro)
+.It Ql \[rs]@ Ta Label name suffix (Only in the body of a macro or a Ic REPT No block)
+.El
+(Note that some of those can be used outside of strings, when noted further in this document.)
+.Pp
+Multi-line strings are contained in triple quotes
+.Pq Ql \&"\&"\&"for instance\&"\&"\&" .
+Escape sequences work the same way in multi-line strings; however, literal newline
+characters will be included as-is, without needing to escape them with
+.Ql \[rs]r
+or
+.Ql \[rs]n .
+.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!
+.Bl -column "STRSUB(str, pos, len)"
+.It Sy Name Ta Sy Operation
+.It Fn STRLEN str Ta Returns the number of characters in Ar str .
+.It Fn STRCAT strs... Ta Concatenates Ar strs .
+.It Fn STRCMP str1 str2 Ta Returns -1 if Ar str1 No is alphabetically lower than Ar str2 No , zero if they match, 1 if Ar str1 No is greater than Ar str2 .
+.It Fn STRIN str1 str2 Ta Returns the first position of Ar str2 No in Ar str1 No or zero if it's not present Pq first character is position 1 .
+.It Fn STRRIN str1 str2 Ta Returns the last 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 No (first character is position 1, last is position -1) and Ar len No characters long. If Ar len No is not specified the substring continues to the end of Ar str .
+.It Fn STRUPR str Ta Returns Ar str No with all letters in uppercase.
+.It Fn STRLWR str Ta Returns Ar str No with all letters in lowercase.
+.It Fn STRRPL str old new Ta Returns Ar str No with each non-overlapping occurrence of the substring Ar old No replaced with Ar new .
+.It Fn STRFMT fmt args... Ta Returns the string Ar fmt No with each
+.Ql %spec
+pattern replaced by interpolating the format
+.Ar spec
+.Pq using the same syntax as Sx Symbol interpolation
+with its corresponding argument in
+.Ar args
+.Pq So %% Sc is replaced by the So % Sc character .
+.It Fn CHARLEN str Ta Returns the number of charmap entries in Ar str No with the current charmap.
+.It Fn CHARSUB str pos Ta Returns the substring for the charmap entry at Ar pos No in Ar str No (first character is position 1, last is position -1) with the current charmap.
+.El
+.Ss Character maps
+When writing text strings that are meant to be displayed on the Game Boy, the character encoding in the ROM may need to be different than the source file encoding.
+For example, the tiles used for uppercase letters may be placed starting at tile index 128, which differs from ASCII starting at 65.
+.Pp
+Character maps allow mapping strings to arbitrary 8-bit values:
+.Bd -literal -offset indent
+CHARMAP "<LF>", 10
+CHARMAP "í", 20
+CHARMAP "A", 128
+.Ed
+This would result in
+.Ql db \(dqAmen<LF>\(dq
+being equivalent to
+.Ql db 128, 109, 101, 110, 10 .
+.Pp
+Any characters in a string without defined mappings will be copied directly, using the source file's encoding of characters to bytes.
+.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 No and switches to it.
+.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename , No and switches to it.
+.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:
+Modifications to a character map take effect immediately from that point onward.
+.Ss Other functions
+There are a few other functions that do various useful things:
+.Bl -column "DEF(symbol)"
+.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 SIZEOF arg Ta Returns the size of the section named
+.Ar arg .
+The result is not constant, since only RGBLINK can compute its value.
+.It Fn STARTOF arg Ta Returns the starting address of the section named
+.Ar arg .
+The result is not constant, since only RGBLINK can compute its value.
+.It Fn DEF symbol Ta Returns TRUE (1) if
+.Ar symbol
+has been defined, FALSE (0) otherwise.
+String constants 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
+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.
+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.
+.Pp
+Possible section
+.Ar type Ns s
+are as follows:
+.Bl -tag -width Ds
+.It Ic ROM0
+A ROM section.
+.Ar addr
+can range from
+.Ad $0000
+to
+.Ad $3FFF ,
+or
+.Ad $0000
+to
+.Ad $7FFF
+if tiny ROM mode is enabled in the linker.
+.It Ic ROMX
+A banked ROM section.
+.Ar addr
+can range from
+.Ad $4000
+to
+.Ad $7FFF .
+.Ar bank
+can range from 1 to 511.
+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
+.Ad $8000
+to
+.Ad $9FFF .
+.Ar bank
+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
+.Ad $A000
+to
+.Ad $BFFF .
+.Ar bank
+can range from 0 to 15.
+.It Ic WRAM0
+A general-purpose RAM section.
+.Ar addr
+can range from
+.Ad $C000
+to
+.Ad $CFFF ,
+or
+.Ad $C000
+to
+.Ad $DFFF
+if WRAM0 mode is enabled in the linker.
+.It Ic WRAMX
+A banked general-purpose RAM section.
+.Ar addr
+can range from
+.Ad $D000
+to
+.Ad $DFFF .
+.Ar bank
+can range from 1 to 7.
+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
+.Ad $FE00
+to
+.Ad $FE9F .
+.It Ic HRAM
+A high RAM section.
+.Ar addr
+can range from
+.Ad $FF80
+to
+.Ad $FFFE .
+.Pp
+.Sy Note :
+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 -width Ds
+.It Ic BANK Ns Bq Ar bank
+Specify which
+.Ar bank
+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 , offset
+Place the section at an address whose
+.Ar align
+least-significant bits are equal to
+.Ar offset .
+(Note that
+.Ic ALIGN Ns Bq Ar align
+is a shorthand for
+.Ic ALIGN Ns Bq Ar align , No 0 ) .
+This option can be used with
+.Bq Ar addr ,
+as long as they don't contradict eachother.
+It's also possible to request alignment in the middle of a section, see
+.Sx Requesting alignment
+below.
+.El
+.Pp
+If
+.Bq Ar addr
+is not specified, the section is considered
+.Dq floating ;
+the linker will automatically calculate an appropriate address for the section.
+Similarly, if
+.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.
+The format is described in
+.Xr rgblink 5 .
+They allow the user to place floating sections in the desired bank in the order specified in the script.
+This is useful if the sections can't be placed at an address manually because the size may change, but they have to be together.
+.Pp
+Section examples:
+.Bl -item
+.It
+.Bd -literal -offset indent
+SECTION "Cool Stuff",ROMX
+.Ed
+This switches to the section called
+.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:
+.Bd -literal -offset indent
+SECTION "Cool Stuff",ROMX[$4567]
+.Ed
+.It
+An example with a fixed bank:
+.Bd -literal -offset indent
+SECTION "Cool Stuff",ROMX[$4567],BANK[3]
+.Ed
+.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 "Cool Stuff",ROMX,BANK[7]
+.Ed
+.It
+Alignment examples:
+The first one could be useful for defining an OAM buffer to be DMA'd, since it must be aligned to 256 bytes.
+The second could also be appropriate for GBC HDMA, or for an optimized copy code that requires alignment.
+.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
+.Ed
+.El
+.Ss Section stack
+.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 override the section context at the point the file was included.
+.Ss RAM code
+Sometimes you want to have some code in RAM.
+But then you can't simply put it in a RAM section, you have to store it in ROM and copy it to RAM at some point.
+.Pp
+This means the code (or data) will not be stored in the place it gets executed.
+Luckily,
+.Ic LOAD
+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
+
+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
+.Ed
+.Pp
+A
+.Ic LOAD
+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 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
+.Sq RAMCode
+and
+.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
+You cannot nest
+.Ic LOAD
+blocks, nor can you change the current section within them.
+.Pp
+.Ic LOAD
+blocks can use the
+.Ic UNION
+or
+.Ic FRAGMENT
+modifiers, as described below.
+.Ss Unionized sections
+When you're tight on RAM, you may want to define overlapping static memory allocations, as explained in the
+.Sx Unions
+section.
+However, a
+.Ic UNION
+only works within a single file, so it can't be used e.g. to define temporary variables across several files, all of which use the same statically allocated memory.
+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 (i.e. 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
+If one section has been declared as unionized, all sections with the same name must be declared unionized as well.
+.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.
+.Ss Section fragments
+Section fragments are sections with a small twist: when several of the same name are encountered, they are concatenated instead of producing an error.
+This works within the same file (paralleling the behavior "plain" sections has in previous versions), but also across object files.
+To declare an section fragment, add a
+.Ic FRAGMENT
+keyword after the
+.Ic SECTION
+one; the declaration is otherwise not different.
+However, similarly to
+.Sx Unionized sections ,
+some rules must be followed:
+.Bl -bullet -offset indent
+.It
+If one section has been declared as fragment, all sections with the same name must be declared fragments as well.
+.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
+A section fragment may not be unionized; after all, that wouldn't make much sense.
+.El
+.Pp
+When RGBASM merges two fragments, the one encountered later is appended to the one encountered earlier.
+.Pp
+When RGBLINK merges two fragments, the one whose file was specified last is appended to the one whose file was specified first.
+For example, assuming
+.Ql bar.o ,
+.Ql baz.o ,
+and
+.Ql foo.o
+all contain a fragment with the same name, the command
+.Dl rgblink -o rom.gb baz.o foo.o bar.o
+would produce the fragment from
+.Ql baz.o
+first, followed by the one from
+.Ql foo.o ,
+and the one from
+.Ql bar.o
+last.
+.Sh SYMBOLS
+RGBDS supports several types of symbols:
+.Bl -hang
+.It Sy Label
+Numeric symbol designating a memory location.
+May or may not have a value known at assembly time.
+.It Sy Constant
+Numeric 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
+A text string that can be expanded later, similarly to a macro.
+.El
+.Pp
+Symbol names can contain ASCII letters, numbers, underscores
+.Sq _ ,
+hashes
+.Sq #
+and at signs
+.Sq @ .
+However, they must begin with either a letter or an underscore.
+Additionally, label names can contain up to a single dot
+.Ql \&. ,
+which may not be the first character.
+.Pp
+A symbol cannot have the same name as a reserved keyword.
+.Ss Labels
+One of the assembler's main tasks is to keep track of addresses for you, so you can work with meaningful names instead of
+.Dq magic
+numbers.
+Labels enable just that: a label ties a name to a specific location within a section.
+A label resolves to a bank and address, determined at the same time as its parent section's (see further in this section).
+.Pp
+A label is defined by writing its name at the beginning of a line, followed by one or two colons, without any whitespace between the label name and the colon(s).
+Declaring a label (global or local) with two colons
+.Ql ::
+will define and
+.Ic EXPORT
+it at the same time.
+(See
+.Sx Exporting and importing symbols
+below).
+When defining a local label, the colon can be omitted, and
+.Nm
+will act as if there was only one.
+.Pp
+A label is said to be
+.Em local
+if its name contains a dot
+.Ql \&. ;
+otherwise, it is said to be
+.Em global
+(not to be mistaken with
+.Dq exported ,
+explained in
+.Sx Exporting and importing symbols
+further below).
+More than one dot in label names is not allowed.
+.Pp
+For convenience, local labels can use a shorthand syntax: when a symbol name starting with a dot is found (for example, inside an expression, or when declaring a label), then the current
+.Dq label scope
+is implicitly prepended.
+.Pp
+Defining a global label sets it as the current
+.Dq label scope ,
+until the next global label definition, or the end of the current section.
+.Pp
+Here are some examples of label definitions:
+.Bd -literal -offset indent
+GlobalLabel:
+AnotherGlobal:
+\&.locallabel ;\ This defines "AnotherGlobal.locallabel"
+\&.another_local:
+AnotherGlobal.with_another_local:
+ThisWillBeExported:: ;\ Note the two colons
+ThisWillBeExported.too::
+.Ed
+.Pp
+In a numeric expression, a label evaluates to its address in memory.
+.Po To obtain its bank, use the
+.Ql BANK()
+function described in
+.Sx Other functions
+.Pc .
+For example, given the following,
+.Ql ld de, vPlayerTiles
+would be equivalent to
+.Ql ld de, $80C0
+assuming the section ends up at
+.Ad $80C0 :
+.Bd -literal -offset indent
+SECTION "Player tiles", VRAM
+PlayerTiles:
+ ds 6 * 16
+.end
+.Ed
+.Pp
+A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants.
+However, if the section in which the label is defined has a fixed base address, its value is known at assembly time.
+.Pp
+Also, while
+.Nm
+obviously can compute the difference between two labels if both are constant, it is also able to compute the difference between two non-constant labels if they both belong to the same section, such as
+.Ql PlayerTiles
+and
+.Ql PlayerTiles.end
+above.
+.Ss Anonymous labels
+Anonymous labels are useful for short blocks of code.
+They are defined like normal labels, but without a name before the colon.
+Anonymous labels are independent of label scoping, so defining one does not change the scoped label, and referencing one is not affected by the current scoped label.
+.Pp
+Anonymous labels are referenced using a colon
+.Ql \&:
+followed by pluses
+.Ql +
+or minuses
+.Ql - .
+Thus
+.Ic :+
+references the next one after the expression,
+.Ic :++
+the one after that;
+.Ic :-
+references the one before the expression;
+and so on.
+.Bd -literal -offset indent
+ ld hl, :++
+: ld a, [hli] ; referenced by "jr nz"
+ ldh [c], a
+ dec c
+ jr nz, :-
+ ret
+
+: ; referenced by "ld hl"
+ dw $7FFF, $1061, $03E0, $58A5
+.Ed
+.Ss Variables
+An equal sign
+.Ic =
+is used to define mutable numeric symbols.
+Unlike the other symbols described below, variables can be redefined.
+This is useful for internal symbols in macros, for counters, etc.
+.Bd -literal -offset indent
+DEF ARRAY_SIZE EQU 4
+DEF COUNT = 2
+DEF COUNT = 3
+DEF COUNT = ARRAY_SIZE + COUNT
+COUNT = COUNT*2
+;\ COUNT now has the value 14
+.Ed
+.Pp
+Note that colons
+.Ql \&:
+following the name are not allowed.
+.Pp
+Variables can be conveniently redefined by compound assignment operators like in C:
+.Bl -column -offset indent "*= /= %="
+.It Sy Operator Ta Sy Meaning
+.It Li += -= Ta Compound plus/minus
+.It Li *= /= %= Ta Compound multiply/divide/modulo
+.It Li <<= >>= Ta Compound shift left/right
+.It Li &= \&|= ^= Ta Compound and/or/xor
+.El
+.Pp
+Examples:
+.Bd -literal -offset indent
+DEF x = 10
+DEF x += 1 ; x == 11
+DEF y = x - 1 ; y == 10
+DEF y *= 2 ; y == 20
+DEF y >>= 1 ; y == 10
+DEF x ^= y ; x == 1
+.Ed
+.Ss Numeric constants
+.Ic EQU
+is used to define immutable numeric symbols.
+Unlike
+.Ic =
+above, constants defined this way cannot be redefined.
+These constants can be used for unchanging values such as properties of the hardware.
+.Bd -literal -offset indent
+def SCREEN_WIDTH equ 160 ;\ In pixels
+def SCREEN_HEIGHT equ 144
+.Ed
+.Pp
+Note that colons
+.Ql \&:
+following the name are not allowed.
+.Pp
+If you
+.Em really
+need to, the
+.Ic REDEF
+keyword will define or redefine a numeric constant symbol.
+(It can also be used for variables, although it's not necessary since they are mutable.)
+This can be used, for example, to update a constant using a macro, without making it mutable in general.
+.Bd -literal -offset indent
+ def NUM_ITEMS equ 0
+MACRO add_item
+ redef NUM_ITEMS equ NUM_ITEMS + 1
+ def ITEM_{02x:NUM_ITEMS} equ \[rs]1+ENDM
+ add_item 1
+ add_item 4
+ add_item 9
+ add_item 16
+ assert NUM_ITEMS == 4
+ assert ITEM_04 == 16
+.Ed
+.Ss Offset constants
+The RS group of commands is a handy way of defining structure offsets:
+.Bd -literal -offset indent
+ RSRESET
+DEF str_pStuff RW 1
+DEF str_tData RB 256
+DEF str_bCount RB 1
+DEF str_SIZEOF RB 0
+.Ed
+.Pp
+The example defines four constants as if by:
+.Bd -literal -offset indent
+DEF str_pStuff EQU 0
+DEF str_tData EQU 2
+DEF str_bCount EQU 258
+DEF str_SIZEOF EQU 259
+.Ed
+.Pp
+There are five commands in the RS group of commands:
+.Bl -column "RSSET constexpr"
+.It Sy Command Ta Sy Meaning
+.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 .
+.El
+.Pp
+If the argument to
+.Ic RB , RW ,
+or
+.Ic RL
+is omitted, it's assumed to be 1.
+.Pp
+Note that colons
+.Ql \&:
+following the name are not allowed.
+.Ss String constants
+.Ic EQUS
+is used to define string constant symbols.
+Wherever the assembler reads a string constant, it gets
+.Em expanded :
+the symbol's name is replaced with its contents.
+If you are familiar with C, you can think of it as similar to
+.Fd #define .
+This expansion is disabled in a few contexts:
+.Ql DEF(name) ,
+.Ql DEF name EQU/=/EQUS/etc ... ,
+.Ql PURGE name ,
+and
+.Ql MACRO name
+will not expand string constants in their names.
+.Bd -literal -offset indent
+DEF COUNTREG EQUS "[hl+]"
+ ld a,COUNTREG
+
+DEF PLAYER_NAME EQUS "\[rs]"John\[rs]""
+ db PLAYER_NAME
+.Ed
+.Pp
+This will be interpreted as:
+.Bd -literal -offset indent
+ ld a,[hl+]
+ db "John"
+.Ed
+.Pp
+String constants can also be used to define small one-line macros:
+.Bd -literal -offset indent
+DEF pusha EQUS "push af\[rs]npush bc\[rs]npush de\[rs]npush hl\[rs]n"
+.Ed
+.Pp
+Note that colons
+.Ql \&:
+following the name are not allowed.
+.Pp
+String constants can't be exported or imported.
+.Pp
+String constants, like numeric constants, cannot be redefined.
+However, the
+.Ic REDEF
+keyword will define or redefine a string constant symbol.
+For example:
+.Bd -literal -offset indent
+DEF s EQUS "Hello, "
+REDEF s EQUS "{s}world!"+; prints "Hello, world!"
+PRINTLN "{s}\n"+.Ed
+.Pp
+.Sy Important note :
+When a string constant is expanded, its expansion may contain another string constant, which will be expanded as well.
+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 .
+The same problem can occur if the expansion of a macro invokes another macro, recursively.
+.Pp
+The examples above for
+.Ql EQU ,
+.Ql = ,
+.Ql RB ,
+.Ql RW ,
+.Ql RL ,
+and
+.Ql EQUS
+all start with
+.Ql DEF .
+(A variable definition may start with
+.Ql REDEF
+instead, since they are redefinable.)
+You may use the older syntax without
+.Ql DEF ,
+but then the name being defined
+.Em must not
+have any whitespace before it;
+otherwise
+.Nm
+will treat it as a macro invocation.
+Furthermore, without the
+.Ql DEF
+keyword,
+string constants may be expanded for the name.
+This can lead to surprising results:
+.Bd -literal -offset indent
+X EQUS "Y"
+; this defines Y, not X!
+X EQU 42
+; prints "Y $2A"
+PRINTLN "{X} {Y}"+.Ed
+.Ss Macros
+One of the best features of an assembler is the ability to write macros for it.
+Macros can be called with arguments, and can react depending on input using
+.Ic IF
+constructs.
+.Bd -literal -offset indent
+MACRO MyMacro
+ ld a, 80
+ call MyFunc
+ENDM
+.Ed
+.Pp
+The example above defines
+.Ql MyMacro
+as a new macro.
+String constants are not expanded within the name of the macro.
+You may use the older syntax
+.Ql MyMacro: MACRO
+instead of
+.Ql MACRO MyMacro ,
+with a single colon
+.Ql \&:
+following the macro's name.
+With the older syntax, string constants may be expanded for the name.
+.Pp
+Macros can't be exported or imported.
+.Pp
+Plainly nesting macro definitions is not allowed, but this can be worked around using
+.Ic EQUS .
+So this won't work:
+.Bd -literal -offset indent
+MACRO outer
+ MACRO inner
+ PRINTLN "Hello!"
+ ENDM
+ENDM
+.Ed
+.Pp
+But this will:
+.Bd -literal -offset indent
+MACRO outer
+DEF definition EQUS "MACRO inner\[rs]nPRINTLN \[rs]"Hello!\[rs]"\[rs]nENDM"
+ definition
+ PURGE definition
+ENDM
+.Ed
+.Pp
+Macro arguments support all the escape sequences of strings, as well as
+.Ql \[rs],
+to escape commas, as well as
+.Ql \[rs](
+and
+.Ql \[rs])
+to escape parentheses, since those otherwise separate and enclose arguments, respectively.
+.Ss Exporting and importing symbols
+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
+.Nm
+finds a symbol it does not know about.
+.Pp
+The following will cause
+.Ar symbol1 , symbol2
+and so on to be accessible to other files during the link process:
+.Dl Ic EXPORT Ar symbol1 Bq , Ar symbol2 , No ...
+.Pp
+For example, if you have the following three files:
+.Pp
+.Ql a.asm :
+.Bd -literal -compact
+SECTION "a", WRAM0
+LabelA:
+.Ed
+.Pp
+.Ql b.asm :
+.Bd -literal -compact
+SECTION "b", WRAM0
+ExportedLabelB1::
+ExportedLabelB2:
+ EXPORT ExportedLabelB2
+.Ed
+.Pp
+.Ql c.asm :
+.Bd -literal -compact
+SECTION "C", ROM0[0]
+ dw LabelA
+ dw ExportedLabelB1
+ dw ExportedLabelB2
+.Ed
+.Pp
+Then
+.Ql c.asm
+can use
+.Ql ExportedLabelB1
+and
+.Ql ExportedLabelB2 ,
+but not
+.Ql LabelA ,
+so linking them together will fail:
+.Bd -literal
+$ rgbasm -o a.o a.asm
+$ rgbasm -o b.o b.asm
+$ rgbasm -o c.o c.asm
+$ rgblink a.o b.o c.o
+error: c.asm(2): Unknown symbol "LabelA"
+Linking failed with 1 error
+.Ed
+.Pp
+Note also that only exported symbols will appear in symbol and map files produced by
+.Xr rgblink 1 .
+.Ss Purging symbols
+.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,
+.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.
+When not sure, it's probably not safe to purge anything other than variables, numeric or string constants, or macros.
+.Bd -literal -offset indent
+DEF Kamikaze EQUS "I don't want to live anymore"
+DEF AOLer EQUS "Me too"
+ PURGE Kamikaze, AOLer
+.Ed
+.Pp
+String constants are not expanded within the symbol names.
+.Ss Predeclared symbols
+The following symbols are defined by the assembler:
+.Bl -column -offset indent "EQUS" "__ISO_8601_LOCAL__"
+.It Sy Name Ta Sy Type Ta Sy Contents
+.It Dv @ Ta Ic EQU Ta PC value (essentially, the current memory address)
+.It Dv _RS Ta Ic = Ta _RS Counter
+.It Dv _NARG Ta Ic EQU Ta Number of arguments passed to macro, updated by Ic SHIFT
+.It Dv __LINE__ Ta Ic EQU Ta The current line number
+.It Dv __FILE__ Ta Ic EQUS Ta The current filename
+.It Dv __DATE__ Ta Ic EQUS Ta Today's date
+.It Dv __TIME__ Ta Ic EQUS Ta The current time
+.It Dv __ISO_8601_LOCAL__ Ta Ic EQUS Ta ISO 8601 timestamp (local)
+.It Dv __ISO_8601_UTC__ Ta Ic EQUS Ta ISO 8601 timestamp (UTC)
+.It Dv __UTC_YEAR__ Ta Ic EQU Ta Today's year
+.It Dv __UTC_MONTH__ Ta Ic EQU Ta Today's month number, 1\[en]12
+.It Dv __UTC_DAY__ Ta Ic EQU Ta Today's day of the month, 1\[en]31
+.It Dv __UTC_HOUR__ Ta Ic EQU Ta Current hour, 0\[en]23
+.It Dv __UTC_MINUTE__ Ta Ic EQU Ta Current minute, 0\[en]59
+.It Dv __UTC_SECOND__ Ta Ic EQU Ta Current second, 0\[en]59
+.It Dv __RGBDS_MAJOR__ Ta Ic EQU Ta Major version number of RGBDS
+.It Dv __RGBDS_MINOR__ Ta Ic EQU Ta Minor version number of RGBDS
+.It Dv __RGBDS_PATCH__ Ta Ic EQU Ta Patch version number of RGBDS
+.It Dv __RGBDS_RC__ Ta Ic EQU Ta Release candidate ID of RGBDS, not defined for final releases
+.It Dv __RGBDS_VERSION__ Ta Ic EQUS Ta Version of RGBDS, as printed by Ql rgbasm --version
+.El
+.Pp
+The current time values will be taken from the
+.Dv SOURCE_DATE_EPOCH
+environment variable if that is defined as a UNIX timestamp.
+Refer to the spec at
+.Lk https://reproducible-builds.org/docs/source-date-epoch/ .
+.Sh DEFINING DATA
+.Ss Statically allocating space in RAM
+.Ic DS
+statically allocates a number of empty bytes.
+This is the preferred method of allocating space in a RAM section.
+You can also use
+.Ic DB , DW
+and
+.Ic DL
+without any arguments instead (see
+.Sx Defining constant data in ROM
+below).
+.Bd -literal -offset indent
+DS 42 ;\ Allocates 42 bytes
+.Ed
+.Pp
+Empty space in RAM sections will not be initialized.
+In ROM sections, it will be filled with the value passed to the
+.Fl p
+command-line option, except when using overlays with
+.Fl O .
+.Ss Defining constant data in ROM
+.Ic DB
+defines a list of bytes that will be stored in the final image.
+Ideal for tables and text.
+.Bd -literal -offset indent
+DB 1,2,3,4,"This is a string"
+.Ed
+.Pp
+Alternatively, you can use
+.Ic DW
+to store a list of words (16-bit) or
+.Ic DL
+to store a list of double-words/longs (32-bit).
+Both of these write their data in little-endian byte order; for example,
+.Ql dw $CAFE
+is equivalent to
+.Ql db $FE, $CA
+and not
+.Ql db $CA, $FE .
+.Pp
+Strings are handled a little specially: they first undergo charmap conversion (see
+.Sx Character maps ) ,
+then each resulting character is output individually.
+For example, under the default charmap, the following two lines are identical:
+.Bd -literal -offset indent
+DW "Hello!"
+DW "H", "e", "l", "l", "o", "!"
+.Ed
+.Pp
+If you do not want this special handling, enclose the string in parentheses.
+.Pp
+.Ic DS
+can also be used to fill a region of memory with some repeated values.
+For example:
+.Bd -literal -offset indent
+; outputs 3 bytes: $AA, $AA, $AA
+DS 3, $AA
+; outputs 7 bytes: $BB, $CC, $BB, $CC, $BB, $CC, $BB
+DS 7, $BB, $CC
+.Ed
+.Pp
+You can also use
+.Ic DB , DW
+and
+.Ic DL
+without arguments.
+This works exactly like
+.Ic DS 1 , DS 2
+and
+.Ic DS 4
+respectively.
+Consequently, no-argument
+.Ic DB , DW
+and
+.Ic DL
+can be used in a
+.Ic WRAM0
+/
+.Ic WRAMX
+/
+.Ic HRAM
+/
+.Ic VRAM
+/
+.Ic SRAM
+section.
+.Ss Including binary files
+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
+.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"
+.Ed
+.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.
+.Bd -literal -offset indent
+INCBIN "data.bin",78,256
+.Ed
+.Pp
+The length argument is optional.
+If only the start position is specified, the bytes from the start position until the end of the file will be included.
+.Ss Unions
+Unions allow multiple static 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
+keyword.
+.Ic NEXTU
+separates each block of allocations, and you may use it as many times within a union as necessary.
+.Bd -literal -offset indent
+ ; Let's say PC = $C0DE here
+ UNION
+ ; Here, PC = $C0DE
+Name: ds 8
+ ; PC = $C0E6
+Nickname: ds 8
+ ; PC = $C0EE
+ NEXTU
+ ; PC is back to $C0DE
+Health: dw
+ ; PC = $C0E0
+Something: ds 6
+ ; And so on
+Lives: db
+ NEXTU
+VideoBuffer: ds 19
+ ENDU
+.Ed
+.Pp
+In the example above,
+.Sq Name , Health , VideoBuffer
+all have the same value, as do
+.Sq Nickname
+and
+.Sq Lives .
+Thus, keep in mind that
+.Ic ld [Health], a
+is identical to
+.Ic ld [Name], a .
+.Pp
+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 Statically allocating space in RAM ) .
+.Sh THE MACRO LANGUAGE
+.Ss Invoking macros
+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
+MACRO LoopyMacro
+ 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
+MACRO LoopyMacro
+ 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
+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
+MACRO LoopyMacro
+ 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 you 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 constants, 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
+MACRO print_double
+ PRINTLN \[rs]1 * 2
+ENDM
+ print_double 1 + 2
+.Ed
+.Pp
+The
+.Ic PRINTLN
+statement will expand to
+.Ql PRINTLN 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
+MACRO PrintMacro1
+ PRINTLN STRCAT(\[rs]1)
+ENDM
+ PrintMacro1 "Hello "\[rs], \[rs]
+ "world"
+MACRO PrintMacro2
+ PRINT \[rs]1
+ENDM
+ PrintMacro2 STRCAT("Hello ", \[rs]+ "world\[rs]n")
+.Ed
+.Pp
+The comma in
+.Ql PrintMacro1
+needs to be escaped to prevent it from starting another macro argument.
+The comma in
+.Ql PrintMacro2
+does not need escaping because it is inside parentheses, similar to macro arguments in C.
+The backslash in
+.Ql \[rs]n
+also does not need escaping because string literals work as usual inside macro arguments.
+.Pp
+Since there are only nine digits, you can only access the first nine macro arguments like this.
+To use the rest, you need to put the multi-digit argument number in angle brackets, like
+.Ql \[rs]<10> .
+This bracketed syntax supports decimal numbers and numeric constant symbols.
+For example,
+.Ql \[rs]<_NARG>
+will get the last argument.
+.Pp
+Other macro arguments and symbol interpolations will be expanded inside the angle brackets.
+For example, if
+.Ql \[rs]1
+is
+.Ql 13 ,
+then
+.Ql \[rs]<\[rs]1>
+will expand to
+.Ql \[rs]<13> .
+Or if
+.Ql v10 = 42
+and
+.Ql x = 10 ,
+then
+.Ql \[rs]<v{d:x}>+will expand to
+.Ql \[rs]<42> .
+.Pp
+Another way to access more than nine macro arguments is the
+.Ic SHIFT
+command, a special command only available in macros.
+It will shift the arguments by one to the left, and decrease
+.Dv _NARG
+by 1.
+.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
+.Ic SHIFT
+can optionally be given an integer parameter, and will apply the above shifting that number of times.
+A negative parameter will shift the arguments in reverse.
+.Pp
+.Ic SHIFT
+is useful in
+.Ic REPT
+blocks to repeat the same commands with multiple arguments.
+.Ss Printing things during assembly
+The
+.Ic PRINT
+and
+.Ic PRINTLN
+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
+PRINT "Hello world!\[rs]n"
+PRINTLN "Hello world!"
+PRINT _NARG, " arguments\[rs]n"
+PRINTLN "sum: ", 2+3, " product: ", 2*3
+PRINTLN "Line #", __LINE__
+PRINTLN STRFMT("E = %f", 2.718)+.Ed
+.Bl -inset
+.It Ic PRINT
+prints out each of its comma-separated arguments.
+Numbers are printed as unsigned uppercase hexadecimal with a leading
+.Ic $ .
+For different formats, use
+.Ic STRFMT .
+.It Ic PRINTLN
+prints out each of its comma-separated arguments, if any, followed by a line feed
+.Pq Ql \[rs]n .
+.El
+.Ss Automatically repeating blocks of code
+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 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:
+.Bd -literal -offset indent
+REPT 4
+ add a,c
+ENDR
+.Ed
+.Pp
+You can also use
+.Ic REPT
+to generate tables on the fly:
+.Bd -literal -offset indent
+; Generate a 256-byte sine table with values in the range [0, 128]
+; (shifted and scaled from the range [-1.0, 1.0])
+ANGLE = 0.0
+ REPT 256
+ db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
+ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
+ ENDR
+.Ed
+.Pp
+As in macros, you can also use the escape sequence
+.Ic \[rs]@ .
+.Ic REPT
+blocks can be nested.
+.Pp
+A common pattern is to repeat a block for each value in some range.
+.Ic FOR
+is simpler than
+.Ic REPT
+for that purpose.
+Everything between
+.Ic FOR
+and the matching
+.Ic ENDR
+will be repeated for each value of a given symbol.
+String constants are not expanded within the symbol name.
+For example, this code will produce a table of squared values from 0 to 255:
+.Bd -literal -offset indent
+FOR N, 256
+ dw N * N
+ENDR
+.Ed
+.Pp
+It acts just as if you had done:
+.Bd -literal -offset indent
+N = 0
+ dw N * N
+N = 1
+ dw N * N
+N = 2
+ dw N * N
+; ...
+N = 255
+ dw N * N
+N = 256
+.Ed
+.Pp
+You can customize the range of
+.Ic FOR
+values, similarly to Python's
+.Ql range
+function:
+.Bl -column "FOR V, start, stop, step"
+.It Sy Code Ta Sy Range
+.It Ic FOR Ar V , stop Ta Ar V No increments from 0 to Ar stop
+.It Ic FOR Ar V , start , stop Ta Ar V No increments from Ar start No to Ar stop
+.It Ic FOR Ar V , start , stop , step Ta Ar V No goes from Ar start No to Ar stop No by Ar step
+.El
+.Pp
+The
+.Ic FOR
+value will be updated by
+.Ar step
+until it reaches or exceeds
+.Ar stop .
+For example:
+.Bd -literal -offset indent
+FOR V, 4, 25, 5
+ PRINT "{d:V} "+ENDR
+ PRINTLN "done {d:V}"+.Ed
+.Pp
+This will print:
+.Bd -literal -offset indent
+4 9 14 19 24 done 29
+.Ed
+.Pp
+Just like with
+.Ic REPT
+blocks, you can use the escape sequence
+.Ic \[rs]@
+inside of
+.Ic FOR
+blocks, and they can be nested.
+.Pp
+You can stop a repeating block with the
+.Ic BREAK
+command.
+A
+.Ic BREAK
+inside of a
+.Ic REPT
+or
+.Ic FOR
+block will interrupt the current iteration and not repeat any more.
+It will continue running code after the block's
+.Ic ENDR .
+For example:
+.Bd -literal -offset indent
+FOR V, 1, 100
+ PRINT "{d:V}"+ IF V == 5
+ PRINT " stop! "
+ BREAK
+ ENDC
+ PRINT ", "
+ENDR
+ PRINTLN "done {d:V}"+.Ed
+.Pp
+This will print:
+.Bd -literal -offset indent
+1, 2, 3, 4, 5 stop! done 5
+.Ed
+.Ss Aborting the assembly process
+.Ic FAIL
+and
+.Ic WARN
+can be used to print errors and warnings respectively during the assembly process.
+This is especially useful for macros that get an invalid argument.
+.Ic FAIL
+and
+.Ic WARN
+take a string as the only argument and they will print this string out as a normal error with a line number.
+.Pp
+.Ic FAIL
+stops assembling immediately while
+.Ic WARN
+shows the message but continues afterwards.
+.Pp
+If you need to ensure some assumption is correct when compiling, you can use
+.Ic ASSERT
+and
+.Ic STATIC_ASSERT .
+Syntax examples are given below:
+.Bd -literal -offset indent
+Function:
+ xor a
+ASSERT LOW(MyByte) == 0
+ ld h, HIGH(MyByte)
+ ld l, a
+ ld a, [hli]
+; You can also indent this!
+ ASSERT BANK(OtherFunction) == BANK(Function)
+ call OtherFunction
+; Lowercase also works
+ ld hl, FirstByte
+ ld a, [hli]
+assert FirstByte + 1 == SecondByte
+ ld b, [hl]
+ ret
+\&.end
+ ; If you specify one, a message will be printed
+ STATIC_ASSERT .end - Function < 256, "Function is too large!"
+.Ed
+.Pp
+First, the difference between
+.Ic ASSERT
+and
+.Ic STATIC_ASSERT
+is that the former is evaluated by RGBASM if it can, otherwise by RGBLINK; but the latter is only ever evaluated by RGBASM.
+If RGBASM cannot compute the value of the argument to
+.Ic STATIC_ASSERT ,
+it will produce an error.
+.Pp
+Second, as shown above, a string can be optionally added at the end, to give insight into what the assertion is checking.
+.Pp
+Finally, you can add one of
+.Ic WARN , FAIL
+or
+.Ic FATAL
+as the first optional argument to either
+.Ic ASSERT
+or
+.Ic STATIC_ASSERT .
+If the assertion fails,
+.Ic WARN
+will cause a simple warning (controlled by
+.Xr rgbasm 1
+flag
+.Fl Wassert )
+to be emitted;
+.Ic FAIL
+(the default) will cause a non-fatal error; and
+.Ic FATAL
+immediately aborts.
+.Ss Including other source files
+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 (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).
+.Bd -literal -offset indent
+ INCLUDE "irq.inc"
+.Ed
+.Ss Conditional assembling
+The four commands
+.Ic IF , ELIF , ELSE ,
+and
+.Ic ENDC
+let you have
+.Nm
+skip over parts of your code depending on a condition.
+This is a powerful feature commonly used in macros.
+.Bd -literal -offset indent
+IF NUM < 0
+ PRINTLN "NUM < 0"
+ELIF NUM == 0
+ PRINTLN "NUM == 0"
+ELSE
+ PRINTLN "NUM > 0"
+ENDC
+.Ed
+.Pp
+The
+.Ic ELIF
+(standing for "else if") and
+.Ic ELSE
+blocks are optional.
+.Ic IF
+/
+.Ic ELIF
+/
+.Ic ELSE
+/
+.Ic ENDC
+blocks can be nested.
+.Pp
+Note that if an
+.Ic ELSE
+block is found before an
+.Ic ELIF
+block, the
+.Ic ELIF
+block will be ignored.
+All
+.Ic ELIF
+blocks must go before the
+.Ic ELSE
+block.
+Also, if there is more than one
+.Ic ELSE
+block, all of them but the first one are ignored.
+.Sh MISCELLANEOUS
+.Ss Changing options while assembling
+.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.
+.Pq See Xr rgbasm 1 .
+.Pp
+.Ic OPT
+takes a comma-separated list of options as its argument:
+.Bd -literal -offset indent
+PUSHO
+ OPT g.oOX, Wdiv, L ; acts like command-line -g.oOX -Wdiv -L
+ DW `..ooOOXX ; uses the graphics constant characters from OPT g
+ PRINTLN $80000000/-1 ; prints a warning about division
+ LD [$FF88], A ; encoded as LD, not LDH
+POPO
+ DW `00112233 ; uses the default graphics constant characters
+ PRINTLN $80000000/-1 ; no warning by default
+ LD [$FF88], A ; optimized to use LDH by default
+.Ed
+.Pp
+The options that
+.Ic OPT
+can modify are currently:
+.Cm b , g , p , r , h , L ,
+and
+.Cm W .
+The Boolean flag options
+.Cm h
+and
+.Cm L
+can be negated as
+.Ql OPT !h
+and
+.Ql OPT !L
+to act like omitting them from the command-line.
+.Pp
+.Ic POPO
+and
+.Ic PUSHO
+provide the interface to the option stack.
+.Ic PUSHO
+will push the current set of options on the option stack.
+.Ic POPO
+can then later be used to restore them.
+Useful if you want to change some options in an include file and you don't want to destroy the options set by the program that included your file.
+The stack's number of entries is limited only by the amount of memory in your machine.
+.Ss Requesting alignment
+While
+.Ic ALIGN
+as presented in
+.Sx SECTIONS
+is often useful as-is, sometimes you instead want a particular piece of data (or code) in the middle of the section to be aligned.
+This is made easier through the use of mid-section
+.Ic ALIGN Ar align , offset .
+It will alter the section's attributes to ensure that the location the
+.Ic ALIGN
+directive is at, has its
+.Ar align
+lower bits equal to
+.Ar offset .
+.Pp
+If the constraint cannot be met (for example because the section is fixed at an incompatible address), an error is produced.
+Note that
+.Ic ALIGN Ar align
+is a shorthand for
+.Ic ALIGN Ar align , No 0 .
+.Sh SEE ALSO
+.Xr rgbasm 1 ,
+.Xr rgblink 1 ,
+.Xr rgblink 5 ,
+.Xr rgbds 5 ,
+.Xr rgbds 7 ,
+.Xr gbz80 7
+.Sh HISTORY
+.Nm
+was originally written by Carsten S\(/orensen as part of the ASMotor package,
+and was later packaged in RGBDS by Justin Lloyd.
+It is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .
--- /dev/null
+++ b/man/rgbds.5
@@ -1,0 +1,275 @@
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBDS 5
+.Os
+.Sh NAME
+.Nm rgbds
+.Nd object file format documentation
+.Sh DESCRIPTION
+This is the description of the object files used by
+.Xr rgbasm 1
+and
+.Xr rgblink 1 .
+.Em Please note that the specifications may change .
+This toolchain is in development and new features may require adding more information to the current format, or modifying some fields, which would break compatibility with older versions.
+.Sh FILE STRUCTURE
+The following types are used:
+.Pp
+.Ar LONG
+is a 32-bit integer stored in little-endian format.
+.Ar BYTE
+is an 8-bit integer.
+.Ar STRING
+is a 0-terminated string of
+.Ar BYTE .
+.Bd -literal
+; Header
+
+BYTE ID[4] ; "RGB9"
+LONG RevisionNumber ; The format's revision number this file uses.
+LONG NumberOfSymbols ; The number of symbols used in this file.
+LONG NumberOfSections ; The number of sections used in this file.
+
+; File info
+
+LONG NumberOfNodes ; The number of nodes contained in this file.
+
+REPT NumberOfNodes ; IMPORTANT NOTE: the nodes are actually written in
+ ; **reverse** order, meaning the node with ID 0 is
+ ; the last one in the file!
+
+ LONG ParentID ; ID of the parent node, -1 means this is the root.
+
+ LONG ParentLineNo ; Line at which the parent context was exited.
+ ; Meaningless on the root node.
+
+ BYTE Type ; 0 = REPT node
+ ; 1 = File node
+ ; 2 = Macro node
+
+ IF Type != 0 ; If the node is not a REPT...
+
+ STRING Name ; The node's name: either a file name, or macro name
+ ; prefixed by its definition file name.
+
+ ELSE ; If the node is a REPT, it also contains the iter
+ ; counts of all the parent REPTs.
+
+ LONG Depth ; Size of the array below.
+
+ LONG Iter[Depth] ; The number of REPT iterations by increasing depth.
+
+ ENDC
+
+ENDR
+
+; Symbols
+
+REPT NumberOfSymbols ; Number of symbols defined in this object file.
+
+ STRING Name ; The name of this symbol. Local symbols are stored
+ ; as "Scope.Symbol".
+
+ BYTE Type ; 0 = LOCAL symbol only used in this file.
+ ; 1 = IMPORT this symbol from elsewhere
+ ; 2 = EXPORT this symbol to other objects.
+
+ IF (Type & 0x7F) != 1 ; If symbol is defined in this object file.
+
+ LONG SourceFile ; File where the symbol is defined.
+
+ LONG LineNum ; Line number in the file where the symbol is defined.
+
+ LONG SectionID ; The section number (of this object file) in which
+ ; this symbol is defined. If it doesn't belong to any
+ ; specific section (like a constant), this field has
+ ; the value -1.
+
+ LONG Value ; The symbols value. It's the offset into that
+ ; symbol's section.
+
+ ENDC
+
+ENDR
+
+; Sections
+
+REPT NumberOfSections
+ STRING Name ; Name of the section
+
+ LONG Size ; Size in bytes of this section
+
+ BYTE Type ; 0 = WRAM0
+ ; 1 = VRAM
+ ; 2 = ROMX
+ ; 3 = ROM0
+ ; 4 = HRAM
+ ; 5 = WRAMX
+ ; 6 = SRAM
+ ; 7 = OAM
+ ; Bits 7 and 6 are independent from the above value:
+ ; Bit 7 encodes whether the section is unionized
+ ; Bit 6 encodes whether the section is a fragment
+ ; Bits 6 and 7 may not be both set at the same time!
+
+ LONG Org ; Address to fix this section at. -1 if the linker should
+ ; decide (floating address).
+
+ LONG Bank ; Bank to load this section into. -1 if the linker should
+ ; decide (floating bank). This field is only valid for ROMX,
+ ; VRAM, WRAMX and SRAM sections.
+
+ BYTE Align ; Alignment of this section, as N bits. 0 when not specified.
+
+ LONG Ofs ; Offset relative to the alignment specified above.
+ ; Must be below 1 << Align.
+
+ IF (Type == ROMX) || (Type == ROM0) ; Sections that can contain data.
+
+ BYTE Data[Size] ; Raw data of the section.
+
+ LONG NumberOfPatches ; Number of patches to apply.
+
+ REPT NumberOfPatches
+
+ LONG SourceFile ; ID of the source file node (for printing
+ ; error messages).
+
+ LONG LineNo ; Line at which the patch was created.
+
+ LONG Offset ; Offset into the section where patch should
+ ; be applied (in bytes).
+
+ LONG PCSectionID ; Index within the file of the section in which
+ ; PC is located.
+ ; This is usually the same section that the
+ ; patch should be applied into, except e.g.
+ ; with LOAD blocks.
+
+ LONG PCOffset ; PC's offset into the above section.
+ ; Used because the section may be floating, so
+ ; PC's value is not known to RGBASM.
+
+ BYTE Type ; 0 = BYTE patch.
+ ; 1 = little endian WORD patch.
+ ; 2 = little endian LONG patch.
+ ; 3 = JR offset value BYTE patch.
+
+ LONG RPNSize ; Size of the buffer with the RPN.
+ ; expression.
+
+ BYTE RPN[RPNSize] ; RPN expression. Definition below.
+
+ ENDR
+
+ ENDC
+
+ENDR
+
+; Assertions
+
+LONG NumberOfAssertions
+
+REPT NumberOfAssertions
+
+ LONG SourceFile ; ID of the source file node (for printing the failure).
+
+ LONG LineNo ; Line at which the assertion was created.
+
+ LONG Offset ; Offset into the section where the assertion is located.
+
+ LONG SectionID ; Index within the file of the section in which PC is
+ ; located, or -1 if defined outside a section.
+
+ LONG PCOffset ; PC's offset into the above section.
+ ; Used because the section may be floating, so PC's value
+ ; is not known to RGBASM.
+
+ BYTE Type ; 0 = Prints the message but allows linking to continue
+ ; 1 = Prints the message and evaluates other assertions,
+ ; but linking fails afterwards
+ ; 2 = Prints the message and immediately fails linking
+
+ LONG RPNSize ; Size of the RPN expression's buffer.
+
+ BYTE RPN[RPNSize] ; RPN expression, same as patches. Assert fails if == 0.
+
+ STRING Message ; A message displayed when the assert fails. If set to
+ ; the empty string, a generic message is printed instead.
+
+ENDR
+.Ed
+.Ss RPN DATA
+Expressions in the object file are stored as RPN.
+This is an expression of the form
+.Dq 2 5 + .
+This will first push the value
+.Do 2 Dc to the stack, then
+.Dq 5 .
+The
+.Do + Dc operator pops two arguments from the stack, adds them, and then pushes the result on the stack, effectively replacing the two top arguments with their sum.
+In the RGB format, RPN expressions are stored as
+.Ar BYTE Ns s
+with some bytes being special prefixes for integers and symbols.
+.Bl -column -offset indent "Sy String" "Sy String"
+.It Sy Value Ta Sy Meaning
+.It Li $00 Ta Li + operator
+.It Li $01 Ta Li - operator
+.It Li $02 Ta Li * operator
+.It Li $03 Ta Li / operator
+.It Li $04 Ta Li % operator
+.It Li $05 Ta Li unary -
+.It Li $06 Ta Li ** operator
+.It Li $10 Ta Li \&| operator
+.It Li $11 Ta Li & operator
+.It Li $12 Ta Li ^ operator
+.It Li $13 Ta Li unary ~
+.It Li $21 Ta Li && comparison
+.It Li $22 Ta Li || comparison
+.It Li $23 Ta Li unary \&!
+.It Li $30 Ta Li == comparison
+.It Li $31 Ta Li != comparison
+.It Li $32 Ta Li > comparison
+.It Li $33 Ta Li < comparison
+.It Li $34 Ta Li >= comparison
+.It Li $35 Ta Li <= comparison
+.It Li $40 Ta Li << operator
+.It Li $41 Ta Li >> operator
+.It Li $42 Ta Li >>> operator
+.It Li $50 Ta Li BANK(symbol) ,
+a
+.Ar LONG
+Symbol ID follows, where -1 means PC
+.It Li $51 Ta Li BANK(section_name) ,
+a null-terminated string follows.
+.It Li $52 Ta Li Current BANK()
+.It Li $53 Ta Li SIZEOF(section_name) ,
+a null-terminated string follows.
+.It Li $54 Ta Li STARTOF(section_name) ,
+a null-terminated string follows.
+.It Li $60 Ta Li HRAMCheck .
+Checks if the value is in HRAM, ANDs it with 0xFF.
+.It Li $61 Ta Li RSTCheck .
+Checks if the value is a RST vector, ORs it with 0xC7.
+.It Li $80 Ta Ar LONG
+integer follows.
+.It Li $81 Ta Ar LONG
+symbol ID follows.
+.El
+.Sh SEE ALSO
+.Xr rgbasm 1 ,
+.Xr rgblink 1 ,
+.Xr rgbds 7 ,
+.Xr gbz80 7
+.Sh HISTORY
+.Nm
+was originally written by Carsten S\(/orensen as part of the ASMotor package,
+and was later packaged in RGBDS by Justin Lloyd.
+It is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .
--- /dev/null
+++ b/man/rgbds.7
@@ -1,0 +1,57 @@
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBDS 7
+.Os
+.Sh NAME
+.Nm rgbds
+.Nd Rednex Game Boy Development System
+.Sh EXAMPLES
+To get a working ROM image from a single assembly source file:
+.Bd -literal -offset indent
+$ rgbasm \-o bar.o foo.asm
+$ rgblink \-o baz.gb bar.o
+$ rgbfix \-v \-p 0 baz.gb
+.Ed
+Or in a single command line:
+.Bd -literal -offset indent
+$ rgbasm \-o - foo.asm | rgblink \-o - - | rgbfix \-v \-p 0 - > baz.gb
+.Ed
+.Sh SEE ALSO
+.Xr rgbasm 1 ,
+.Xr rgbfix 1 ,
+.Xr rgblink 1 ,
+.Xr rgbds 5 ,
+.Xr gbz80 7
+.Sh HISTORY
+.Bl -item
+.It
+1997, Carsten S\(/orensen (AKA SurfSmurf) writes ASMotor as a general-purpose
+assembler/linker system for DOS/Win32.
+.It
+1999, Justin Lloyd (AKA Otaku no Zoku) adapts ASMotor to read and produce GBZ80
+assembly/machine code, and releases this version as RGBDS.
+.It
+2009, Vegard Nossum adapts the code to be more UNIX-like and releases this
+version as rgbds-linux on GitHub.
+.It
+2010, Anthony J. Bentley forks that repository.
+The fork becomes the reference implementation of rgbds.
+.It
+2017, Bentley's repository is moved to a neutral name.
+It is now maintained by a number of contributors at
+.Lk https://github.com/rednex/rgbds .
+.It
+2018, codebase relicensed under the MIT license.
+.It
+2020, repository is moved to the gbdev organisation, at
+.Lk https://github.com/gbdev/rgbds .
+The
+.Lk https://rgbds.gbdev.io
+website serving documentation and downloads is created.
+.El
--- /dev/null
+++ b/man/rgbfix.1
@@ -1,0 +1,243 @@
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBFIX 1
+.Os
+.Sh NAME
+.Nm rgbfix
+.Nd Game Boy header utility and checksum fixer
+.Sh SYNOPSIS
+.Nm
+.Op Fl jOsVv
+.Op Fl C | c
+.Op Fl f Ar fix_spec
+.Op Fl i Ar game_id
+.Op Fl k Ar licensee_str
+.Op Fl l Ar licensee_id
+.Op Fl m Ar mbc_type
+.Op Fl n Ar rom_version
+.Op Fl p Ar pad_value
+.Op Fl r Ar ram_size
+.Op Fl t Ar title_str
+.Op Ar
+.Sh DESCRIPTION
+The
+.Nm
+program changes headers of Game Boy ROM images, typically generated by
+.Xr rgblink 1 ,
+though it will work with
+.Em any
+Game Boy ROM.
+It also performs other correctness operations, such as padding.
+.Nm
+only changes the fields for which it has values specified.
+Developers are advised to fill those fields with 0x00 bytes in their source code before running
+.Nm ,
+and to have already populated whichever fields they don't specify using
+.Nm .
+.Pp
+Note that options can be abbreviated as long as the abbreviation is unambiguous:
+.Fl Fl color-o
+is
+.Fl Fl color-only ,
+but
+.Fl Fl color
+is invalid because it could also be
+.Fl Fl color-compatible .
+Options later in the command line override those set earlier.
+Accepted options are as follows:
+.Bl -tag -width Ds
+.It Fl C , Fl Fl color-only
+Set the Game Boy Color\(enonly flag
+.Pq Ad 0x143
+to 0xC0.
+This overrides
+.Fl c
+if it was set prior.
+.It Fl c , Fl Fl color-compatible
+Set the Game Boy Color\(encompatible flag:
+.Pq Ad 0x143
+to 0x80.
+This overrides
+.Fl c
+if it was set prior.
+.It Fl f Ar fix_spec , Fl Fl fix-spec Ar fix_spec
+Fix certain header values that the Game Boy checks for correctness.
+Alternatively, intentionally trash these values by writing their binary inverse instead.
+.Ar fix_spec
+is a string containing any combination of the following characters:
+.Pp
+.Bl -tag -compact -width xx
+.It Cm l
+Fix the Nintendo logo
+.Pq Ad 0x104 Ns \(en Ns Ad 0x133 .
+.It Cm L
+Trash the Nintendo logo.
+.It Cm h
+Fix the header checksum
+.Pq Ad 0x14D .
+.It Cm H
+Trash the header checksum.
+.It Cm g
+Fix the global checksum
+.Pq Ad 0x14E Ns \(en Ns Ad 0x14F .
+.It Cm G
+Trash the global checksum.
+.El
+.It Fl i Ar game_id , Fl Fl game-id Ar game_id
+Set the game ID string
+.Pq Ad 0x13F Ns \(en Ns Ad 0x142
+to a given string.
+If it's longer than 4 chars, it will be truncated, and a warning emitted.
+.It Fl j , Fl Fl non-japanese
+Set the non-Japanese region flag
+.Pq Ad 0x14A
+to 0x01.
+.It Fl k Ar licensee_str , Fl Fl new-licensee Ar licensee_str
+Set the new licensee string
+.Pq Ad 0x144 Ns \(en Ns Ad 0x145
+to a given string.
+If it's longer than 2 chars, it will be truncated, and a warning emitted.
+.It Fl l Ar licensee_id , Fl Fl old-licensee Ar licensee_id
+Set the old licensee code
+.Pq Ad 0x14B
+to a given value from 0 to 0xFF.
+This value is deprecated and should be set to 0x33 in all new software.
+.It Fl m Ar mbc_type , Fl Fl mbc-type Ar mbc_type
+Set the MBC type
+.Pq Ad 0x147
+to a given value from 0 to 0xFF.
+.Pp
+This value may also be an MBC name.
+The list of accepted names can be obtained by passing
+.Ql Cm help
+as the argument.
+Any amount of whitespace (space and tabs) is allowed around plus signs, and the order of "components" is free, as long as the MBC name is first.
+There are special considerations to take for the TPP1 mapper; see the
+.Sx TPP1
+section below.
+.It Fl n Ar rom_version , Fl Fl rom-version Ar rom_version
+Set the ROM version
+.Pq Ad 0x14C
+to a given value from 0 to 0xFF.
+.It Fl O , Fl Fl overwrite
+Allow overwriting different non-zero bytes in the header without a warning being emitted.
+.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
+Pad the ROM image to a valid size with a given pad value from 0 to 255 (0xFF).
+.Nm
+will automatically pick a size from 32 KiB, 64 KiB, 128 KiB, ..., 8192 KiB.
+The cartridge size byte
+.Pq Ad 0x148
+will be changed to reflect this new size.
+The recommended padding value is 0xFF, to speed up writing the ROM to flash chips, and to avoid "nop slides" into VRAM.
+.It Fl r Ar ram_size , Fl Fl ram-size Ar ram_size
+Set the RAM size
+.Pq Ad 0x149
+to a given value from 0 to 0xFF.
+.It Fl s , Fl Fl sgb-compatible
+Set the SGB flag
+.Pq Ad 0x146
+to 0x03.
+This flag will be ignored by the SGB unless the old licensee code is 0x33!
+If this is given as well as
+.Fl l ,
+but is not set to 0x33, a warning will be printed.
+.It Fl t Ar title , Fl Fl title Ar title
+Set the title string
+.Pq Ad 0x134 Ns \(en Ns Ad 0x143
+to a given string.
+If the title is longer than the max length, it will be truncated, and a warning emitted.
+The max length is 11 characters if the game ID
+.Pq Fl i
+is specified, 15 characters if the CGB flag
+.Fl ( c
+or
+.Fl C )
+is specified but the game ID is not, and 16 characters otherwise.
+.It Fl V , Fl Fl version
+Print the version of the program and exit.
+.It Fl v , Fl Fl validate
+Equivalent to
+.Fl f Cm lhg .
+.El
+.Sh EXAMPLES
+Most values in the ROM header do not matter to the actual console, and most are seldom useful anyway.
+The bare minimum requirements for a workable program are the header checksum, the Nintendo logo, and (if needed) the CGB/SGB flags.
+It is a good idea to pad the image to a valid size as well
+.Pq Do valid Dc meaning a power of 2, times 32 KiB .
+.Pp
+The following will make a plain, non-color Game Boy game without checking for
+a valid size:
+.Pp
+.D1 $ rgbfix -v foo.gb
+.Pp
+The following will make a SGB-enabled, color-enabled game with a title of
+.Dq foobar ,
+and pad it to a valid size.
+.Pq The Game Boy itself does not use the title, but some emulators or ROM managers do.
+.Pp
+.D1 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
+.Pp
+The following will duplicate the header of the game
+.Dq Survival Kids ,
+sans global checksum:
+.Pp
+.D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \
+SurvivalKids.gbc
+.Sh TPP1
+TPP1 is a homebrew mapper designed as a functional superset of the common traditional MBCs, allowing larger ROM and RAM sizes combined with other hardware features.
+Its specification, as well as more resources, can be found online at
+.Lk https://github.com/TwitchPlaysPokemon/tpp1 .
+.Ss MBC name
+The MBC name for TPP1 is more complex than standard mappers.
+It must be followed with the revision number, of the form
+.Ql major.minor ,
+where both
+.Ql major
+and
+.Ql minor
+are decimal, 8-bit integers.
+There may be any amount of spaces or underscores between
+.Ql TPP1
+and the revision number.
+.Nm
+only supports 1.x revisions, and will reject everything else.
+.Pp
+Like other mappers, the name may be followed with a list of optional,
+.Ql + Ns
+-separated features; however,
+.Ql RAM
+should not be specified, as the TPP1 mapper implicitly requests RAM if a non-zero RAM size is specified.
+Therefore,
+.Nm
+will ignore the
+.Ql RAM
+feature on a TPP1 mapper with a warning.
+.Ss Special considerations
+TPP1 overwrites the byte at
+.Ad 0x14A ,
+usually indicating the region destination
+.Pq see Fl j ,
+with one of its three identification bytes.
+Therefore,
+.Nm
+will warn about and ignore
+.Fl j
+if used in combination with TPP1.
+.Sh BUGS
+Please report bugs on
+.Lk https://github.com/gbdev/rgbds/issues GitHub .
+.Sh SEE ALSO
+.Xr rgbasm 1 ,
+.Xr rgblink 1 ,
+.Xr rgbds 7
+.Sh HISTORY
+.Nm
+was originally released by Carsten S\(/orensen as a standalone program called gbfix, and was later packaged in RGBDS by Justin Lloyd.
+It is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .
--- /dev/null
+++ b/man/rgbgfx.1
@@ -1,0 +1,160 @@
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2013-2021, stag019 and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBGFX 1
+.Os
+.Sh NAME
+.Nm rgbgfx
+.Nd Game Boy graphics converter
+.Sh SYNOPSIS
+.Nm
+.Op Fl CDhmuVv
+.Op Fl f | Fl F
+.Op Fl a Ar attrmap | Fl A
+.Op Fl d Ar depth
+.Op Fl o Ar out_file
+.Op Fl p Ar pal_file | Fl P
+.Op Fl t Ar tilemap | Fl T
+.Op Fl x Ar tiles
+.Ar file
+.Sh DESCRIPTION
+The
+.Nm
+program converts PNG images into the Nintendo Game Boy's planar tile format.
+.Pp
+The resulting colors and their palette indices are determined differently depending on the input PNG file:
+.Bl -dash -width Ds
+.It
+If the file has an embedded palette, that palette's color and order are used.
+.It
+If not, and the image only contains shades of gray, rgbgfx maps them to the indices appropriate for each shade.
+Any undetermined indices are set to respective default shades of gray.
+For example: if the bit depth is 2 and the image contains light gray and black, they become the second and fourth colors, and the first and third colors get set to default white and dark gray.
+If the image has multiple shades that map to the same index, the palette is instead determined as if the image had color.
+.It
+If the image has color (or the grayscale method failed), the colors are sorted from lightest to darkest.
+.El
+.Pp
+The input image may not contain more colors than the selected bit depth allows.
+Transparent pixels are set to palette index 0.
+.Sh ARGUMENTS
+Note that options can be abbreviated as long as the abbreviation is unambiguous:
+.Fl Fl verb
+is
+.Fl Fl verbose ,
+but
+.Fl Fl ver
+is invalid because it could also be
+.Fl Fl version .
+The arguments are as follows:
+.Bl -tag -width Ds
+.It Fl a Ar attrmap , Fl Fl attr-map Ar attrmap
+Generate a file of tile mirroring attributes for OAM or (CGB-only) background tiles.
+For each tile in the input file, a byte is written representing the dimensions that the associated tile in the output file should be mirrored.
+Useful in combination with
+.Fl m
+to keep track the mirror direction of mirrored duplicate tiles.
+.It Fl A , Fl Fl output-attr-map
+Same as
+.Fl a ,
+but the attrmap file output name is made by taking the input filename, removing the file extension, and appending
+.Pa .attrmap .
+.It Fl C , Fl Fl color-curve
+Use the color curve of the Game Boy Color when generating palettes.
+.It Fl D , Fl Fl debug
+Debug features are enabled.
+.It Fl d Ar depth , Fl Fl depth Ar depth
+The bit depth of the output image (either 1 or 2).
+By default, the bit depth is 2 (two bits per pixel).
+.It Fl f , Fl Fl fix
+Fix the input PNG file to be a correctly indexed image.
+.It Fl F , Fl Fl fix-and-save
+Same as
+.Fl f ,
+but additionally, the supplied command line parameters are saved within the PNG and will be loaded and automatically used next time.
+.It Fl h , Fl Fl horizontal
+Lay out tiles in column-major order (column by column), instead of the default row-major order (line by line).
+Especially useful for "8x16" OBJ mode, if the input image is 16 pixels tall.
+.It Fl m , Fl Fl mirror-tiles
+Truncate tiles by checking for tiles that are mirrored versions of others and omitting these from the output file.
+Useful with tilemaps and attrmaps together to keep track of the duplicated tiles and the dimension mirrored.
+Tiles are checked for horizontal, vertical, and horizontal-vertical mirroring.
+Implies
+.Fl u .
+.It Fl o Ar out_file , Fl Fl output Ar out_file
+The name of the output file.
+.It Fl p Ar pal_file , Fl Fl palette Ar pal_file
+Output the image's palette in standard GBC palette format: bytes (8 bytes for two bits per pixel, 4 bytes for one bit per pixel) containing the RGB15 values in little-endian byte order.
+If the palette contains too few colors, the remaining entries are set to black.
+.It Fl P , Fl Fl output-palette
+Same as
+.Fl p ,
+but the palette file output name is made by taking the input PNG file's filename, removing the file extension, and appending
+.Pa .pal .
+.It Fl t Ar tilemap , Fl Fl tilemap Ar tilemap
+Generate a file of tile indices.
+For each tile in the input file, a byte is written representing the index of the associated tile in the output file.
+Useful in combination with
+.Fl u
+or
+.Fl m
+to keep track of duplicate tiles.
+.It Fl T , Fl Fl output-tilemap
+Same as
+.Fl t ,
+but the tilemap file output name is made by taking the input filename, removing the file extension, and appending
+.Pa .tilemap .
+.It Fl u , Fl Fl unique-tiles
+Truncate tiles by checking for tiles that are exact duplicates of others and omitting these from the output file.
+Useful with tilemaps to keep track of the duplicated tiles.
+.It Fl V , Fl Fl version
+Print the version of the program and exit.
+.It Fl v , Fl Fl verbose
+Verbose.
+Print errors when the command line parameters and the parameters in the PNG file don't match.
+.It Fl x Ar tiles , Fl Fl trim-end Ar tiles
+Trim the end of the output file by this many tiles.
+.El
+.Sh EXAMPLES
+The following will take a PNG file with a bit depth of 1, 2, or 8, and output planar 2bpp data:
+.Pp
+.D1 $ rgbgfx -o out.2bpp in.png
+.Pp
+The following creates a planar 2bpp file with only unique tiles, and its tilemap
+.Pa out.tilemap :
+.Pp
+.D1 $ rgbgfx -T -u -o out.2bpp in.png
+.Pp
+The following creates a planar 2bpp file with only unique tiles
+.Pa accounting for tile mirroring
+and its associated tilemap
+.Pa out.tilemap
+and attrmap
+.Pa out.attrmap :
+.Pp
+.D1 $ rgbgfx -A -T -m -o out.2bpp in.png
+.Pp
+The following will do nothing:
+.Pp
+.D1 $ rgbgfx in.png
+.Sh BUGS
+Please report bugs on
+.Lk https://github.com/gbdev/rgbds/issues GitHub .
+.Sh SEE ALSO
+.Xr rgbds 7 ,
+.Xr rgbasm 1 ,
+.Xr rgblink 1 ,
+.Xr rgbfix 1 ,
+.Xr gbz80 7
+.Sh HISTORY
+.Nm
+was created by
+.An stag019
+to be included in RGBDS.
+It is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .
--- /dev/null
+++ b/man/rgblink.1
@@ -1,0 +1,205 @@
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBLINK 1
+.Os
+.Sh NAME
+.Nm rgblink
+.Nd Game Boy linker
+.Sh SYNOPSIS
+.Nm
+.Op Fl dtVvwx
+.Op Fl l Ar linker_script
+.Op Fl m Ar map_file
+.Op Fl n Ar sym_file
+.Op Fl O Ar overlay_file
+.Op Fl o Ar out_file
+.Op Fl p Ar pad_value
+.Op Fl S Ar spec
+.Op Fl s Ar symbol
+.Ar
+.Sh DESCRIPTION
+The
+.Nm
+program links RGB object files, typically created by
+.Xr rgbasm 1 ,
+into a single Game Boy ROM file.
+The format is documented in
+.Xr rgbds 5 .
+.Pp
+ROM0 sections are placed in the first 16 KiB of the output ROM, and ROMX sections are placed in any 16 KiB
+.Dq bank
+except the first.
+If your ROM will only be 32 KiB, you can use the
+.Fl t
+option to change this.
+.Pp
+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
+.Fl w
+option to change this.
+.Pp
+Also, if your ROM is designed for a monochrome Game Boy, you can make sure that you don't use any incompatible section by using the
+.Fl d
+option, which implies
+.Fl w
+but also prohibits the use of banked VRAM.
+.Pp
+Note that options can be abbreviated as long as the abbreviation is unambiguous:
+.Fl Fl verb
+is
+.Fl Fl verbose ,
+but
+.Fl Fl ver
+is invalid because it could also be
+.Fl Fl version .
+The arguments are as follows:
+.Bl -tag -width Ds
+.It Fl d , Fl Fl dmg
+Enable DMG mode.
+Prohibit the use of sections that doesn't exist on a DMG, such as VRAM bank 1.
+This option automatically enables
+.Fl w .
+.It Fl l Ar linker_script , Fl Fl linkerscript Ar linker_script
+Specify a linker script file that tells the linker how sections must be placed in the ROM.
+The attributes assigned in the linker script must be consistent with any assigned in the code.
+See
+.Xr rgblink 5
+for more information about the linker script format.
+.It Fl m Ar map_file , Fl Fl map Ar map_file
+Write a map file to the given filename, listing how sections and symbols were assigned.
+.It Fl n Ar sym_file , Fl Fl sym Ar sym_file
+Write a symbol file to the given filename, listing the address of all exported symbols.
+Several external programs can use this information, for example to help debugging ROMs.
+.It Fl O Ar overlay_file , Fl Fl overlay Ar overlay_file
+If specified, sections will be overlaid "on top" of the provided ROM image.
+In that case, all sections must be fixed.
+This may be used to patch an existing binary.
+.It Fl o Ar out_file , Fl Fl output Ar out_file
+Write the ROM image to the given file.
+.It Fl p Ar pad_value , Fl Fl pad Ar pad_value
+When inserting padding between sections, pad with this value.
+Has no effect if
+.Fl O
+is specified.
+The default is 0.
+.It Fl S Ar spec , Fl Fl scramble Ar spec
+Enables a different
+.Dq scrambling
+algorithm for placing sections.
+See
+.Sx Scrambling algorithm
+below for an explanation and a description of
+.Ar spec .
+.It Fl s Ar symbol , Fl Fl smart Ar symbol
+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 Fl tiny
+Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to ROM.
+ROMX sections that are fixed to a bank other than 1 become errors, other ROMX sections are treated as ROM0.
+Useful for ROMs that fit in 32 KiB.
+.It Fl V , Fl Fl version
+Print the version of the program and exit.
+.It Fl v , Fl Fl verbose
+Verbose: enable printing more information to standard error.
+.It Fl w , Fl Fl wramx
+Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to WRAM.
+WRAMX sections that are fixed to a bank other than 1 become errors, other WRAMX sections are treated as WRAM0.
+.It Fl x , Fl Fl nopad
+Disables padding the end of the final file.
+This option automatically enables
+.Fl t .
+You can use this when not not making a ROM.
+When making a ROM, be careful that not using this is not a replacement for
+.Xr rgbfix 1 Ap s Fl p
+option!
+.El
+.Ss Scrambling algorithm
+The default section placement algorithm tries to minimize the number of banks used;
+.Dq scrambling
+instead places sections into a given pool of banks, trying to minimize the number of sections sharing a given bank.
+This is useful to catch broken bank assumptions, such as expecting two different sections to land in the same bank (that is not guaranteed unless both are manually assigned the same bank number).
+.Pp
+A scrambling spec is a comma-separated list of region specs.
+A trailing comma is allowed, as well as whitespace between all specs and their components.
+Each region spec has the following form:
+.D1 Ar region Ns Op = Ns Ar size
+.Ar region
+must be one of the following (case-insensitive), while
+.Ar size
+must be a positive decimal integer between 1 and the corresponding maximum.
+Certain regions allow omitting the size, in which case it defaults to its max value.
+.Bl -column "Region name" "Max value" "Size optional"
+Region name Ta Max size Ta Size optional
+.Cm romx Ta 65535 Ta \&No
+.Cm sram Ta 255 Ta \&No
+.Cm wramx Ta 7 Ta Yes
+.El
+.Pp
+A
+.Ar size
+of 0 disables scrambling for that region.
+.Pp
+For example,
+.Ql romx=64,wramx=4
+will scramble
+.Ic ROMX
+sections among ROM banks 1 to 64,
+.Ic WRAMX
+sections among RAM banks 1 to 4, and will not scramble
+.Ic SRAM
+sections.
+.Pp
+Later region specs override earlier ones; for example,
+.Ql romx=42, Romx=0
+disables scrambling for
+.Cm romx .
+.Pp
+.Cm wramx
+scrambling is silently ignored if
+.Fl w
+is passed (including if implied by
+.Fl d ) ,
+as
+.Ic WRAMX
+sections will be treated as
+.Ic WRAM0 .
+.Sh EXAMPLES
+All you need for a basic ROM is an object file, which can be made into a ROM image like so:
+.Pp
+.Dl $ rgblink -o bar.gb foo.o
+.Pp
+The resulting
+.Ar bar.gb
+will not have correct checksums (unless you put them in the assembly source).
+You should use
+.Xr rgbfix 1
+to fix these so that the program will actually run in a Game Boy:
+.Pp
+.Dl $ rgbfix -v bar.gb
+.Pp
+Here is a more complete example:
+.Pp
+.Dl $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o
+.Sh BUGS
+Please report bugs on
+.Lk https://github.com/gbdev/rgbds/issues GitHub .
+.Sh SEE ALSO
+.Xr rgbasm 1 ,
+.Xr rgblink 5 ,
+.Xr rgbfix 1 ,
+.Xr rgbds 5 ,
+.Xr rgbds 7
+.Sh HISTORY
+.Nm
+was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
+It is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .
--- /dev/null
+++ b/man/rgblink.5
@@ -1,0 +1,90 @@
+.\"
+.\" This file is part of RGBDS.
+.\"
+.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
+.\"
+.\" SPDX-License-Identifier: MIT
+.\"
+.Dd March 28, 2021
+.Dt RGBLINK 5
+.Os
+.Sh NAME
+.Nm rgblink
+.Nd linker script file format
+.Sh DESCRIPTION
+The linker script is an external file that allows the user to specify the order of sections at link time and in a centralized manner.
+.Pp
+A linker script consists on a series of banks followed by a list of sections and, optionally, commands.
+They can be lowercase or uppercase, it is ignored.
+Any line can contain a comment starting with
+.Ql \&;
+that ends at the end of the line:
+.Bd -literal -offset indent
+ROMX $F ; This is a comment
+ "Functions to read array"
+ ALIGN 8
+ "Array aligned to 256 bytes"
+
+WRAMX 2
+ "Some variables"
+.Ed
+.Pp
+Numbers can be in decimal or hexadecimal format
+.Pq the prefix is Ql $ .
+It is an error if any section name or command is found before setting a bank.
+.Pp
+Files can be included by using the
+.Ic INCLUDE
+keyword, followed by a string with the path of the file that has to be included.
+.Pp
+The possible bank types are:
+.Cm ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM
+and
+.Cm HRAM .
+Unless there is a single bank, which can occur with types
+.Cm ROMX , VRAM , SRAM
+and
+.Cm WRAMX ,
+it is needed to specify a bank number after the type.
+.Pp
+When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
+If the linker script switches to a different bank and then comes back to a previous one, it will continue from the last address that was used.
+.Pp
+The only two commands are
+.Ic ORG
+and
+.Ic ALIGN :
+.Bl -bullet
+.It
+.Ic ORG
+sets the address in which new sections will be placed.
+It can not be lower than the current address.
+.It
+.Ic ALIGN
+will increase the address until it is aligned to the specified boundary
+.Po it tries to set to 0 the number of bits specified after the command:
+.Ql ALIGN 8
+will align to $100
+.Pc .
+.El
+.Pp
+.Sy Note:
+The bank, alignment, address and type of sections can be specified both in the source code and in the linker script.
+For a section to be able to be placed with the linker script, the bank, address and alignment must be left unassigned in the source code or be compatible with what is specified in the linker script.
+For example,
+.Ql ALIGN[8]
+in the source code is compatible with
+.Ql ORG $F00
+in the linker script.
+.Sh SEE ALSO
+.Xr rgbasm 1 ,
+.Xr rgblink 1 ,
+.Xr rgbfix 1 ,
+.Xr rgbds 5 ,
+.Xr rgbds 7
+.Sh HISTORY
+.Nm
+was originally written by Carsten S\(/orensen as part of the ASMotor package,
+and was later packaged in RGBDS by Justin Lloyd.
+It is now maintained by a number of contributors at
+.Lk https://github.com/gbdev/rgbds .
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -97,22 +97,6 @@
install(TARGETS rgb${PROG} RUNTIME DESTINATION bin)endforeach()
-set(MANDIR "share/man")
-set(man1 "asm/rgbasm.1"
- "fix/rgbfix.1"
- "gfx/rgbgfx.1"
- "link/rgblink.1")
-set(man5 "asm/rgbasm.5"
- "link/rgblink.5"
- "rgbds.5")
-set(man7 "gbz80.7"
- "rgbds.7")
-
-foreach(SECTION "man1" "man5" "man7")
- set(DEST "${MANDIR}/${SECTION}")- install(FILES ${${SECTION}} DESTINATION ${DEST})-endforeach()
-
if(LIBPNG_FOUND) # pkg-config
target_include_directories(rgbgfx PRIVATE ${LIBPNG_INCLUDE_DIRS}) target_link_directories(rgbgfx PRIVATE ${LIBPNG_LIBRARY_DIRS})--- a/src/asm/rgbasm.1
+++ /dev/null
@@ -1,315 +1,0 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.Dd March 28, 2021
-.Dt RGBASM 1
-.Os
-.Sh NAME
-.Nm rgbasm
-.Nd Game Boy assembler
-.Sh SYNOPSIS
-.Nm
-.Op Fl EhLVvw
-.Op Fl b Ar chars
-.Op Fl D Ar name Ns Op = Ns Ar value
-.Op Fl g Ar chars
-.Op Fl i Ar path
-.Op Fl M Ar depend_file
-.Op Fl MG
-.Op Fl MP
-.Op Fl MT Ar target_file
-.Op Fl MQ Ar target_file
-.Op Fl o Ar out_file
-.Op Fl p Ar pad_value
-.Op Fl r Ar recursion_depth
-.Op Fl W Ar warning
-.Ar
-.Sh DESCRIPTION
-The
-.Nm
-program creates an RGB object file from an assembly source file.
-The input
-.Ar file
-can be a file path, or
-.Cm \-
-denoting
-.Cm stdin .
-.Pp
-Note that options can be abbreviated as long as the abbreviation is unambiguous:
-.Fl Fl verb
-is
-.Fl Fl verbose ,
-but
-.Fl Fl ver
-is invalid because it could also be
-.Fl Fl version .
-The arguments are as follows:
-.Bl -tag -width Ds
-.It Fl b Ar chars , Fl Fl binary-digits Ar chars
-Change the two characters used for binary constants.
-The defaults are 01.
-.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 \(dq Ns Ar value Ns \(dq
-in code, or
-.Ql Ar name Ic EQUS \(dq1\(dq
-if
-.Ar value
-is not specified.
-.It Fl E , Fl Fl export-all
-Export all labels, including unreferenced and local labels.
-.It Fl g Ar chars , Fl Fl gfx-chars Ar chars
-Change the four characters used for gfx constants.
-The defaults are 0123.
-.It Fl h , Fl Fl halt-without-nop
-By default,
-.Nm
-inserts a
-.Ic nop
-instruction immediately after any
-.Ic halt
-instruction.
-The
-.Fl h
-option disables this behavior.
-.It Fl i Ar path , Fl Fl include Ar path
-Add an include path.
-.It Fl L , Fl Fl preserve-ld
-Disable the optimization that turns loads of the form
-.Ic LD [$FF00+n8],A
-into the opcode
-.Ic LDH [$FF00+n8],A
-in order to have full control of the result in the final ROM.
-.It Fl M Ar depend_file , Fl Fl dependfile Ar depend_file
-.Xr make 1
-dependencies to
-.Ar depend_file .
-.It Fl MG
-To be used in conjunction with
-.Fl M .
-This makes
-.Nm
-assume that missing files are auto-generated: when
-.Ic INCLUDE
-or
-.Ic INCBIN
-is attempted on a non-existent file, it is added as a dependency, then
-.Nm
-exits normally instead of erroring out.
-This feature is used in automatic updating of makefiles.
-.It Fl MP
-When enabled, this causes a phony target to be added for each dependency other than the main file.
-This prevents
-.Xr make 1
-from erroring out when dependency files are deleted.
-.It Fl MT Ar target_file
-Add a target to the rules emitted by
-.Fl M .
-The exact string provided will be written, including spaces and special characters.
-.Dl Fl MT No fileA Fl MT No fileB
-is equivalent to
-.Dl Fl MT No 'fileA fileB' .
-If neither this nor
-.Fl MQ
-is specified, the output file name is used.
-.It Fl MQ Ar target_file
-Same as
-.Fl MT ,
-but additionally escapes any special
-.Xr make 1
-characters, essentially
-.Sq $ .
-.It Fl o Ar out_file , Fl Fl output Ar out_file
-Write an object file to the given filename.
-.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
-When padding an image, pad with this value.
-The default is 0x00.
-.It Fl r Ar recursion_depth , Fl Fl recursion-depth Ar recursion_depth
-Specifies the recursion depth at which RGBASM will assume being in an infinite loop.
-.It Fl V , Fl Fl version
-Print the version of the program and exit.
-.It Fl v , Fl Fl verbose
-Be verbose.
-.It Fl W Ar warning , Fl Fl warning Ar warning
-Set warning flag
-.Ar warning .
-A warning message will be printed if
-.Ar warning
-is an unknown warning flag.
-See the
-.Sx DIAGNOSTICS
-section for a list of warnings.
-.It Fl w
-Disable all warning output, even when turned into errors.
-.El
-.Sh DIAGNOSTICS
-Warnings are diagnostic messages that indicate possibly erroneous behavior that does not necessarily compromise the assembling process.
-The following options alter the way warnings are processed.
-.Bl -tag -width Ds
-.It Fl Werror
-Make all warnings into errors.
-.It Fl Werror=
-Make the specified warning into an error.
-A warning's name is appended
-.Pq example: Fl Werror=obsolete ,
-and this warning is implicitly enabled and turned into an error.
-This is an error if used with a meta warning, such as
-.Fl Werror=all .
-.El
-.Pp
-The following warnings are
-.Dq meta
-warnings, that enable a collection of other warnings.
-If a specific warning is toggled via a meta flag and a specific one, the more specific one takes priority.
-The position on the command-line acts as a tie breaker, the last one taking effect.
-.Bl -tag -width Ds
-.It Fl Wall
-This enables warnings that are likely to indicate an error or undesired behavior, and that can easily be fixed.
-.It Fl Wextra
-This enables extra warnings that are less likely to pose a problem, but that may still be wanted.
-.It Fl Weverything
-Enables literally every warning.
-.El
-.Pp
-The following warnings are actual warning flags; with each description, the corresponding warning flag is included.
-Note that each of these flag also has a negation (for example,
-.Fl Wcharmap-redef
-enables the warning that
-.Fl Wno-charmap-redef
-disables).
-Only the non-default flag is listed here.
-Ignoring the
-.Dq no-
-prefix, entries are listed alphabetically.
-.Bl -tag -width Ds
-.It Fl Wno-assert
-Warn when
-.Ic WARN Ns No -type
-assertions fail. (See
-.Dq Aborting the assembly process
-in
-.Xr rgbasm 5
-for
-.Ic ASSERT ) .
-.It Fl Wbackwards-for
-Warn when
-.Ic FOR
-loops have their start and stop values switched according to the step value.
-This warning is enabled by
-.Fl Wall .
-.It Fl Wbuiltin-args
-Warn about incorrect arguments to built-in functions, such as
-.Fn STRSUB
-with indexes outside of the string's bounds.
-This warning is enabled by
-.Fl Wall .
-.It Fl Wcharmap-redef
-Warn when re-defining a charmap mapping.
-This warning is enabled by
-.Fl Wall .
-.It Fl Wdiv
-Warn when dividing the smallest negative integer (-2**31) by -1, which yields itself due to integer overflow.
-.It Fl Wempty-macro-arg
-Warn when a macro argument is empty.
-This warning is enabled by
-.Fl Wextra .
-.It Fl Wempty-strrpl
-Warn when
-.Fn STRRPL
-is called with an empty string as its second argument (the substring to replace).
-This warning is enabled by
-.Fl Wall .
-.It Fl Wlarge-constant
-Warn when a constant too large to fit in a signed 32-bit integer is encountered.
-This warning is enabled by
-.Fl Wall .
-.It Fl Wlong-string
-Warn when a string too long to fit in internal buffers is encountered.
-This warning is enabled by
-.Fl Wall .
-.It Fl Wmacro-shift
-Warn when shifting macro arguments past their limits.
-This warning is enabled by
-.Fl Wextra .
-.It Fl Wno-obsolete
-Warn when obsolete constructs such as the
-.Ic _PI
-constant or
-.Ic PRINTT
-directive are encountered.
-.It Fl Wnumeric-string=
-Warn when a multi-character string is treated as a number.
-.Fl Wnumeric-string=0
-or
-.Fl Wno-numeric-string
-disables this warning.
-.Fl Wnumeric-string=1
-or just
-.Fl Wnumeric-string
-warns about strings longer than four characters, since four or fewer characters fit within a 32-bit integer.
-.Fl Wnumeric-string=2
-warns about any multi-character string.
-.It Fl Wshift
-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 Wtruncation=
-Warn when an implicit truncation (for example,
-.Ic db
-to an 8-bit value) loses some bits.
-.Fl Wtruncation=0
-or
-.Fl Wno-truncation
-disables this warning.
-.Fl Wtruncation=1
-warns when an N-bit value's absolute value is 2**N or greater.
-.Fl Wtruncation=2
-or just
-.Fl Wtruncation
-also warns when an N-bit value is less than -2**(N-1), which will not fit in two's complement encoding.
-.It Fl Wno-user
-Warn when the
-.Ic WARN
-built-in is executed. (See
-.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
-Pipes way:
-.Dl $ cat foo.asm | rgbasm -o bar.o -
-.Dl $ rgbasm -o bar.o - < foo.asm
-.Pp
-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 .
-.Sh BUGS
-Please report bugs on
-.Lk https://github.com/gbdev/rgbds/issues GitHub .
-.Sh SEE ALSO
-.Xr rgbasm 5 ,
-.Xr rgbfix 1 ,
-.Xr rgblink 1 ,
-.Xr rgbds 5 ,
-.Xr rgbds 7 ,
-.Xr gbz80 7
-.Sh HISTORY
-.Nm
-was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
-It is now maintained by a number of contributors at
-.Lk https://github.com/gbdev/rgbds .
--- a/src/asm/rgbasm.5
+++ /dev/null
@@ -1,2071 +1,0 @@
-'\" e
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.Dd March 28, 2021
-.Dt RGBASM 5
-.Os
-.Sh NAME
-.Nm rgbasm
-.Nd language documentation
-.Sh DESCRIPTION
-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
-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 RGBDS object files (described in
-.Xr rgbds 5 )
-can be used in its place.
-.Sh SYNTAX
-The syntax is line-based, just as in any other assembler, meaning that you do one instruction or directive per line:
-.Pp
-.Dl Oo Ar label Oc Oo Ar instruction Oc Oo Ar ;\ comment Oc
-.Pp
-Example:
-.Bd -literal -offset indent
-John: ld a,87 ;Weee
-.Ed
-.Pp
-All reserved keywords (directives, mnemonics, registers, etc.) are case-insensitive;
-all identifiers (symbol names) are case-sensitive.
-.Pp
-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 \&;
-not inside a string, is a comment until the end of the line.
-The second is a block comment, beginning with
-.Ql /*
-and ending with
-.Ql */ .
-It can be split across multiple lines, or occur in the middle of an expression:
-.Bd -literal -offset indent
-X = /* the value of x
- should be 3 */ 3
-.Ed
-.Pp
-Sometimes lines can be too long and it may be necessary to split them.
-To do so, put a backslash at the end of the line:
-.Bd -literal -offset indent
- DB 1, 2, 3,\ \[rs]
- 4, 5, 6,\ \[rs]\ ;\ Put it before any comments
- 7, 8, 9
- DB "Hello,\ \[rs]\ \ ;\ Space before the \[rs] is included
-world!"\ \ \ \ \ \ \ \ \ \ \ ;\ Any leading space is included
-.Ed
-.Ss Symbol interpolation
-A funky feature is
-.Ql {symbol}-within a string, called
-.Dq symbol interpolation .
-This will paste the contents of
-.Ql symbol
-as if they were part of the source file.
-If it is a string symbol, its characters are simply inserted as-is.
-If it is a numeric symbol, its value is converted to hexadecimal notation with a dollar sign
-.Sq $
-prepended.
-.Pp
-Symbol interpolations can be nested, too!
-.Bd -literal -offset indent
-DEF topic EQUS "life, the universe, and \[rs]"everything\[rs]""
-DEF meaning EQUS "answer"
-;\ Defines answer = 42
-DEF {meaning} = 42-;\ Prints "The answer to life, the universe, and "everything" is $2A"
-PRINTLN "The {meaning} to {topic} is {{meaning}}"-PURGE topic, meaning, {meaning}-.Ed
-.Pp
-Symbols can be
-.Em interpolated
-even in the contexts that disable automatic
-.Em expansion
-of string constants:
-.Ql name
-will be expanded in all of
-.Ql DEF({name}) ,-.Ql DEF {name} EQU/=/EQUS/etc ... ,-.Ql PURGE {name} ,-and
-.Ql MACRO {name} ,-but, for example, won't be in
-.Ql DEF(name) .
-.Pp
-It's possible to change the way symbols are printed by specifying a print format like so:
-.Ql {fmt:symbol} .-The
-.Ql fmt
-specifier consists of these parts:
-.Ql <sign><prefix><align><pad><width><frac><type> .
-These parts are:
-.Bl -column "<prefix>"
-.It Sy Part Ta Sy Meaning
-.It Ql <sign> Ta May be
-.Ql +
-or
-.Ql \ .
-If specified, prints this character in front of non-negative numbers.
-.It Ql <prefix> Ta May be
-.Ql # .
-If specified, prints the appropriate prefix for numbers,
-.Ql $ ,
-.Ql & ,
-or
-.Ql % .
-.It Ql <align> Ta May be
-.Ql - .
-If specified, aligns left instead of right.
-.It Ql <pad> Ta May be
-.Ql 0 .
-If specified, pads right-aligned numbers with zeros instead of spaces.
-.It Ql <width> Ta May be one or more
-.Ql 0
-\[en]
-.Ql 9 .
-If specified, pads the value to this width, right-aligned with spaces by default.
-.It Ql <frac> Ta May be
-.Ql \&.
-followed by one or more
-.Ql 0
-\[en]
-.Ql 9 .
-If specified, prints this many digits of a fixed-point fraction.
-Defaults to 5 digits, maximum 255 digits.
-.It Ql <type> Ta Specifies the type of value.
-.El
-.Pp
-All the format specifier parts are optional except the
-.Ql <type> .
-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 Signed decimal Ta -42
-.It Ql u Ta Unsigned 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
-.It Ql o Ta Octal Ta 52
-.It Ql f Ta Fixed-point Ta 1234.56789
-.It Ql s Ta String Ta \&"example\&"
-.El
-.Pp
-Examples:
-.Bd -literal -offset indent
-SECTION "Test", ROM0[2]
-X: ;\ This works with labels **whose address is known**
-Y = 3 ;\ This also works with variables
-SUM equ X + Y ;\ And likewise with numeric constants
-; Prints "%0010 + $3 == 5"
-PRINTLN "{#05b:X} + {#x:Y} == {d:SUM}"-
-rsset 32
-PERCENT rb 1 ;\ Same with offset constants
-VALUE = 20
-RESULT = MUL(20.0, 0.32)
-; Prints "32% of 20 = 6.40"
-PRINTLN "{d:PERCENT}% of {d:VALUE} = {f:RESULT}"-
-WHO equs STRLWR("WORLD")-; Prints "Hello world!"
-PRINTLN "Hello {s:WHO}!"-.Ed
-.Pp
-Although, for these examples,
-.Ic STRFMT
-would be more approriate; see
-.Sx String expressions
-further below.
-.Sh EXPRESSIONS
-An expression can be composed of many things.
-Numeric 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
-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
-The instructions in the macro-language generally require constant expressions.
-.Ss Numeric formats
-There are a number of numeric formats.
-.Bl -column -offset indent "Fixed point (Q16.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 (Q16.16) Ta none Ta 01234.56789
-.It Character constant Ta none Ta \(dqABYZ\(dq
-.It Gameboy graphics Ta \` Ta 0123
-.El
-.Pp
-Underscores are also accepted in numbers, except at the beginning of one.
-This can be useful for grouping digits, like
-.Ql 123_456
-or
-.Ql %1100_1001 .
-.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
-A great number of operators you can use in expressions are available (listed from highest to lowest precedence):
-.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 Exponent
-.It Li ~ + - Ta Unary complement/plus/minus
-.It Li * / % Ta Multiply/divide/modulo
-.It Li << Ta Shift left
-.It Li >> Ta Signed shift right (sign-extension)
-.It Li >>> Ta Unsigned shift right (zero-extension)
-.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, so that
-.Sq a / b * b + a % b == a
-is always true.
-The result has the same sign as the divisor.
-This makes
-.Sq a % b .
-equal to
-.Sq (a + b) % b
-or
-.Sq (a - b) % b .
-.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
-.Ic \&!
-returns 1 if the operand was 0, and 0 otherwise.
-.Ss Fixed-point expressions
-Fixed-point numbers are basically normal (32-bit) integers, which count 65536ths 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
-.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 POW x y Ta $x$ to the $y$ power
-.It Fn LOG x y Ta Logarithm of $x$ to the base $y$
-.It Fn ROUND x Ta Round $x$ to the nearest integer
-.It Fn CEIL x Ta Round $x$ up to an integer
-.It Fn FLOOR x Ta Round $x$ down to an integer
-.It Fn SIN x Ta Sine of $x$
-.It Fn COS x Ta Cosine of $x$
-.It Fn TAN x Ta Tangent of $x$
-.It Fn ASIN x Ta Inverse sine of $x$
-.It Fn ACOS x Ta Inverse cosine of $x$
-.It Fn ATAN x Ta Inverse tangent of $x$
-.It Fn ATAN2 x y Ta Angle between $( x , y )$ and $( 1 , 0 )$
-.El
-.EQ
-delim off
-.EN
-.Pp
-The trigonometry functions (
-.Ic SIN ,
-.Ic COS ,
-.Ic TAN ,
-etc) are defined in terms of a circle divided into 65535.0 degrees.
-.Pp
-These functions are useful for automatic generation of various tables.
-For example:
-.Bd -literal -offset indent
-; Generate a 256-byte sine table with values in the range [0, 128]
-; (shifted and scaled from the range [-1.0, 1.0])
-ANGLE = 0.0
- REPT 256
- db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
-ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
- ENDR
-.Ed
-.Ss String expressions
-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:
-.Bl -column -offset indent "Qo \[rs]1 Qc \[en] Qo \[rs]9 Qc"
-.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 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 in the body of a macro; see Sx Invoking macros )
-.It Ql \[rs]# Ta All Dv _NARG No macro arguments, separated by commas (Only in the body of a macro)
-.It Ql \[rs]@ Ta Label name suffix (Only in the body of a macro or a Ic REPT No block)
-.El
-(Note that some of those can be used outside of strings, when noted further in this document.)
-.Pp
-Multi-line strings are contained in triple quotes
-.Pq Ql \&"\&"\&"for instance\&"\&"\&" .
-Escape sequences work the same way in multi-line strings; however, literal newline
-characters will be included as-is, without needing to escape them with
-.Ql \[rs]r
-or
-.Ql \[rs]n .
-.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!
-.Bl -column "STRSUB(str, pos, len)"
-.It Sy Name Ta Sy Operation
-.It Fn STRLEN str Ta Returns the number of characters in Ar str .
-.It Fn STRCAT strs... Ta Concatenates Ar strs .
-.It Fn STRCMP str1 str2 Ta Returns -1 if Ar str1 No is alphabetically lower than Ar str2 No , zero if they match, 1 if Ar str1 No is greater than Ar str2 .
-.It Fn STRIN str1 str2 Ta Returns the first position of Ar str2 No in Ar str1 No or zero if it's not present Pq first character is position 1 .
-.It Fn STRRIN str1 str2 Ta Returns the last 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 No (first character is position 1, last is position -1) and Ar len No characters long. If Ar len No is not specified the substring continues to the end of Ar str .
-.It Fn STRUPR str Ta Returns Ar str No with all letters in uppercase.
-.It Fn STRLWR str Ta Returns Ar str No with all letters in lowercase.
-.It Fn STRRPL str old new Ta Returns Ar str No with each non-overlapping occurrence of the substring Ar old No replaced with Ar new .
-.It Fn STRFMT fmt args... Ta Returns the string Ar fmt No with each
-.Ql %spec
-pattern replaced by interpolating the format
-.Ar spec
-.Pq using the same syntax as Sx Symbol interpolation
-with its corresponding argument in
-.Ar args
-.Pq So %% Sc is replaced by the So % Sc character .
-.It Fn CHARLEN str Ta Returns the number of charmap entries in Ar str No with the current charmap.
-.It Fn CHARSUB str pos Ta Returns the substring for the charmap entry at Ar pos No in Ar str No (first character is position 1, last is position -1) with the current charmap.
-.El
-.Ss Character maps
-When writing text strings that are meant to be displayed on the Game Boy, the character encoding in the ROM may need to be different than the source file encoding.
-For example, the tiles used for uppercase letters may be placed starting at tile index 128, which differs from ASCII starting at 65.
-.Pp
-Character maps allow mapping strings to arbitrary 8-bit values:
-.Bd -literal -offset indent
-CHARMAP "<LF>", 10
-CHARMAP "í", 20
-CHARMAP "A", 128
-.Ed
-This would result in
-.Ql db \(dqAmen<LF>\(dq
-being equivalent to
-.Ql db 128, 109, 101, 110, 10 .
-.Pp
-Any characters in a string without defined mappings will be copied directly, using the source file's encoding of characters to bytes.
-.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 No and switches to it.
-.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename , No and switches to it.
-.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:
-Modifications to a character map take effect immediately from that point onward.
-.Ss Other functions
-There are a few other functions that do various useful things:
-.Bl -column "DEF(symbol)"
-.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 SIZEOF arg Ta Returns the size of the section named
-.Ar arg .
-The result is not constant, since only RGBLINK can compute its value.
-.It Fn STARTOF arg Ta Returns the starting address of the section named
-.Ar arg .
-The result is not constant, since only RGBLINK can compute its value.
-.It Fn DEF symbol Ta Returns TRUE (1) if
-.Ar symbol
-has been defined, FALSE (0) otherwise.
-String constants 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
-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.
-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.
-.Pp
-Possible section
-.Ar type Ns s
-are as follows:
-.Bl -tag -width Ds
-.It Ic ROM0
-A ROM section.
-.Ar addr
-can range from
-.Ad $0000
-to
-.Ad $3FFF ,
-or
-.Ad $0000
-to
-.Ad $7FFF
-if tiny ROM mode is enabled in the linker.
-.It Ic ROMX
-A banked ROM section.
-.Ar addr
-can range from
-.Ad $4000
-to
-.Ad $7FFF .
-.Ar bank
-can range from 1 to 511.
-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
-.Ad $8000
-to
-.Ad $9FFF .
-.Ar bank
-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
-.Ad $A000
-to
-.Ad $BFFF .
-.Ar bank
-can range from 0 to 15.
-.It Ic WRAM0
-A general-purpose RAM section.
-.Ar addr
-can range from
-.Ad $C000
-to
-.Ad $CFFF ,
-or
-.Ad $C000
-to
-.Ad $DFFF
-if WRAM0 mode is enabled in the linker.
-.It Ic WRAMX
-A banked general-purpose RAM section.
-.Ar addr
-can range from
-.Ad $D000
-to
-.Ad $DFFF .
-.Ar bank
-can range from 1 to 7.
-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
-.Ad $FE00
-to
-.Ad $FE9F .
-.It Ic HRAM
-A high RAM section.
-.Ar addr
-can range from
-.Ad $FF80
-to
-.Ad $FFFE .
-.Pp
-.Sy Note :
-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 -width Ds
-.It Ic BANK Ns Bq Ar bank
-Specify which
-.Ar bank
-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 , offset
-Place the section at an address whose
-.Ar align
-least-significant bits are equal to
-.Ar offset .
-(Note that
-.Ic ALIGN Ns Bq Ar align
-is a shorthand for
-.Ic ALIGN Ns Bq Ar align , No 0 ) .
-This option can be used with
-.Bq Ar addr ,
-as long as they don't contradict eachother.
-It's also possible to request alignment in the middle of a section, see
-.Sx Requesting alignment
-below.
-.El
-.Pp
-If
-.Bq Ar addr
-is not specified, the section is considered
-.Dq floating ;
-the linker will automatically calculate an appropriate address for the section.
-Similarly, if
-.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.
-The format is described in
-.Xr rgblink 5 .
-They allow the user to place floating sections in the desired bank in the order specified in the script.
-This is useful if the sections can't be placed at an address manually because the size may change, but they have to be together.
-.Pp
-Section examples:
-.Bl -item
-.It
-.Bd -literal -offset indent
-SECTION "Cool Stuff",ROMX
-.Ed
-This switches to the section called
-.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:
-.Bd -literal -offset indent
-SECTION "Cool Stuff",ROMX[$4567]
-.Ed
-.It
-An example with a fixed bank:
-.Bd -literal -offset indent
-SECTION "Cool Stuff",ROMX[$4567],BANK[3]
-.Ed
-.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 "Cool Stuff",ROMX,BANK[7]
-.Ed
-.It
-Alignment examples:
-The first one could be useful for defining an OAM buffer to be DMA'd, since it must be aligned to 256 bytes.
-The second could also be appropriate for GBC HDMA, or for an optimized copy code that requires alignment.
-.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
-.Ed
-.El
-.Ss Section stack
-.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 override the section context at the point the file was included.
-.Ss RAM code
-Sometimes you want to have some code in RAM.
-But then you can't simply put it in a RAM section, you have to store it in ROM and copy it to RAM at some point.
-.Pp
-This means the code (or data) will not be stored in the place it gets executed.
-Luckily,
-.Ic LOAD
-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
-
-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
-.Ed
-.Pp
-A
-.Ic LOAD
-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 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
-.Sq RAMCode
-and
-.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
-You cannot nest
-.Ic LOAD
-blocks, nor can you change the current section within them.
-.Pp
-.Ic LOAD
-blocks can use the
-.Ic UNION
-or
-.Ic FRAGMENT
-modifiers, as described below.
-.Ss Unionized sections
-When you're tight on RAM, you may want to define overlapping static memory allocations, as explained in the
-.Sx Unions
-section.
-However, a
-.Ic UNION
-only works within a single file, so it can't be used e.g. to define temporary variables across several files, all of which use the same statically allocated memory.
-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 (i.e. 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
-If one section has been declared as unionized, all sections with the same name must be declared unionized as well.
-.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.
-.Ss Section fragments
-Section fragments are sections with a small twist: when several of the same name are encountered, they are concatenated instead of producing an error.
-This works within the same file (paralleling the behavior "plain" sections has in previous versions), but also across object files.
-To declare an section fragment, add a
-.Ic FRAGMENT
-keyword after the
-.Ic SECTION
-one; the declaration is otherwise not different.
-However, similarly to
-.Sx Unionized sections ,
-some rules must be followed:
-.Bl -bullet -offset indent
-.It
-If one section has been declared as fragment, all sections with the same name must be declared fragments as well.
-.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
-A section fragment may not be unionized; after all, that wouldn't make much sense.
-.El
-.Pp
-When RGBASM merges two fragments, the one encountered later is appended to the one encountered earlier.
-.Pp
-When RGBLINK merges two fragments, the one whose file was specified last is appended to the one whose file was specified first.
-For example, assuming
-.Ql bar.o ,
-.Ql baz.o ,
-and
-.Ql foo.o
-all contain a fragment with the same name, the command
-.Dl rgblink -o rom.gb baz.o foo.o bar.o
-would produce the fragment from
-.Ql baz.o
-first, followed by the one from
-.Ql foo.o ,
-and the one from
-.Ql bar.o
-last.
-.Sh SYMBOLS
-RGBDS supports several types of symbols:
-.Bl -hang
-.It Sy Label
-Numeric symbol designating a memory location.
-May or may not have a value known at assembly time.
-.It Sy Constant
-Numeric 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
-A text string that can be expanded later, similarly to a macro.
-.El
-.Pp
-Symbol names can contain ASCII letters, numbers, underscores
-.Sq _ ,
-hashes
-.Sq #
-and at signs
-.Sq @ .
-However, they must begin with either a letter or an underscore.
-Additionally, label names can contain up to a single dot
-.Ql \&. ,
-which may not be the first character.
-.Pp
-A symbol cannot have the same name as a reserved keyword.
-.Ss Labels
-One of the assembler's main tasks is to keep track of addresses for you, so you can work with meaningful names instead of
-.Dq magic
-numbers.
-Labels enable just that: a label ties a name to a specific location within a section.
-A label resolves to a bank and address, determined at the same time as its parent section's (see further in this section).
-.Pp
-A label is defined by writing its name at the beginning of a line, followed by one or two colons, without any whitespace between the label name and the colon(s).
-Declaring a label (global or local) with two colons
-.Ql ::
-will define and
-.Ic EXPORT
-it at the same time.
-(See
-.Sx Exporting and importing symbols
-below).
-When defining a local label, the colon can be omitted, and
-.Nm
-will act as if there was only one.
-.Pp
-A label is said to be
-.Em local
-if its name contains a dot
-.Ql \&. ;
-otherwise, it is said to be
-.Em global
-(not to be mistaken with
-.Dq exported ,
-explained in
-.Sx Exporting and importing symbols
-further below).
-More than one dot in label names is not allowed.
-.Pp
-For convenience, local labels can use a shorthand syntax: when a symbol name starting with a dot is found (for example, inside an expression, or when declaring a label), then the current
-.Dq label scope
-is implicitly prepended.
-.Pp
-Defining a global label sets it as the current
-.Dq label scope ,
-until the next global label definition, or the end of the current section.
-.Pp
-Here are some examples of label definitions:
-.Bd -literal -offset indent
-GlobalLabel:
-AnotherGlobal:
-\&.locallabel ;\ This defines "AnotherGlobal.locallabel"
-\&.another_local:
-AnotherGlobal.with_another_local:
-ThisWillBeExported:: ;\ Note the two colons
-ThisWillBeExported.too::
-.Ed
-.Pp
-In a numeric expression, a label evaluates to its address in memory.
-.Po To obtain its bank, use the
-.Ql BANK()
-function described in
-.Sx Other functions
-.Pc .
-For example, given the following,
-.Ql ld de, vPlayerTiles
-would be equivalent to
-.Ql ld de, $80C0
-assuming the section ends up at
-.Ad $80C0 :
-.Bd -literal -offset indent
-SECTION "Player tiles", VRAM
-PlayerTiles:
- ds 6 * 16
-.end
-.Ed
-.Pp
-A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants.
-However, if the section in which the label is defined has a fixed base address, its value is known at assembly time.
-.Pp
-Also, while
-.Nm
-obviously can compute the difference between two labels if both are constant, it is also able to compute the difference between two non-constant labels if they both belong to the same section, such as
-.Ql PlayerTiles
-and
-.Ql PlayerTiles.end
-above.
-.Ss Anonymous labels
-Anonymous labels are useful for short blocks of code.
-They are defined like normal labels, but without a name before the colon.
-Anonymous labels are independent of label scoping, so defining one does not change the scoped label, and referencing one is not affected by the current scoped label.
-.Pp
-Anonymous labels are referenced using a colon
-.Ql \&:
-followed by pluses
-.Ql +
-or minuses
-.Ql - .
-Thus
-.Ic :+
-references the next one after the expression,
-.Ic :++
-the one after that;
-.Ic :-
-references the one before the expression;
-and so on.
-.Bd -literal -offset indent
- ld hl, :++
-: ld a, [hli] ; referenced by "jr nz"
- ldh [c], a
- dec c
- jr nz, :-
- ret
-
-: ; referenced by "ld hl"
- dw $7FFF, $1061, $03E0, $58A5
-.Ed
-.Ss Variables
-An equal sign
-.Ic =
-is used to define mutable numeric symbols.
-Unlike the other symbols described below, variables can be redefined.
-This is useful for internal symbols in macros, for counters, etc.
-.Bd -literal -offset indent
-DEF ARRAY_SIZE EQU 4
-DEF COUNT = 2
-DEF COUNT = 3
-DEF COUNT = ARRAY_SIZE + COUNT
-COUNT = COUNT*2
-;\ COUNT now has the value 14
-.Ed
-.Pp
-Note that colons
-.Ql \&:
-following the name are not allowed.
-.Pp
-Variables can be conveniently redefined by compound assignment operators like in C:
-.Bl -column -offset indent "*= /= %="
-.It Sy Operator Ta Sy Meaning
-.It Li += -= Ta Compound plus/minus
-.It Li *= /= %= Ta Compound multiply/divide/modulo
-.It Li <<= >>= Ta Compound shift left/right
-.It Li &= \&|= ^= Ta Compound and/or/xor
-.El
-.Pp
-Examples:
-.Bd -literal -offset indent
-DEF x = 10
-DEF x += 1 ; x == 11
-DEF y = x - 1 ; y == 10
-DEF y *= 2 ; y == 20
-DEF y >>= 1 ; y == 10
-DEF x ^= y ; x == 1
-.Ed
-.Ss Numeric constants
-.Ic EQU
-is used to define immutable numeric symbols.
-Unlike
-.Ic =
-above, constants defined this way cannot be redefined.
-These constants can be used for unchanging values such as properties of the hardware.
-.Bd -literal -offset indent
-def SCREEN_WIDTH equ 160 ;\ In pixels
-def SCREEN_HEIGHT equ 144
-.Ed
-.Pp
-Note that colons
-.Ql \&:
-following the name are not allowed.
-.Pp
-If you
-.Em really
-need to, the
-.Ic REDEF
-keyword will define or redefine a numeric constant symbol.
-(It can also be used for variables, although it's not necessary since they are mutable.)
-This can be used, for example, to update a constant using a macro, without making it mutable in general.
-.Bd -literal -offset indent
- def NUM_ITEMS equ 0
-MACRO add_item
- redef NUM_ITEMS equ NUM_ITEMS + 1
- def ITEM_{02x:NUM_ITEMS} equ \[rs]1-ENDM
- add_item 1
- add_item 4
- add_item 9
- add_item 16
- assert NUM_ITEMS == 4
- assert ITEM_04 == 16
-.Ed
-.Ss Offset constants
-The RS group of commands is a handy way of defining structure offsets:
-.Bd -literal -offset indent
- RSRESET
-DEF str_pStuff RW 1
-DEF str_tData RB 256
-DEF str_bCount RB 1
-DEF str_SIZEOF RB 0
-.Ed
-.Pp
-The example defines four constants as if by:
-.Bd -literal -offset indent
-DEF str_pStuff EQU 0
-DEF str_tData EQU 2
-DEF str_bCount EQU 258
-DEF str_SIZEOF EQU 259
-.Ed
-.Pp
-There are five commands in the RS group of commands:
-.Bl -column "RSSET constexpr"
-.It Sy Command Ta Sy Meaning
-.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 .
-.El
-.Pp
-If the argument to
-.Ic RB , RW ,
-or
-.Ic RL
-is omitted, it's assumed to be 1.
-.Pp
-Note that colons
-.Ql \&:
-following the name are not allowed.
-.Ss String constants
-.Ic EQUS
-is used to define string constant symbols.
-Wherever the assembler reads a string constant, it gets
-.Em expanded :
-the symbol's name is replaced with its contents.
-If you are familiar with C, you can think of it as similar to
-.Fd #define .
-This expansion is disabled in a few contexts:
-.Ql DEF(name) ,
-.Ql DEF name EQU/=/EQUS/etc ... ,
-.Ql PURGE name ,
-and
-.Ql MACRO name
-will not expand string constants in their names.
-.Bd -literal -offset indent
-DEF COUNTREG EQUS "[hl+]"
- ld a,COUNTREG
-
-DEF PLAYER_NAME EQUS "\[rs]"John\[rs]""
- db PLAYER_NAME
-.Ed
-.Pp
-This will be interpreted as:
-.Bd -literal -offset indent
- ld a,[hl+]
- db "John"
-.Ed
-.Pp
-String constants can also be used to define small one-line macros:
-.Bd -literal -offset indent
-DEF pusha EQUS "push af\[rs]npush bc\[rs]npush de\[rs]npush hl\[rs]n"
-.Ed
-.Pp
-Note that colons
-.Ql \&:
-following the name are not allowed.
-.Pp
-String constants can't be exported or imported.
-.Pp
-String constants, like numeric constants, cannot be redefined.
-However, the
-.Ic REDEF
-keyword will define or redefine a string constant symbol.
-For example:
-.Bd -literal -offset indent
-DEF s EQUS "Hello, "
-REDEF s EQUS "{s}world!"-; prints "Hello, world!"
-PRINTLN "{s}\n"-.Ed
-.Pp
-.Sy Important note :
-When a string constant is expanded, its expansion may contain another string constant, which will be expanded as well.
-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 .
-The same problem can occur if the expansion of a macro invokes another macro, recursively.
-.Pp
-The examples above for
-.Ql EQU ,
-.Ql = ,
-.Ql RB ,
-.Ql RW ,
-.Ql RL ,
-and
-.Ql EQUS
-all start with
-.Ql DEF .
-(A variable definition may start with
-.Ql REDEF
-instead, since they are redefinable.)
-You may use the older syntax without
-.Ql DEF ,
-but then the name being defined
-.Em must not
-have any whitespace before it;
-otherwise
-.Nm
-will treat it as a macro invocation.
-Furthermore, without the
-.Ql DEF
-keyword,
-string constants may be expanded for the name.
-This can lead to surprising results:
-.Bd -literal -offset indent
-X EQUS "Y"
-; this defines Y, not X!
-X EQU 42
-; prints "Y $2A"
-PRINTLN "{X} {Y}"-.Ed
-.Ss Macros
-One of the best features of an assembler is the ability to write macros for it.
-Macros can be called with arguments, and can react depending on input using
-.Ic IF
-constructs.
-.Bd -literal -offset indent
-MACRO MyMacro
- ld a, 80
- call MyFunc
-ENDM
-.Ed
-.Pp
-The example above defines
-.Ql MyMacro
-as a new macro.
-String constants are not expanded within the name of the macro.
-You may use the older syntax
-.Ql MyMacro: MACRO
-instead of
-.Ql MACRO MyMacro ,
-with a single colon
-.Ql \&:
-following the macro's name.
-With the older syntax, string constants may be expanded for the name.
-.Pp
-Macros can't be exported or imported.
-.Pp
-Plainly nesting macro definitions is not allowed, but this can be worked around using
-.Ic EQUS .
-So this won't work:
-.Bd -literal -offset indent
-MACRO outer
- MACRO inner
- PRINTLN "Hello!"
- ENDM
-ENDM
-.Ed
-.Pp
-But this will:
-.Bd -literal -offset indent
-MACRO outer
-DEF definition EQUS "MACRO inner\[rs]nPRINTLN \[rs]"Hello!\[rs]"\[rs]nENDM"
- definition
- PURGE definition
-ENDM
-.Ed
-.Pp
-Macro arguments support all the escape sequences of strings, as well as
-.Ql \[rs],
-to escape commas, as well as
-.Ql \[rs](
-and
-.Ql \[rs])
-to escape parentheses, since those otherwise separate and enclose arguments, respectively.
-.Ss Exporting and importing symbols
-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
-.Nm
-finds a symbol it does not know about.
-.Pp
-The following will cause
-.Ar symbol1 , symbol2
-and so on to be accessible to other files during the link process:
-.Dl Ic EXPORT Ar symbol1 Bq , Ar symbol2 , No ...
-.Pp
-For example, if you have the following three files:
-.Pp
-.Ql a.asm :
-.Bd -literal -compact
-SECTION "a", WRAM0
-LabelA:
-.Ed
-.Pp
-.Ql b.asm :
-.Bd -literal -compact
-SECTION "b", WRAM0
-ExportedLabelB1::
-ExportedLabelB2:
- EXPORT ExportedLabelB2
-.Ed
-.Pp
-.Ql c.asm :
-.Bd -literal -compact
-SECTION "C", ROM0[0]
- dw LabelA
- dw ExportedLabelB1
- dw ExportedLabelB2
-.Ed
-.Pp
-Then
-.Ql c.asm
-can use
-.Ql ExportedLabelB1
-and
-.Ql ExportedLabelB2 ,
-but not
-.Ql LabelA ,
-so linking them together will fail:
-.Bd -literal
-$ rgbasm -o a.o a.asm
-$ rgbasm -o b.o b.asm
-$ rgbasm -o c.o c.asm
-$ rgblink a.o b.o c.o
-error: c.asm(2): Unknown symbol "LabelA"
-Linking failed with 1 error
-.Ed
-.Pp
-Note also that only exported symbols will appear in symbol and map files produced by
-.Xr rgblink 1 .
-.Ss Purging symbols
-.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,
-.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.
-When not sure, it's probably not safe to purge anything other than variables, numeric or string constants, or macros.
-.Bd -literal -offset indent
-DEF Kamikaze EQUS "I don't want to live anymore"
-DEF AOLer EQUS "Me too"
- PURGE Kamikaze, AOLer
-.Ed
-.Pp
-String constants are not expanded within the symbol names.
-.Ss Predeclared symbols
-The following symbols are defined by the assembler:
-.Bl -column -offset indent "EQUS" "__ISO_8601_LOCAL__"
-.It Sy Name Ta Sy Type Ta Sy Contents
-.It Dv @ Ta Ic EQU Ta PC value (essentially, the current memory address)
-.It Dv _RS Ta Ic = Ta _RS Counter
-.It Dv _NARG Ta Ic EQU Ta Number of arguments passed to macro, updated by Ic SHIFT
-.It Dv __LINE__ Ta Ic EQU Ta The current line number
-.It Dv __FILE__ Ta Ic EQUS Ta The current filename
-.It Dv __DATE__ Ta Ic EQUS Ta Today's date
-.It Dv __TIME__ Ta Ic EQUS Ta The current time
-.It Dv __ISO_8601_LOCAL__ Ta Ic EQUS Ta ISO 8601 timestamp (local)
-.It Dv __ISO_8601_UTC__ Ta Ic EQUS Ta ISO 8601 timestamp (UTC)
-.It Dv __UTC_YEAR__ Ta Ic EQU Ta Today's year
-.It Dv __UTC_MONTH__ Ta Ic EQU Ta Today's month number, 1\[en]12
-.It Dv __UTC_DAY__ Ta Ic EQU Ta Today's day of the month, 1\[en]31
-.It Dv __UTC_HOUR__ Ta Ic EQU Ta Current hour, 0\[en]23
-.It Dv __UTC_MINUTE__ Ta Ic EQU Ta Current minute, 0\[en]59
-.It Dv __UTC_SECOND__ Ta Ic EQU Ta Current second, 0\[en]59
-.It Dv __RGBDS_MAJOR__ Ta Ic EQU Ta Major version number of RGBDS
-.It Dv __RGBDS_MINOR__ Ta Ic EQU Ta Minor version number of RGBDS
-.It Dv __RGBDS_PATCH__ Ta Ic EQU Ta Patch version number of RGBDS
-.It Dv __RGBDS_RC__ Ta Ic EQU Ta Release candidate ID of RGBDS, not defined for final releases
-.It Dv __RGBDS_VERSION__ Ta Ic EQUS Ta Version of RGBDS, as printed by Ql rgbasm --version
-.El
-.Pp
-The current time values will be taken from the
-.Dv SOURCE_DATE_EPOCH
-environment variable if that is defined as a UNIX timestamp.
-Refer to the spec at
-.Lk https://reproducible-builds.org/docs/source-date-epoch/ .
-.Sh DEFINING DATA
-.Ss Statically allocating space in RAM
-.Ic DS
-statically allocates a number of empty bytes.
-This is the preferred method of allocating space in a RAM section.
-You can also use
-.Ic DB , DW
-and
-.Ic DL
-without any arguments instead (see
-.Sx Defining constant data in ROM
-below).
-.Bd -literal -offset indent
-DS 42 ;\ Allocates 42 bytes
-.Ed
-.Pp
-Empty space in RAM sections will not be initialized.
-In ROM sections, it will be filled with the value passed to the
-.Fl p
-command-line option, except when using overlays with
-.Fl O .
-.Ss Defining constant data in ROM
-.Ic DB
-defines a list of bytes that will be stored in the final image.
-Ideal for tables and text.
-.Bd -literal -offset indent
-DB 1,2,3,4,"This is a string"
-.Ed
-.Pp
-Alternatively, you can use
-.Ic DW
-to store a list of words (16-bit) or
-.Ic DL
-to store a list of double-words/longs (32-bit).
-Both of these write their data in little-endian byte order; for example,
-.Ql dw $CAFE
-is equivalent to
-.Ql db $FE, $CA
-and not
-.Ql db $CA, $FE .
-.Pp
-Strings are handled a little specially: they first undergo charmap conversion (see
-.Sx Character maps ) ,
-then each resulting character is output individually.
-For example, under the default charmap, the following two lines are identical:
-.Bd -literal -offset indent
-DW "Hello!"
-DW "H", "e", "l", "l", "o", "!"
-.Ed
-.Pp
-If you do not want this special handling, enclose the string in parentheses.
-.Pp
-.Ic DS
-can also be used to fill a region of memory with some repeated values.
-For example:
-.Bd -literal -offset indent
-; outputs 3 bytes: $AA, $AA, $AA
-DS 3, $AA
-; outputs 7 bytes: $BB, $CC, $BB, $CC, $BB, $CC, $BB
-DS 7, $BB, $CC
-.Ed
-.Pp
-You can also use
-.Ic DB , DW
-and
-.Ic DL
-without arguments.
-This works exactly like
-.Ic DS 1 , DS 2
-and
-.Ic DS 4
-respectively.
-Consequently, no-argument
-.Ic DB , DW
-and
-.Ic DL
-can be used in a
-.Ic WRAM0
-/
-.Ic WRAMX
-/
-.Ic HRAM
-/
-.Ic VRAM
-/
-.Ic SRAM
-section.
-.Ss Including binary files
-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
-.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"
-.Ed
-.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.
-.Bd -literal -offset indent
-INCBIN "data.bin",78,256
-.Ed
-.Pp
-The length argument is optional.
-If only the start position is specified, the bytes from the start position until the end of the file will be included.
-.Ss Unions
-Unions allow multiple static 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
-keyword.
-.Ic NEXTU
-separates each block of allocations, and you may use it as many times within a union as necessary.
-.Bd -literal -offset indent
- ; Let's say PC = $C0DE here
- UNION
- ; Here, PC = $C0DE
-Name: ds 8
- ; PC = $C0E6
-Nickname: ds 8
- ; PC = $C0EE
- NEXTU
- ; PC is back to $C0DE
-Health: dw
- ; PC = $C0E0
-Something: ds 6
- ; And so on
-Lives: db
- NEXTU
-VideoBuffer: ds 19
- ENDU
-.Ed
-.Pp
-In the example above,
-.Sq Name , Health , VideoBuffer
-all have the same value, as do
-.Sq Nickname
-and
-.Sq Lives .
-Thus, keep in mind that
-.Ic ld [Health], a
-is identical to
-.Ic ld [Name], a .
-.Pp
-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 Statically allocating space in RAM ) .
-.Sh THE MACRO LANGUAGE
-.Ss Invoking macros
-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
-MACRO LoopyMacro
- 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
-MACRO LoopyMacro
- 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
-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
-MACRO LoopyMacro
- 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 you 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 constants, 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
-MACRO print_double
- PRINTLN \[rs]1 * 2
-ENDM
- print_double 1 + 2
-.Ed
-.Pp
-The
-.Ic PRINTLN
-statement will expand to
-.Ql PRINTLN 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
-MACRO PrintMacro1
- PRINTLN STRCAT(\[rs]1)
-ENDM
- PrintMacro1 "Hello "\[rs], \[rs]
- "world"
-MACRO PrintMacro2
- PRINT \[rs]1
-ENDM
- PrintMacro2 STRCAT("Hello ", \[rs]- "world\[rs]n")
-.Ed
-.Pp
-The comma in
-.Ql PrintMacro1
-needs to be escaped to prevent it from starting another macro argument.
-The comma in
-.Ql PrintMacro2
-does not need escaping because it is inside parentheses, similar to macro arguments in C.
-The backslash in
-.Ql \[rs]n
-also does not need escaping because string literals work as usual inside macro arguments.
-.Pp
-Since there are only nine digits, you can only access the first nine macro arguments like this.
-To use the rest, you need to put the multi-digit argument number in angle brackets, like
-.Ql \[rs]<10> .
-This bracketed syntax supports decimal numbers and numeric constant symbols.
-For example,
-.Ql \[rs]<_NARG>
-will get the last argument.
-.Pp
-Other macro arguments and symbol interpolations will be expanded inside the angle brackets.
-For example, if
-.Ql \[rs]1
-is
-.Ql 13 ,
-then
-.Ql \[rs]<\[rs]1>
-will expand to
-.Ql \[rs]<13> .
-Or if
-.Ql v10 = 42
-and
-.Ql x = 10 ,
-then
-.Ql \[rs]<v{d:x}>-will expand to
-.Ql \[rs]<42> .
-.Pp
-Another way to access more than nine macro arguments is the
-.Ic SHIFT
-command, a special command only available in macros.
-It will shift the arguments by one to the left, and decrease
-.Dv _NARG
-by 1.
-.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
-.Ic SHIFT
-can optionally be given an integer parameter, and will apply the above shifting that number of times.
-A negative parameter will shift the arguments in reverse.
-.Pp
-.Ic SHIFT
-is useful in
-.Ic REPT
-blocks to repeat the same commands with multiple arguments.
-.Ss Printing things during assembly
-The
-.Ic PRINT
-and
-.Ic PRINTLN
-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
-PRINT "Hello world!\[rs]n"
-PRINTLN "Hello world!"
-PRINT _NARG, " arguments\[rs]n"
-PRINTLN "sum: ", 2+3, " product: ", 2*3
-PRINTLN "Line #", __LINE__
-PRINTLN STRFMT("E = %f", 2.718)-.Ed
-.Bl -inset
-.It Ic PRINT
-prints out each of its comma-separated arguments.
-Numbers are printed as unsigned uppercase hexadecimal with a leading
-.Ic $ .
-For different formats, use
-.Ic STRFMT .
-.It Ic PRINTLN
-prints out each of its comma-separated arguments, if any, followed by a line feed
-.Pq Ql \[rs]n .
-.El
-.Ss Automatically repeating blocks of code
-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 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:
-.Bd -literal -offset indent
-REPT 4
- add a,c
-ENDR
-.Ed
-.Pp
-You can also use
-.Ic REPT
-to generate tables on the fly:
-.Bd -literal -offset indent
-; Generate a 256-byte sine table with values in the range [0, 128]
-; (shifted and scaled from the range [-1.0, 1.0])
-ANGLE = 0.0
- REPT 256
- db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
-ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
- ENDR
-.Ed
-.Pp
-As in macros, you can also use the escape sequence
-.Ic \[rs]@ .
-.Ic REPT
-blocks can be nested.
-.Pp
-A common pattern is to repeat a block for each value in some range.
-.Ic FOR
-is simpler than
-.Ic REPT
-for that purpose.
-Everything between
-.Ic FOR
-and the matching
-.Ic ENDR
-will be repeated for each value of a given symbol.
-String constants are not expanded within the symbol name.
-For example, this code will produce a table of squared values from 0 to 255:
-.Bd -literal -offset indent
-FOR N, 256
- dw N * N
-ENDR
-.Ed
-.Pp
-It acts just as if you had done:
-.Bd -literal -offset indent
-N = 0
- dw N * N
-N = 1
- dw N * N
-N = 2
- dw N * N
-; ...
-N = 255
- dw N * N
-N = 256
-.Ed
-.Pp
-You can customize the range of
-.Ic FOR
-values, similarly to Python's
-.Ql range
-function:
-.Bl -column "FOR V, start, stop, step"
-.It Sy Code Ta Sy Range
-.It Ic FOR Ar V , stop Ta Ar V No increments from 0 to Ar stop
-.It Ic FOR Ar V , start , stop Ta Ar V No increments from Ar start No to Ar stop
-.It Ic FOR Ar V , start , stop , step Ta Ar V No goes from Ar start No to Ar stop No by Ar step
-.El
-.Pp
-The
-.Ic FOR
-value will be updated by
-.Ar step
-until it reaches or exceeds
-.Ar stop .
-For example:
-.Bd -literal -offset indent
-FOR V, 4, 25, 5
- PRINT "{d:V} "-ENDR
- PRINTLN "done {d:V}"-.Ed
-.Pp
-This will print:
-.Bd -literal -offset indent
-4 9 14 19 24 done 29
-.Ed
-.Pp
-Just like with
-.Ic REPT
-blocks, you can use the escape sequence
-.Ic \[rs]@
-inside of
-.Ic FOR
-blocks, and they can be nested.
-.Pp
-You can stop a repeating block with the
-.Ic BREAK
-command.
-A
-.Ic BREAK
-inside of a
-.Ic REPT
-or
-.Ic FOR
-block will interrupt the current iteration and not repeat any more.
-It will continue running code after the block's
-.Ic ENDR .
-For example:
-.Bd -literal -offset indent
-FOR V, 1, 100
- PRINT "{d:V}"- IF V == 5
- PRINT " stop! "
- BREAK
- ENDC
- PRINT ", "
-ENDR
- PRINTLN "done {d:V}"-.Ed
-.Pp
-This will print:
-.Bd -literal -offset indent
-1, 2, 3, 4, 5 stop! done 5
-.Ed
-.Ss Aborting the assembly process
-.Ic FAIL
-and
-.Ic WARN
-can be used to print errors and warnings respectively during the assembly process.
-This is especially useful for macros that get an invalid argument.
-.Ic FAIL
-and
-.Ic WARN
-take a string as the only argument and they will print this string out as a normal error with a line number.
-.Pp
-.Ic FAIL
-stops assembling immediately while
-.Ic WARN
-shows the message but continues afterwards.
-.Pp
-If you need to ensure some assumption is correct when compiling, you can use
-.Ic ASSERT
-and
-.Ic STATIC_ASSERT .
-Syntax examples are given below:
-.Bd -literal -offset indent
-Function:
- xor a
-ASSERT LOW(MyByte) == 0
- ld h, HIGH(MyByte)
- ld l, a
- ld a, [hli]
-; You can also indent this!
- ASSERT BANK(OtherFunction) == BANK(Function)
- call OtherFunction
-; Lowercase also works
- ld hl, FirstByte
- ld a, [hli]
-assert FirstByte + 1 == SecondByte
- ld b, [hl]
- ret
-\&.end
- ; If you specify one, a message will be printed
- STATIC_ASSERT .end - Function < 256, "Function is too large!"
-.Ed
-.Pp
-First, the difference between
-.Ic ASSERT
-and
-.Ic STATIC_ASSERT
-is that the former is evaluated by RGBASM if it can, otherwise by RGBLINK; but the latter is only ever evaluated by RGBASM.
-If RGBASM cannot compute the value of the argument to
-.Ic STATIC_ASSERT ,
-it will produce an error.
-.Pp
-Second, as shown above, a string can be optionally added at the end, to give insight into what the assertion is checking.
-.Pp
-Finally, you can add one of
-.Ic WARN , FAIL
-or
-.Ic FATAL
-as the first optional argument to either
-.Ic ASSERT
-or
-.Ic STATIC_ASSERT .
-If the assertion fails,
-.Ic WARN
-will cause a simple warning (controlled by
-.Xr rgbasm 1
-flag
-.Fl Wassert )
-to be emitted;
-.Ic FAIL
-(the default) will cause a non-fatal error; and
-.Ic FATAL
-immediately aborts.
-.Ss Including other source files
-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 (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).
-.Bd -literal -offset indent
- INCLUDE "irq.inc"
-.Ed
-.Ss Conditional assembling
-The four commands
-.Ic IF , ELIF , ELSE ,
-and
-.Ic ENDC
-let you have
-.Nm
-skip over parts of your code depending on a condition.
-This is a powerful feature commonly used in macros.
-.Bd -literal -offset indent
-IF NUM < 0
- PRINTLN "NUM < 0"
-ELIF NUM == 0
- PRINTLN "NUM == 0"
-ELSE
- PRINTLN "NUM > 0"
-ENDC
-.Ed
-.Pp
-The
-.Ic ELIF
-(standing for "else if") and
-.Ic ELSE
-blocks are optional.
-.Ic IF
-/
-.Ic ELIF
-/
-.Ic ELSE
-/
-.Ic ENDC
-blocks can be nested.
-.Pp
-Note that if an
-.Ic ELSE
-block is found before an
-.Ic ELIF
-block, the
-.Ic ELIF
-block will be ignored.
-All
-.Ic ELIF
-blocks must go before the
-.Ic ELSE
-block.
-Also, if there is more than one
-.Ic ELSE
-block, all of them but the first one are ignored.
-.Sh MISCELLANEOUS
-.Ss Changing options while assembling
-.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.
-.Pq See Xr rgbasm 1 .
-.Pp
-.Ic OPT
-takes a comma-separated list of options as its argument:
-.Bd -literal -offset indent
-PUSHO
- OPT g.oOX, Wdiv, L ; acts like command-line -g.oOX -Wdiv -L
- DW `..ooOOXX ; uses the graphics constant characters from OPT g
- PRINTLN $80000000/-1 ; prints a warning about division
- LD [$FF88], A ; encoded as LD, not LDH
-POPO
- DW `00112233 ; uses the default graphics constant characters
- PRINTLN $80000000/-1 ; no warning by default
- LD [$FF88], A ; optimized to use LDH by default
-.Ed
-.Pp
-The options that
-.Ic OPT
-can modify are currently:
-.Cm b , g , p , r , h , L ,
-and
-.Cm W .
-The Boolean flag options
-.Cm h
-and
-.Cm L
-can be negated as
-.Ql OPT !h
-and
-.Ql OPT !L
-to act like omitting them from the command-line.
-.Pp
-.Ic POPO
-and
-.Ic PUSHO
-provide the interface to the option stack.
-.Ic PUSHO
-will push the current set of options on the option stack.
-.Ic POPO
-can then later be used to restore them.
-Useful if you want to change some options in an include file and you don't want to destroy the options set by the program that included your file.
-The stack's number of entries is limited only by the amount of memory in your machine.
-.Ss Requesting alignment
-While
-.Ic ALIGN
-as presented in
-.Sx SECTIONS
-is often useful as-is, sometimes you instead want a particular piece of data (or code) in the middle of the section to be aligned.
-This is made easier through the use of mid-section
-.Ic ALIGN Ar align , offset .
-It will alter the section's attributes to ensure that the location the
-.Ic ALIGN
-directive is at, has its
-.Ar align
-lower bits equal to
-.Ar offset .
-.Pp
-If the constraint cannot be met (for example because the section is fixed at an incompatible address), an error is produced.
-Note that
-.Ic ALIGN Ar align
-is a shorthand for
-.Ic ALIGN Ar align , No 0 .
-.Sh SEE ALSO
-.Xr rgbasm 1 ,
-.Xr rgblink 1 ,
-.Xr rgblink 5 ,
-.Xr rgbds 5 ,
-.Xr rgbds 7 ,
-.Xr gbz80 7
-.Sh HISTORY
-.Nm
-was originally written by Carsten S\(/orensen as part of the ASMotor package,
-and was later packaged in RGBDS by Justin Lloyd.
-It is now maintained by a number of contributors at
-.Lk https://github.com/gbdev/rgbds .
--- a/src/fix/rgbfix.1
+++ /dev/null
@@ -1,243 +1,0 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.Dd March 28, 2021
-.Dt RGBFIX 1
-.Os
-.Sh NAME
-.Nm rgbfix
-.Nd Game Boy header utility and checksum fixer
-.Sh SYNOPSIS
-.Nm
-.Op Fl jOsVv
-.Op Fl C | c
-.Op Fl f Ar fix_spec
-.Op Fl i Ar game_id
-.Op Fl k Ar licensee_str
-.Op Fl l Ar licensee_id
-.Op Fl m Ar mbc_type
-.Op Fl n Ar rom_version
-.Op Fl p Ar pad_value
-.Op Fl r Ar ram_size
-.Op Fl t Ar title_str
-.Op Ar
-.Sh DESCRIPTION
-The
-.Nm
-program changes headers of Game Boy ROM images, typically generated by
-.Xr rgblink 1 ,
-though it will work with
-.Em any
-Game Boy ROM.
-It also performs other correctness operations, such as padding.
-.Nm
-only changes the fields for which it has values specified.
-Developers are advised to fill those fields with 0x00 bytes in their source code before running
-.Nm ,
-and to have already populated whichever fields they don't specify using
-.Nm .
-.Pp
-Note that options can be abbreviated as long as the abbreviation is unambiguous:
-.Fl Fl color-o
-is
-.Fl Fl color-only ,
-but
-.Fl Fl color
-is invalid because it could also be
-.Fl Fl color-compatible .
-Options later in the command line override those set earlier.
-Accepted options are as follows:
-.Bl -tag -width Ds
-.It Fl C , Fl Fl color-only
-Set the Game Boy Color\(enonly flag
-.Pq Ad 0x143
-to 0xC0.
-This overrides
-.Fl c
-if it was set prior.
-.It Fl c , Fl Fl color-compatible
-Set the Game Boy Color\(encompatible flag:
-.Pq Ad 0x143
-to 0x80.
-This overrides
-.Fl c
-if it was set prior.
-.It Fl f Ar fix_spec , Fl Fl fix-spec Ar fix_spec
-Fix certain header values that the Game Boy checks for correctness.
-Alternatively, intentionally trash these values by writing their binary inverse instead.
-.Ar fix_spec
-is a string containing any combination of the following characters:
-.Pp
-.Bl -tag -compact -width xx
-.It Cm l
-Fix the Nintendo logo
-.Pq Ad 0x104 Ns \(en Ns Ad 0x133 .
-.It Cm L
-Trash the Nintendo logo.
-.It Cm h
-Fix the header checksum
-.Pq Ad 0x14D .
-.It Cm H
-Trash the header checksum.
-.It Cm g
-Fix the global checksum
-.Pq Ad 0x14E Ns \(en Ns Ad 0x14F .
-.It Cm G
-Trash the global checksum.
-.El
-.It Fl i Ar game_id , Fl Fl game-id Ar game_id
-Set the game ID string
-.Pq Ad 0x13F Ns \(en Ns Ad 0x142
-to a given string.
-If it's longer than 4 chars, it will be truncated, and a warning emitted.
-.It Fl j , Fl Fl non-japanese
-Set the non-Japanese region flag
-.Pq Ad 0x14A
-to 0x01.
-.It Fl k Ar licensee_str , Fl Fl new-licensee Ar licensee_str
-Set the new licensee string
-.Pq Ad 0x144 Ns \(en Ns Ad 0x145
-to a given string.
-If it's longer than 2 chars, it will be truncated, and a warning emitted.
-.It Fl l Ar licensee_id , Fl Fl old-licensee Ar licensee_id
-Set the old licensee code
-.Pq Ad 0x14B
-to a given value from 0 to 0xFF.
-This value is deprecated and should be set to 0x33 in all new software.
-.It Fl m Ar mbc_type , Fl Fl mbc-type Ar mbc_type
-Set the MBC type
-.Pq Ad 0x147
-to a given value from 0 to 0xFF.
-.Pp
-This value may also be an MBC name.
-The list of accepted names can be obtained by passing
-.Ql Cm help
-as the argument.
-Any amount of whitespace (space and tabs) is allowed around plus signs, and the order of "components" is free, as long as the MBC name is first.
-There are special considerations to take for the TPP1 mapper; see the
-.Sx TPP1
-section below.
-.It Fl n Ar rom_version , Fl Fl rom-version Ar rom_version
-Set the ROM version
-.Pq Ad 0x14C
-to a given value from 0 to 0xFF.
-.It Fl O , Fl Fl overwrite
-Allow overwriting different non-zero bytes in the header without a warning being emitted.
-.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
-Pad the ROM image to a valid size with a given pad value from 0 to 255 (0xFF).
-.Nm
-will automatically pick a size from 32 KiB, 64 KiB, 128 KiB, ..., 8192 KiB.
-The cartridge size byte
-.Pq Ad 0x148
-will be changed to reflect this new size.
-The recommended padding value is 0xFF, to speed up writing the ROM to flash chips, and to avoid "nop slides" into VRAM.
-.It Fl r Ar ram_size , Fl Fl ram-size Ar ram_size
-Set the RAM size
-.Pq Ad 0x149
-to a given value from 0 to 0xFF.
-.It Fl s , Fl Fl sgb-compatible
-Set the SGB flag
-.Pq Ad 0x146
-to 0x03.
-This flag will be ignored by the SGB unless the old licensee code is 0x33!
-If this is given as well as
-.Fl l ,
-but is not set to 0x33, a warning will be printed.
-.It Fl t Ar title , Fl Fl title Ar title
-Set the title string
-.Pq Ad 0x134 Ns \(en Ns Ad 0x143
-to a given string.
-If the title is longer than the max length, it will be truncated, and a warning emitted.
-The max length is 11 characters if the game ID
-.Pq Fl i
-is specified, 15 characters if the CGB flag
-.Fl ( c
-or
-.Fl C )
-is specified but the game ID is not, and 16 characters otherwise.
-.It Fl V , Fl Fl version
-Print the version of the program and exit.
-.It Fl v , Fl Fl validate
-Equivalent to
-.Fl f Cm lhg .
-.El
-.Sh EXAMPLES
-Most values in the ROM header do not matter to the actual console, and most are seldom useful anyway.
-The bare minimum requirements for a workable program are the header checksum, the Nintendo logo, and (if needed) the CGB/SGB flags.
-It is a good idea to pad the image to a valid size as well
-.Pq Do valid Dc meaning a power of 2, times 32 KiB .
-.Pp
-The following will make a plain, non-color Game Boy game without checking for
-a valid size:
-.Pp
-.D1 $ rgbfix -v foo.gb
-.Pp
-The following will make a SGB-enabled, color-enabled game with a title of
-.Dq foobar ,
-and pad it to a valid size.
-.Pq The Game Boy itself does not use the title, but some emulators or ROM managers do.
-.Pp
-.D1 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
-.Pp
-The following will duplicate the header of the game
-.Dq Survival Kids ,
-sans global checksum:
-.Pp
-.D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \
-SurvivalKids.gbc
-.Sh TPP1
-TPP1 is a homebrew mapper designed as a functional superset of the common traditional MBCs, allowing larger ROM and RAM sizes combined with other hardware features.
-Its specification, as well as more resources, can be found online at
-.Lk https://github.com/TwitchPlaysPokemon/tpp1 .
-.Ss MBC name
-The MBC name for TPP1 is more complex than standard mappers.
-It must be followed with the revision number, of the form
-.Ql major.minor ,
-where both
-.Ql major
-and
-.Ql minor
-are decimal, 8-bit integers.
-There may be any amount of spaces or underscores between
-.Ql TPP1
-and the revision number.
-.Nm
-only supports 1.x revisions, and will reject everything else.
-.Pp
-Like other mappers, the name may be followed with a list of optional,
-.Ql + Ns
--separated features; however,
-.Ql RAM
-should not be specified, as the TPP1 mapper implicitly requests RAM if a non-zero RAM size is specified.
-Therefore,
-.Nm
-will ignore the
-.Ql RAM
-feature on a TPP1 mapper with a warning.
-.Ss Special considerations
-TPP1 overwrites the byte at
-.Ad 0x14A ,
-usually indicating the region destination
-.Pq see Fl j ,
-with one of its three identification bytes.
-Therefore,
-.Nm
-will warn about and ignore
-.Fl j
-if used in combination with TPP1.
-.Sh BUGS
-Please report bugs on
-.Lk https://github.com/gbdev/rgbds/issues GitHub .
-.Sh SEE ALSO
-.Xr rgbasm 1 ,
-.Xr rgblink 1 ,
-.Xr rgbds 7
-.Sh HISTORY
-.Nm
-was originally released by Carsten S\(/orensen as a standalone program called gbfix, and was later packaged in RGBDS by Justin Lloyd.
-It is now maintained by a number of contributors at
-.Lk https://github.com/gbdev/rgbds .
--- a/src/gbz80.7
+++ /dev/null
@@ -1,1881 +1,0 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.Dd March 28, 2021
-.Dt GBZ80 7
-.Os
-.Sh NAME
-.Nm gbz80
-.Nd CPU opcode reference
-.Sh DESCRIPTION
-This is the list of opcodes supported by
-.Xr rgbasm 1 ,
-including a short description, the number of bytes needed to encode them and the number of CPU cycles at 1MHz (or 2MHz in GBC dual speed mode) needed to complete them.
-.Pp
-Note: All arithmetic/logic operations that use 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:
-.Bd -literal -offset indent
-OR A,B
-OR B
-.Ed
-.Sh LEGEND
-List of abbreviations used in this document.
-.Bl -tag -width Ds
-.It Ar r8
-Any of the 8-bit registers
-.Pq Sy A , B , C , D , E , H , L .
-.It Ar r16
-Any of the general-purpose 16-bit registers
-.Pq Sy BC , DE , HL .
-.It Ar n8
-8-bit integer constant.
-.It Ar n16
-16-bit integer constant.
-.It Ar e8
-8-bit offset
-.Po Sy -128
-to
-.Sy 127
-.Pc .
-.It Ar u3
-3-bit unsigned integer constant
-.Po Sy 0
-to
-.Sy 7
-.Pc .
-.It Ar cc
-Condition codes:
-.Bl -tag -width Ds -compact
-.It Sy Z
-Execute if Z is set.
-.It Sy NZ
-Execute if Z is not set.
-.It Sy C
-Execute if C is set.
-.It Sy NC
-Execute if C is not set.
-.It Sy ! cc
-Negates a condition code.
-.El
-.It Ar vec
-One of the
-.Sy RST
-vectors
-.Po Ad 0x00 , 0x08 , 0x10 , 0x18 , 0x20 , 0x28 , 0x30 ,
-and
-.Ad 0x38 Pc .
-.El
-.Sh INSTRUCTION OVERVIEW
-.Ss 8-bit Arithmetic and Logic Instructions
-.Bl -inset -compact
-.It Sx ADC A,r8
-.It Sx ADC A,[HL]
-.It Sx ADC A,n8
-.It Sx ADD A,r8
-.It Sx ADD A,[HL]
-.It Sx ADD A,n8
-.It Sx AND A,r8
-.It Sx AND A,[HL]
-.It Sx AND A,n8
-.It Sx CP A,r8
-.It Sx CP A,[HL]
-.It Sx CP A,n8
-.It Sx DEC r8
-.It Sx DEC [HL]
-.It Sx INC r8
-.It Sx INC [HL]
-.It Sx OR A,r8
-.It Sx OR A,[HL]
-.It Sx OR A,n8
-.It Sx SBC A,r8
-.It Sx SBC A,[HL]
-.It Sx SBC A,n8
-.It Sx SUB A,r8
-.It Sx SUB A,[HL]
-.It Sx SUB A,n8
-.It Sx XOR A,r8
-.It Sx XOR A,[HL]
-.It Sx XOR A,n8
-.El
-.Ss 16-bit Arithmetic Instructions
-.Bl -inset -compact
-.It Sx ADD HL,r16
-.It Sx DEC r16
-.It Sx INC r16
-.El
-.Ss Bit Operations Instructions
-.Bl -inset -compact
-.It Sx BIT u3,r8
-.It Sx BIT u3,[HL]
-.It Sx RES u3,r8
-.It Sx RES u3,[HL]
-.It Sx SET u3,r8
-.It Sx SET u3,[HL]
-.It Sx SWAP r8
-.It Sx SWAP [HL]
-.El
-.Ss Bit Shift Instructions
-.Bl -inset -compact
-.It Sx RL r8
-.It Sx RL [HL]
-.It Sx RLA
-.It Sx RLC r8
-.It Sx RLC [HL]
-.It Sx RLCA
-.It Sx RR r8
-.It Sx RR [HL]
-.It Sx RRA
-.It Sx RRC r8
-.It Sx RRC [HL]
-.It Sx RRCA
-.It Sx SLA r8
-.It Sx SLA [HL]
-.It Sx SRA r8
-.It Sx SRA [HL]
-.It Sx SRL r8
-.It Sx SRL [HL]
-.El
-.Ss Load Instructions
-.Bl -inset -compact
-.It Sx LD r8,r8
-.It Sx LD r8,n8
-.It Sx LD r16,n16
-.It Sx LD [HL],r8
-.It Sx LD [HL],n8
-.It Sx LD r8,[HL]
-.It Sx LD [r16],A
-.It Sx LD [n16],A
-.It Sx LDH [n16],A
-.It Sx LDH [C],A
-.It Sx LD A,[r16]
-.It Sx LD A,[n16]
-.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
-.It Sx CALL n16
-.It Sx CALL cc,n16
-.It Sx JP HL
-.It Sx JP n16
-.It Sx JP cc,n16
-.It Sx JR e8
-.It Sx JR cc,e8
-.It Sx RET cc
-.It Sx RET
-.It Sx RETI
-.It Sx RST vec
-.El
-.Ss Stack Operations Instructions
-.Bl -inset -compact
-.It Sx ADD HL,SP
-.It Sx ADD SP,e8
-.It Sx DEC SP
-.It Sx INC SP
-.It Sx LD SP,n16
-.It Sx LD [n16],SP
-.It Sx LD HL,SP+e8
-.It Sx LD SP,HL
-.It Sx POP AF
-.It Sx POP r16
-.It Sx PUSH AF
-.It Sx PUSH r16
-.El
-.Ss Miscellaneous Instructions
-.Bl -inset -compact
-.It Sx CCF
-.It Sx CPL
-.It Sx DAA
-.It Sx DI
-.It Sx EI
-.It Sx HALT
-.It Sx NOP
-.It Sx SCF
-.It Sx STOP
-.El
-.Sh INSTRUCTION REFERENCE
-.Ss ADC A,r8
-Add the value in
-.Ar r8
-plus the carry flag to
-.Sy A .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-Set if overflow from bit 3.
-.It Sy C
-Set if overflow from bit 7.
-.El
-.Ss ADC A,[HL]
-Add the byte pointed to by
-.Sy HL
-plus the carry flag to
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx ADC A,r8
-.Ss ADC A,n8
-Add the value
-.Ar n8
-plus the carry flag to
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx ADC A,r8
-.Ss ADD A,r8
-Add the value in
-.Ar r8
-to
-.Sy A .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-Set if overflow from bit 3.
-.It Sy C
-Set if overflow from bit 7.
-.El
-.Ss ADD A,[HL]
-Add the byte pointed to by
-.Sy HL
-to
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx ADD A,r8
-.Ss ADD A,n8
-Add the value
-.Ar n8
-to
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx ADD A,r8
-.Ss ADD HL,r16
-Add the value in
-.Ar r16
-to
-.Sy HL .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy N
-0
-.It Sy H
-Set if overflow from bit 11.
-.It Sy C
-Set if overflow from bit 15.
-.El
-.Ss ADD HL,SP
-Add the value in
-.Sy SP
-to
-.Sy HL .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx ADD HL,r16
-.Ss ADD SP,e8
-Add the signed value
-.Ar e8
-to
-.Sy SP .
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-0
-.It Sy N
-0
-.It Sy H
-Set if overflow from bit 3.
-.It Sy C
-Set if overflow from bit 7.
-.El
-.Ss AND A,r8
-Bitwise AND between the value in
-.Ar r8
-and
-.Sy A .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-1
-.It Sy C
-0
-.El
-.Ss AND A,[HL]
-Bitwise AND between the byte pointed to by
-.Sy HL
-and
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx AND A,r8
-.Ss AND A,n8
-Bitwise AND between the value in
-.Ar n8
-and
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx AND A,r8
-.Ss BIT u3,r8
-Test bit
-.Ar u3
-in register
-.Ar r8 ,
-set the zero flag if bit not set.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if the selected bit is 0.
-.It Sy N
-0
-.It Sy H
-1
-.El
-.Ss BIT u3,[HL]
-Test bit
-.Ar u3
-in the byte pointed by
-.Sy HL ,
-set the zero flag if bit not set.
-.Pp
-Cycles: 3
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx BIT u3,r8
-.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
-Bytes: 3
-.Pp
-Flags: None affected.
-.Ss CALL cc,n16
-Call address
-.Ar n16
-if condition
-.Ar cc
-is met.
-.Pp
-Cycles: 6 taken / 3 untaken
-.Pp
-Bytes: 3
-.Pp
-Flags: None affected.
-.Ss CCF
-Complement Carry Flag.
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Inverted.
-.El
-.Ss CP A,r8
-Subtract the value in
-.Ar r8
-from
-.Sy A
-and set flags accordingly, but don't store the result.
-This is useful for ComParing values.
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-1
-.It Sy H
-Set if borrow from bit 4.
-.It Sy C
-Set if borrow (i.e. if
-.Ar r8
->
-.Sy A ) .
-.El
-.Ss CP A,[HL]
-Subtract the byte pointed to by
-.Sy HL
-from
-.Sy A
-and set flags accordingly, but don't store the result.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx CP A,r8
-.Ss CP A,n8
-Subtract the value
-.Ar n8
-from
-.Sy A
-and set flags accordingly, but don't store the result.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx CP A,r8
-.Ss CPL
-ComPLement accumulator
-.Po Sy A
-=
-.Sy ~A
-.Pc .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy N
-1
-.It Sy H
-1
-.El
-.Ss DAA
-Decimal Adjust Accumulator to get a correct BCD representation after an arithmetic instruction.
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy H
-0
-.It Sy C
-Set or reset depending on the operation.
-.El
-.Ss DEC r8
-Decrement value in register
-.Ar r8
-by 1.
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-1
-.It Sy H
-Set if borrow from bit 4.
-.El
-.Ss DEC [HL]
-Decrement the byte pointed to by
-.Sy HL
-by 1.
-.Pp
-Cycles: 3
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx DEC r8
-.Ss DEC r16
-Decrement value in register
-.Ar r16
-by 1.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss DEC SP
-Decrement value in register
-.Sy SP
-by 1.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss DI
-Disable Interrupts by clearing the
-.Sy IME
-flag.
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss EI
-Enable Interrupts by setting the
-.Sy IME
-flag.
-The flag is only set
-.Em after
-the instruction following
-.Sy EI .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss HALT
-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
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss INC r8
-Increment value in register
-.Ar r8
-by 1.
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-Set if overflow from bit 3.
-.El
-.Ss INC [HL]
-Increment the byte pointed to by
-.Sy HL
-by 1.
-.Pp
-Cycles: 3
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx INC r8
-.Ss INC r16
-Increment value in register
-.Ar r16
-by 1.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss INC SP
-Increment value in register
-.Sy SP
-by 1.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss JP n16
-Jump to address
-.Ar n16 ;
-effectively, store
-.Ar n16
-into
-.Sy PC .
-.Pp
-Cycles: 4
-.Pp
-Bytes: 3
-.Pp
-Flags: None affected.
-.Ss JP cc,n16
-Jump to address
-.Ar n16
-if condition
-.Ar cc
-is met.
-.Pp
-Cycles: 4 taken / 3 untaken
-.Pp
-Bytes: 3
-.Pp
-Flags: None affected.
-.Ss JP HL
-Jump to address in
-.Sy HL ;
-effectively, load
-.Sy PC
-with value in register
-.Sy HL .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss JR e8
-Relative Jump by adding
-.Ar e8
-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
-Bytes: 2
-.Pp
-Flags: None affected.
-.Ss JR cc,e8
-Relative Jump by adding
-.Ar e8
-to the current address if condition
-.Ar cc
-is met.
-.Pp
-Cycles: 3 taken / 2 untaken
-.Pp
-Bytes: 2
-.Pp
-Flags: None affected.
-.Ss LD r8,r8
-Load (copy) value in register on the right into register on the left.
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss LD r8,n8
-Load value
-.Ar n8
-into register
-.Ar r8 .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: None affected.
-.Ss LD r16,n16
-Load value
-.Ar n16
-into register
-.Ar r16 .
-.Pp
-Cycles: 3
-.Pp
-Bytes: 3
-.Pp
-Flags: None affected.
-.Ss LD [HL],r8
-Store value in register
-.Ar r8
-into the byte pointed to by register
-.Sy HL .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss LD [HL],n8
-Store value
-.Ar n8
-into the byte pointed to by register
-.Sy HL .
-.Pp
-Cycles: 3
-.Pp
-Bytes: 2
-.Pp
-Flags: None affected.
-.Ss LD r8,[HL]
-Load value into register
-.Ar r8
-from the byte pointed to by register
-.Sy HL .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss LD [r16],A
-Store value in register
-.Sy A
-into the byte pointed to by register
-.Ar r16 .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss LD [n16],A
-Store value in register
-.Sy A
-into the byte at address
-.Ar n16 .
-.Pp
-Cycles: 4
-.Pp
-Bytes: 3
-.Pp
-Flags: None affected.
-.Ss LDH [n16],A
-Store value in register
-.Sy A
-into the byte at address
-.Ar n16 ,
-provided the address is between
-.Ad $FF00
-and
-.Ad $FFFF .
-.Pp
-Cycles: 3
-.Pp
-Bytes: 2
-.Pp
-Flags: None affected.
-.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 the byte at address
-.Ad $FF00+C .
-.Pp
-Cycles: 2
-.Pp
-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 the byte pointed to by register
-.Ar r16 .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss LD A,[n16]
-Load value in register
-.Sy A
-from the byte at address
-.Ar n16 .
-.Pp
-Cycles: 4
-.Pp
-Bytes: 3
-.Pp
-Flags: None affected.
-.Ss LDH A,[n16]
-Load value in register
-.Sy A
-from the byte at address
-.Ar n16 ,
-provided the address is between
-.Ad $FF00
-and
-.Ad $FFFF .
-.Pp
-Cycles: 3
-.Pp
-Bytes: 2
-.Pp
-Flags: None affected.
-.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 the byte at address
-.Ad $FF00+c .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.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 the byte pointed by
-.Sy HL
-and increment
-.Sy HL
-afterwards.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Pp
-This is sometimes written as
-.Ql LD [HL+],A ,
-or
-.Ql LDI [HL],A .
-.Ss LD [HLD],A
-Store value in register
-.Sy A
-into the byte pointed by
-.Sy HL
-and decrement
-.Sy HL
-afterwards.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Pp
-This is sometimes written as
-.Ql LD [HL-],A ,
-or
-.Ql LDD [HL],A .
-.Ss LD A,[HLD]
-Load value into register
-.Sy A
-from the byte pointed by
-.Sy HL
-and decrement
-.Sy HL
-afterwards.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Pp
-This is sometimes written as
-.Ql LD A,[HL-] ,
-or
-.Ql LDD A,[HL] .
-.Ss LD A,[HLI]
-Load value into register
-.Sy A
-from the byte pointed by
-.Sy HL
-and increment
-.Sy HL
-afterwards.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Pp
-This is sometimes written as
-.Ql LD A,[HL+] ,
-or
-.Ql LDI A,[HL] .
-.Ss LD SP,n16
-Load value
-.Ar n16
-into register
-.Sy SP .
-.Pp
-Cycles: 3
-.Pp
-Bytes: 3
-.Pp
-Flags: None affected.
-.Ss LD [n16],SP
-Store
-.Sy SP & $FF
-at address
-.Ar n16
-and
-.Sy SP >> 8
-at address
-.Ar n16
-+ 1.
-.Pp
-Cycles: 5
-.Pp
-Bytes: 3
-.Pp
-Flags: None affected.
-.Ss LD HL,SP+e8
-Add the signed value
-.Ar e8
-to
-.Sy SP
-and store the result in
-.Sy HL .
-.Pp
-Cycles: 3
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-0
-.It Sy N
-0
-.It Sy H
-Set if overflow from bit 3.
-.It Sy C
-Set if overflow from bit 7.
-.El
-.Ss LD SP,HL
-Load register
-.Sy HL
-into register
-.Sy SP .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss NOP
-No OPeration.
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss OR A,r8
-Store into
-.Sy A
-the bitwise OR of the value in
-.Ar r8
-and
-.Sy A .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-0
-.El
-.Ss OR A,[HL]
-Store into
-.Sy A
-the bitwise OR of the byte pointed to by
-.Sy HL
-and
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx OR A,r8
-.Ss OR A,n8
-Store into
-.Sy A
-the bitwise OR of
-.Ar n8
-and
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx OR A,r8
-.Ss POP AF
-Pop register
-.Sy AF
-from the stack.
-This is roughly equivalent to the following
-.Em imaginary
-instructions:
-.Bd -literal -offset indent
-ld f, [sp] ; See below for individual flags
-inc sp
-ld a, [sp]
-inc sp
-.Ed
-.Pp
-Cycles: 3
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set from bit 7 of the popped low byte.
-.It Sy N
-Set from bit 6 of the popped low byte.
-.It Sy H
-Set from bit 5 of the popped low byte.
-.It Sy C
-Set from bit 4 of the popped low byte.
-.El
-.Ss POP r16
-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
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss PUSH AF
-Push register
-.Sy AF
-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
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss PUSH r16
-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
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss RES u3,r8
-Set bit
-.Ar u3
-in register
-.Ar r8
-to 0.
-Bit 0 is the rightmost one, bit 7 the leftmost one.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: None affected.
-.Ss RES u3,[HL]
-Set bit
-.Ar u3
-in the byte pointed by
-.Sy HL
-to 0.
-Bit 0 is the rightmost one, bit 7 the leftmost one.
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-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
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss RET cc
-Return from subroutine if condition
-.Ar cc
-is met.
-.Pp
-Cycles: 5 taken / 2 untaken
-.Pp
-Bytes: 1
-.Pp
-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
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss RL r8
-Rotate bits in register
-.Ar r8
-left through carry.
-.Pp
-.D1 C <- [7 <- 0] <- C
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss RL [HL]
-Rotate the byte pointed to by
-.Sy HL
-left through carry.
-.Pp
-.D1 C <- [7 <- 0] <- C
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx RL r8
-.Ss RLA
-Rotate register
-.Sy A
-left through carry.
-.Pp
-.D1 C <- [7 <- 0] <- C
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-0
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss RLC r8
-Rotate register
-.Ar r8
-left.
-.Pp
-.D1 C <- [7 <- 0] <- [7]
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss RLC [HL]
-Rotate the byte pointed to by
-.Sy HL
-left.
-.Pp
-.D1 C <- [7 <- 0] <- [7]
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx RLC r8
-.Ss RLCA
-Rotate register
-.Sy A
-left.
-.Pp
-.D1 C <- [7 <- 0] <- [7]
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-0
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss RR r8
-Rotate register
-.Ar r8
-right through carry.
-.Pp
-.D1 C -> [7 -> 0] -> C
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss RR [HL]
-Rotate the byte pointed to by
-.Sy HL
-right through carry.
-.Pp
-.D1 C -> [7 -> 0] -> C
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx RR r8
-.Ss RRA
-Rotate register
-.Sy A
-right through carry.
-.Pp
-.D1 C -> [7 -> 0] -> C
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-0
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss RRC r8
-Rotate register
-.Ar r8
-right.
-.Pp
-.D1 [0] -> [7 -> 0] -> C
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss RRC [HL]
-Rotate the byte pointed to by
-.Sy HL
-right.
-.Pp
-.D1 [0] -> [7 -> 0] -> C
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx RRC r8
-.Ss RRCA
-Rotate register
-.Sy A
-right.
-.Pp
-.D1 [0] -> [7 -> 0] -> C
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-0
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss RST vec
-Call address
-.Ar vec .
-This is a shorter and faster equivalent to
-.Sx CALL
-for suitable values of
-.Ar vec .
-.Pp
-Cycles: 4
-.Pp
-Bytes: 1
-.Pp
-Flags: None affected.
-.Ss SBC A,r8
-Subtract the value in
-.Ar r8
-and the carry flag from
-.Sy A .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-1
-.It Sy H
-Set if borrow from bit 4.
-.It Sy C
-Set if borrow (i.e. if
-.Po Ar r8
-+ carry
-.Pc >
-.Sy A ) .
-.El
-.Ss SBC A,[HL]
-Subtract the byte pointed to by
-.Sy HL
-and the carry flag from
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx SBC A,r8
-.Ss SBC A,n8
-Subtract the value
-.Ar n8
-and the carry flag from
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx SBC A,r8
-.Ss SCF
-Set Carry Flag.
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-1
-.El
-.Ss SET u3,r8
-Set bit
-.Ar u3
-in register
-.Ar r8
-to 1.
-Bit 0 is the rightmost one, bit 7 the leftmost one.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: None affected.
-.Ss SET u3,[HL]
-Set bit
-.Ar u3
-in the byte pointed by
-.Sy HL
-to 1.
-Bit 0 is the rightmost one, bit 7 the leftmost one.
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags: None affected.
-.Ss SLA r8
-Shift Left Arithmetically register
-.Ar r8 .
-.Pp
-.D1 C <- [7 <- 0] <- 0
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss SLA [HL]
-Shift Left Arithmetically the byte pointed to by
-.Sy HL .
-.Pp
-.D1 C <- [7 <- 0] <- 0
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx SLA r8
-.Ss SRA r8
-Shift Right Arithmetically register
-.Ar r8 .
-.Pp
-.D1 [7] -> [7 -> 0] -> C
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss SRA [HL]
-Shift Right Arithmetically the byte pointed to by
-.Sy HL .
-.Pp
-.D1 [7] -> [7 -> 0] -> C
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx SRA r8
-.Ss SRL r8
-Shift Right Logically register
-.Ar r8 .
-.Pp
-.D1 0 -> [7 -> 0] -> C
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-Set according to result.
-.El
-.Ss SRL [HL]
-Shift Right Logically the byte pointed to by
-.Sy HL .
-.Pp
-.D1 0 -> [7 -> 0] -> C
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx SRA r8
-.Ss STOP
-Enter CPU very low power mode.
-Also used to switch between double and normal speed CPU modes in GBC.
-.Pp
-Cycles: -
-.Pp
-Bytes: 2
-.Pp
-Flags: None affected.
-.Ss SUB A,r8
-Subtract the value in
-.Ar r8
-from
-.Sy A .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-1
-.It Sy H
-Set if borrow from bit 4.
-.It Sy C
-Set if borrow (set if
-.Ar r8
->
-.Sy A ) .
-.El
-.Ss SUB A,[HL]
-Subtract the byte pointed to by
-.Sy HL
-from
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx SUB A,r8
-.Ss SUB A,n8
-Subtract the value
-.Ar n8
-from
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx SUB A,r8
-.Ss SWAP r8
-Swap the upper 4 bits in register
-.Ar r8
-and the lower 4 ones.
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-0
-.El
-.Ss SWAP [HL]
-Swap the upper 4 bits in the byte pointed by
-.Sy HL
-and the lower 4 ones.
-.Pp
-Cycles: 4
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx SWAP r8
-.Ss XOR A,r8
-Bitwise XOR between the value in
-.Ar r8
-and
-.Sy A .
-.Pp
-Cycles: 1
-.Pp
-Bytes: 1
-.Pp
-Flags:
-.Bl -hang -compact
-.It Sy Z
-Set if result is 0.
-.It Sy N
-0
-.It Sy H
-0
-.It Sy C
-0
-.El
-.Ss XOR A,[HL]
-Bitwise XOR between the byte pointed to by
-.Sy HL
-and
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 1
-.Pp
-Flags: See
-.Sx XOR A,r8
-.Ss XOR A,n8
-Bitwise XOR between the value in
-.Ar n8
-and
-.Sy A .
-.Pp
-Cycles: 2
-.Pp
-Bytes: 2
-.Pp
-Flags: See
-.Sx XOR A,r8
-.Sh SEE ALSO
-.Xr rgbasm 1 ,
-.Xr rgbds 7
-.Sh HISTORY
-.Nm rgbds
-was originally written by Carsten S\(/orensen as part of the ASMotor package,
-and was later packaged in RGBDS by Justin Lloyd.
-It is now maintained by a number of contributors at
-.Lk https://github.com/gbdev/rgbds .
--- a/src/gfx/rgbgfx.1
+++ /dev/null
@@ -1,160 +1,0 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2013-2021, stag019 and RGBDS contributors.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.Dd March 28, 2021
-.Dt RGBGFX 1
-.Os
-.Sh NAME
-.Nm rgbgfx
-.Nd Game Boy graphics converter
-.Sh SYNOPSIS
-.Nm
-.Op Fl CDhmuVv
-.Op Fl f | Fl F
-.Op Fl a Ar attrmap | Fl A
-.Op Fl d Ar depth
-.Op Fl o Ar out_file
-.Op Fl p Ar pal_file | Fl P
-.Op Fl t Ar tilemap | Fl T
-.Op Fl x Ar tiles
-.Ar file
-.Sh DESCRIPTION
-The
-.Nm
-program converts PNG images into the Nintendo Game Boy's planar tile format.
-.Pp
-The resulting colors and their palette indices are determined differently depending on the input PNG file:
-.Bl -dash -width Ds
-.It
-If the file has an embedded palette, that palette's color and order are used.
-.It
-If not, and the image only contains shades of gray, rgbgfx maps them to the indices appropriate for each shade.
-Any undetermined indices are set to respective default shades of gray.
-For example: if the bit depth is 2 and the image contains light gray and black, they become the second and fourth colors, and the first and third colors get set to default white and dark gray.
-If the image has multiple shades that map to the same index, the palette is instead determined as if the image had color.
-.It
-If the image has color (or the grayscale method failed), the colors are sorted from lightest to darkest.
-.El
-.Pp
-The input image may not contain more colors than the selected bit depth allows.
-Transparent pixels are set to palette index 0.
-.Sh ARGUMENTS
-Note that options can be abbreviated as long as the abbreviation is unambiguous:
-.Fl Fl verb
-is
-.Fl Fl verbose ,
-but
-.Fl Fl ver
-is invalid because it could also be
-.Fl Fl version .
-The arguments are as follows:
-.Bl -tag -width Ds
-.It Fl a Ar attrmap , Fl Fl attr-map Ar attrmap
-Generate a file of tile mirroring attributes for OAM or (CGB-only) background tiles.
-For each tile in the input file, a byte is written representing the dimensions that the associated tile in the output file should be mirrored.
-Useful in combination with
-.Fl m
-to keep track the mirror direction of mirrored duplicate tiles.
-.It Fl A , Fl Fl output-attr-map
-Same as
-.Fl a ,
-but the attrmap file output name is made by taking the input filename, removing the file extension, and appending
-.Pa .attrmap .
-.It Fl C , Fl Fl color-curve
-Use the color curve of the Game Boy Color when generating palettes.
-.It Fl D , Fl Fl debug
-Debug features are enabled.
-.It Fl d Ar depth , Fl Fl depth Ar depth
-The bit depth of the output image (either 1 or 2).
-By default, the bit depth is 2 (two bits per pixel).
-.It Fl f , Fl Fl fix
-Fix the input PNG file to be a correctly indexed image.
-.It Fl F , Fl Fl fix-and-save
-Same as
-.Fl f ,
-but additionally, the supplied command line parameters are saved within the PNG and will be loaded and automatically used next time.
-.It Fl h , Fl Fl horizontal
-Lay out tiles in column-major order (column by column), instead of the default row-major order (line by line).
-Especially useful for "8x16" OBJ mode, if the input image is 16 pixels tall.
-.It Fl m , Fl Fl mirror-tiles
-Truncate tiles by checking for tiles that are mirrored versions of others and omitting these from the output file.
-Useful with tilemaps and attrmaps together to keep track of the duplicated tiles and the dimension mirrored.
-Tiles are checked for horizontal, vertical, and horizontal-vertical mirroring.
-Implies
-.Fl u .
-.It Fl o Ar out_file , Fl Fl output Ar out_file
-The name of the output file.
-.It Fl p Ar pal_file , Fl Fl palette Ar pal_file
-Output the image's palette in standard GBC palette format: bytes (8 bytes for two bits per pixel, 4 bytes for one bit per pixel) containing the RGB15 values in little-endian byte order.
-If the palette contains too few colors, the remaining entries are set to black.
-.It Fl P , Fl Fl output-palette
-Same as
-.Fl p ,
-but the palette file output name is made by taking the input PNG file's filename, removing the file extension, and appending
-.Pa .pal .
-.It Fl t Ar tilemap , Fl Fl tilemap Ar tilemap
-Generate a file of tile indices.
-For each tile in the input file, a byte is written representing the index of the associated tile in the output file.
-Useful in combination with
-.Fl u
-or
-.Fl m
-to keep track of duplicate tiles.
-.It Fl T , Fl Fl output-tilemap
-Same as
-.Fl t ,
-but the tilemap file output name is made by taking the input filename, removing the file extension, and appending
-.Pa .tilemap .
-.It Fl u , Fl Fl unique-tiles
-Truncate tiles by checking for tiles that are exact duplicates of others and omitting these from the output file.
-Useful with tilemaps to keep track of the duplicated tiles.
-.It Fl V , Fl Fl version
-Print the version of the program and exit.
-.It Fl v , Fl Fl verbose
-Verbose.
-Print errors when the command line parameters and the parameters in the PNG file don't match.
-.It Fl x Ar tiles , Fl Fl trim-end Ar tiles
-Trim the end of the output file by this many tiles.
-.El
-.Sh EXAMPLES
-The following will take a PNG file with a bit depth of 1, 2, or 8, and output planar 2bpp data:
-.Pp
-.D1 $ rgbgfx -o out.2bpp in.png
-.Pp
-The following creates a planar 2bpp file with only unique tiles, and its tilemap
-.Pa out.tilemap :
-.Pp
-.D1 $ rgbgfx -T -u -o out.2bpp in.png
-.Pp
-The following creates a planar 2bpp file with only unique tiles
-.Pa accounting for tile mirroring
-and its associated tilemap
-.Pa out.tilemap
-and attrmap
-.Pa out.attrmap :
-.Pp
-.D1 $ rgbgfx -A -T -m -o out.2bpp in.png
-.Pp
-The following will do nothing:
-.Pp
-.D1 $ rgbgfx in.png
-.Sh BUGS
-Please report bugs on
-.Lk https://github.com/gbdev/rgbds/issues GitHub .
-.Sh SEE ALSO
-.Xr rgbds 7 ,
-.Xr rgbasm 1 ,
-.Xr rgblink 1 ,
-.Xr rgbfix 1 ,
-.Xr gbz80 7
-.Sh HISTORY
-.Nm
-was created by
-.An stag019
-to be included in RGBDS.
-It is now maintained by a number of contributors at
-.Lk https://github.com/gbdev/rgbds .
--- a/src/link/rgblink.1
+++ /dev/null
@@ -1,205 +1,0 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.Dd March 28, 2021
-.Dt RGBLINK 1
-.Os
-.Sh NAME
-.Nm rgblink
-.Nd Game Boy linker
-.Sh SYNOPSIS
-.Nm
-.Op Fl dtVvwx
-.Op Fl l Ar linker_script
-.Op Fl m Ar map_file
-.Op Fl n Ar sym_file
-.Op Fl O Ar overlay_file
-.Op Fl o Ar out_file
-.Op Fl p Ar pad_value
-.Op Fl S Ar spec
-.Op Fl s Ar symbol
-.Ar
-.Sh DESCRIPTION
-The
-.Nm
-program links RGB object files, typically created by
-.Xr rgbasm 1 ,
-into a single Game Boy ROM file.
-The format is documented in
-.Xr rgbds 5 .
-.Pp
-ROM0 sections are placed in the first 16 KiB of the output ROM, and ROMX sections are placed in any 16 KiB
-.Dq bank
-except the first.
-If your ROM will only be 32 KiB, you can use the
-.Fl t
-option to change this.
-.Pp
-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
-.Fl w
-option to change this.
-.Pp
-Also, if your ROM is designed for a monochrome Game Boy, you can make sure that you don't use any incompatible section by using the
-.Fl d
-option, which implies
-.Fl w
-but also prohibits the use of banked VRAM.
-.Pp
-Note that options can be abbreviated as long as the abbreviation is unambiguous:
-.Fl Fl verb
-is
-.Fl Fl verbose ,
-but
-.Fl Fl ver
-is invalid because it could also be
-.Fl Fl version .
-The arguments are as follows:
-.Bl -tag -width Ds
-.It Fl d , Fl Fl dmg
-Enable DMG mode.
-Prohibit the use of sections that doesn't exist on a DMG, such as VRAM bank 1.
-This option automatically enables
-.Fl w .
-.It Fl l Ar linker_script , Fl Fl linkerscript Ar linker_script
-Specify a linker script file that tells the linker how sections must be placed in the ROM.
-The attributes assigned in the linker script must be consistent with any assigned in the code.
-See
-.Xr rgblink 5
-for more information about the linker script format.
-.It Fl m Ar map_file , Fl Fl map Ar map_file
-Write a map file to the given filename, listing how sections and symbols were assigned.
-.It Fl n Ar sym_file , Fl Fl sym Ar sym_file
-Write a symbol file to the given filename, listing the address of all exported symbols.
-Several external programs can use this information, for example to help debugging ROMs.
-.It Fl O Ar overlay_file , Fl Fl overlay Ar overlay_file
-If specified, sections will be overlaid "on top" of the provided ROM image.
-In that case, all sections must be fixed.
-This may be used to patch an existing binary.
-.It Fl o Ar out_file , Fl Fl output Ar out_file
-Write the ROM image to the given file.
-.It Fl p Ar pad_value , Fl Fl pad Ar pad_value
-When inserting padding between sections, pad with this value.
-Has no effect if
-.Fl O
-is specified.
-The default is 0.
-.It Fl S Ar spec , Fl Fl scramble Ar spec
-Enables a different
-.Dq scrambling
-algorithm for placing sections.
-See
-.Sx Scrambling algorithm
-below for an explanation and a description of
-.Ar spec .
-.It Fl s Ar symbol , Fl Fl smart Ar symbol
-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 Fl tiny
-Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to ROM.
-ROMX sections that are fixed to a bank other than 1 become errors, other ROMX sections are treated as ROM0.
-Useful for ROMs that fit in 32 KiB.
-.It Fl V , Fl Fl version
-Print the version of the program and exit.
-.It Fl v , Fl Fl verbose
-Verbose: enable printing more information to standard error.
-.It Fl w , Fl Fl wramx
-Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to WRAM.
-WRAMX sections that are fixed to a bank other than 1 become errors, other WRAMX sections are treated as WRAM0.
-.It Fl x , Fl Fl nopad
-Disables padding the end of the final file.
-This option automatically enables
-.Fl t .
-You can use this when not not making a ROM.
-When making a ROM, be careful that not using this is not a replacement for
-.Xr rgbfix 1 Ap s Fl p
-option!
-.El
-.Ss Scrambling algorithm
-The default section placement algorithm tries to minimize the number of banks used;
-.Dq scrambling
-instead places sections into a given pool of banks, trying to minimize the number of sections sharing a given bank.
-This is useful to catch broken bank assumptions, such as expecting two different sections to land in the same bank (that is not guaranteed unless both are manually assigned the same bank number).
-.Pp
-A scrambling spec is a comma-separated list of region specs.
-A trailing comma is allowed, as well as whitespace between all specs and their components.
-Each region spec has the following form:
-.D1 Ar region Ns Op = Ns Ar size
-.Ar region
-must be one of the following (case-insensitive), while
-.Ar size
-must be a positive decimal integer between 1 and the corresponding maximum.
-Certain regions allow omitting the size, in which case it defaults to its max value.
-.Bl -column "Region name" "Max value" "Size optional"
-Region name Ta Max size Ta Size optional
-.Cm romx Ta 65535 Ta \&No
-.Cm sram Ta 255 Ta \&No
-.Cm wramx Ta 7 Ta Yes
-.El
-.Pp
-A
-.Ar size
-of 0 disables scrambling for that region.
-.Pp
-For example,
-.Ql romx=64,wramx=4
-will scramble
-.Ic ROMX
-sections among ROM banks 1 to 64,
-.Ic WRAMX
-sections among RAM banks 1 to 4, and will not scramble
-.Ic SRAM
-sections.
-.Pp
-Later region specs override earlier ones; for example,
-.Ql romx=42, Romx=0
-disables scrambling for
-.Cm romx .
-.Pp
-.Cm wramx
-scrambling is silently ignored if
-.Fl w
-is passed (including if implied by
-.Fl d ) ,
-as
-.Ic WRAMX
-sections will be treated as
-.Ic WRAM0 .
-.Sh EXAMPLES
-All you need for a basic ROM is an object file, which can be made into a ROM image like so:
-.Pp
-.Dl $ rgblink -o bar.gb foo.o
-.Pp
-The resulting
-.Ar bar.gb
-will not have correct checksums (unless you put them in the assembly source).
-You should use
-.Xr rgbfix 1
-to fix these so that the program will actually run in a Game Boy:
-.Pp
-.Dl $ rgbfix -v bar.gb
-.Pp
-Here is a more complete example:
-.Pp
-.Dl $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o
-.Sh BUGS
-Please report bugs on
-.Lk https://github.com/gbdev/rgbds/issues GitHub .
-.Sh SEE ALSO
-.Xr rgbasm 1 ,
-.Xr rgblink 5 ,
-.Xr rgbfix 1 ,
-.Xr rgbds 5 ,
-.Xr rgbds 7
-.Sh HISTORY
-.Nm
-was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
-It is now maintained by a number of contributors at
-.Lk https://github.com/gbdev/rgbds .
--- a/src/link/rgblink.5
+++ /dev/null
@@ -1,90 +1,0 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.Dd March 28, 2021
-.Dt RGBLINK 5
-.Os
-.Sh NAME
-.Nm rgblink
-.Nd linker script file format
-.Sh DESCRIPTION
-The linker script is an external file that allows the user to specify the order of sections at link time and in a centralized manner.
-.Pp
-A linker script consists on a series of banks followed by a list of sections and, optionally, commands.
-They can be lowercase or uppercase, it is ignored.
-Any line can contain a comment starting with
-.Ql \&;
-that ends at the end of the line:
-.Bd -literal -offset indent
-ROMX $F ; This is a comment
- "Functions to read array"
- ALIGN 8
- "Array aligned to 256 bytes"
-
-WRAMX 2
- "Some variables"
-.Ed
-.Pp
-Numbers can be in decimal or hexadecimal format
-.Pq the prefix is Ql $ .
-It is an error if any section name or command is found before setting a bank.
-.Pp
-Files can be included by using the
-.Ic INCLUDE
-keyword, followed by a string with the path of the file that has to be included.
-.Pp
-The possible bank types are:
-.Cm ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM
-and
-.Cm HRAM .
-Unless there is a single bank, which can occur with types
-.Cm ROMX , VRAM , SRAM
-and
-.Cm WRAMX ,
-it is needed to specify a bank number after the type.
-.Pp
-When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
-If the linker script switches to a different bank and then comes back to a previous one, it will continue from the last address that was used.
-.Pp
-The only two commands are
-.Ic ORG
-and
-.Ic ALIGN :
-.Bl -bullet
-.It
-.Ic ORG
-sets the address in which new sections will be placed.
-It can not be lower than the current address.
-.It
-.Ic ALIGN
-will increase the address until it is aligned to the specified boundary
-.Po it tries to set to 0 the number of bits specified after the command:
-.Ql ALIGN 8
-will align to $100
-.Pc .
-.El
-.Pp
-.Sy Note:
-The bank, alignment, address and type of sections can be specified both in the source code and in the linker script.
-For a section to be able to be placed with the linker script, the bank, address and alignment must be left unassigned in the source code or be compatible with what is specified in the linker script.
-For example,
-.Ql ALIGN[8]
-in the source code is compatible with
-.Ql ORG $F00
-in the linker script.
-.Sh SEE ALSO
-.Xr rgbasm 1 ,
-.Xr rgblink 1 ,
-.Xr rgbfix 1 ,
-.Xr rgbds 5 ,
-.Xr rgbds 7
-.Sh HISTORY
-.Nm
-was originally written by Carsten S\(/orensen as part of the ASMotor package,
-and was later packaged in RGBDS by Justin Lloyd.
-It is now maintained by a number of contributors at
-.Lk https://github.com/gbdev/rgbds .
--- a/src/rgbds.5
+++ /dev/null
@@ -1,275 +1,0 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.Dd March 28, 2021
-.Dt RGBDS 5
-.Os
-.Sh NAME
-.Nm rgbds
-.Nd object file format documentation
-.Sh DESCRIPTION
-This is the description of the object files used by
-.Xr rgbasm 1
-and
-.Xr rgblink 1 .
-.Em Please note that the specifications may change .
-This toolchain is in development and new features may require adding more information to the current format, or modifying some fields, which would break compatibility with older versions.
-.Sh FILE STRUCTURE
-The following types are used:
-.Pp
-.Ar LONG
-is a 32-bit integer stored in little-endian format.
-.Ar BYTE
-is an 8-bit integer.
-.Ar STRING
-is a 0-terminated string of
-.Ar BYTE .
-.Bd -literal
-; Header
-
-BYTE ID[4] ; "RGB9"
-LONG RevisionNumber ; The format's revision number this file uses.
-LONG NumberOfSymbols ; The number of symbols used in this file.
-LONG NumberOfSections ; The number of sections used in this file.
-
-; File info
-
-LONG NumberOfNodes ; The number of nodes contained in this file.
-
-REPT NumberOfNodes ; IMPORTANT NOTE: the nodes are actually written in
- ; **reverse** order, meaning the node with ID 0 is
- ; the last one in the file!
-
- LONG ParentID ; ID of the parent node, -1 means this is the root.
-
- LONG ParentLineNo ; Line at which the parent context was exited.
- ; Meaningless on the root node.
-
- BYTE Type ; 0 = REPT node
- ; 1 = File node
- ; 2 = Macro node
-
- IF Type != 0 ; If the node is not a REPT...
-
- STRING Name ; The node's name: either a file name, or macro name
- ; prefixed by its definition file name.
-
- ELSE ; If the node is a REPT, it also contains the iter
- ; counts of all the parent REPTs.
-
- LONG Depth ; Size of the array below.
-
- LONG Iter[Depth] ; The number of REPT iterations by increasing depth.
-
- ENDC
-
-ENDR
-
-; Symbols
-
-REPT NumberOfSymbols ; Number of symbols defined in this object file.
-
- STRING Name ; The name of this symbol. Local symbols are stored
- ; as "Scope.Symbol".
-
- BYTE Type ; 0 = LOCAL symbol only used in this file.
- ; 1 = IMPORT this symbol from elsewhere
- ; 2 = EXPORT this symbol to other objects.
-
- IF (Type & 0x7F) != 1 ; If symbol is defined in this object file.
-
- LONG SourceFile ; File where the symbol is defined.
-
- LONG LineNum ; Line number in the file where the symbol is defined.
-
- LONG SectionID ; The section number (of this object file) in which
- ; this symbol is defined. If it doesn't belong to any
- ; specific section (like a constant), this field has
- ; the value -1.
-
- LONG Value ; The symbols value. It's the offset into that
- ; symbol's section.
-
- ENDC
-
-ENDR
-
-; Sections
-
-REPT NumberOfSections
- STRING Name ; Name of the section
-
- LONG Size ; Size in bytes of this section
-
- BYTE Type ; 0 = WRAM0
- ; 1 = VRAM
- ; 2 = ROMX
- ; 3 = ROM0
- ; 4 = HRAM
- ; 5 = WRAMX
- ; 6 = SRAM
- ; 7 = OAM
- ; Bits 7 and 6 are independent from the above value:
- ; Bit 7 encodes whether the section is unionized
- ; Bit 6 encodes whether the section is a fragment
- ; Bits 6 and 7 may not be both set at the same time!
-
- LONG Org ; Address to fix this section at. -1 if the linker should
- ; decide (floating address).
-
- LONG Bank ; Bank to load this section into. -1 if the linker should
- ; decide (floating bank). This field is only valid for ROMX,
- ; VRAM, WRAMX and SRAM sections.
-
- BYTE Align ; Alignment of this section, as N bits. 0 when not specified.
-
- LONG Ofs ; Offset relative to the alignment specified above.
- ; Must be below 1 << Align.
-
- IF (Type == ROMX) || (Type == ROM0) ; Sections that can contain data.
-
- BYTE Data[Size] ; Raw data of the section.
-
- LONG NumberOfPatches ; Number of patches to apply.
-
- REPT NumberOfPatches
-
- LONG SourceFile ; ID of the source file node (for printing
- ; error messages).
-
- LONG LineNo ; Line at which the patch was created.
-
- LONG Offset ; Offset into the section where patch should
- ; be applied (in bytes).
-
- LONG PCSectionID ; Index within the file of the section in which
- ; PC is located.
- ; This is usually the same section that the
- ; patch should be applied into, except e.g.
- ; with LOAD blocks.
-
- LONG PCOffset ; PC's offset into the above section.
- ; Used because the section may be floating, so
- ; PC's value is not known to RGBASM.
-
- BYTE Type ; 0 = BYTE patch.
- ; 1 = little endian WORD patch.
- ; 2 = little endian LONG patch.
- ; 3 = JR offset value BYTE patch.
-
- LONG RPNSize ; Size of the buffer with the RPN.
- ; expression.
-
- BYTE RPN[RPNSize] ; RPN expression. Definition below.
-
- ENDR
-
- ENDC
-
-ENDR
-
-; Assertions
-
-LONG NumberOfAssertions
-
-REPT NumberOfAssertions
-
- LONG SourceFile ; ID of the source file node (for printing the failure).
-
- LONG LineNo ; Line at which the assertion was created.
-
- LONG Offset ; Offset into the section where the assertion is located.
-
- LONG SectionID ; Index within the file of the section in which PC is
- ; located, or -1 if defined outside a section.
-
- LONG PCOffset ; PC's offset into the above section.
- ; Used because the section may be floating, so PC's value
- ; is not known to RGBASM.
-
- BYTE Type ; 0 = Prints the message but allows linking to continue
- ; 1 = Prints the message and evaluates other assertions,
- ; but linking fails afterwards
- ; 2 = Prints the message and immediately fails linking
-
- LONG RPNSize ; Size of the RPN expression's buffer.
-
- BYTE RPN[RPNSize] ; RPN expression, same as patches. Assert fails if == 0.
-
- STRING Message ; A message displayed when the assert fails. If set to
- ; the empty string, a generic message is printed instead.
-
-ENDR
-.Ed
-.Ss RPN DATA
-Expressions in the object file are stored as RPN.
-This is an expression of the form
-.Dq 2 5 + .
-This will first push the value
-.Do 2 Dc to the stack, then
-.Dq 5 .
-The
-.Do + Dc operator pops two arguments from the stack, adds them, and then pushes the result on the stack, effectively replacing the two top arguments with their sum.
-In the RGB format, RPN expressions are stored as
-.Ar BYTE Ns s
-with some bytes being special prefixes for integers and symbols.
-.Bl -column -offset indent "Sy String" "Sy String"
-.It Sy Value Ta Sy Meaning
-.It Li $00 Ta Li + operator
-.It Li $01 Ta Li - operator
-.It Li $02 Ta Li * operator
-.It Li $03 Ta Li / operator
-.It Li $04 Ta Li % operator
-.It Li $05 Ta Li unary -
-.It Li $06 Ta Li ** operator
-.It Li $10 Ta Li \&| operator
-.It Li $11 Ta Li & operator
-.It Li $12 Ta Li ^ operator
-.It Li $13 Ta Li unary ~
-.It Li $21 Ta Li && comparison
-.It Li $22 Ta Li || comparison
-.It Li $23 Ta Li unary \&!
-.It Li $30 Ta Li == comparison
-.It Li $31 Ta Li != comparison
-.It Li $32 Ta Li > comparison
-.It Li $33 Ta Li < comparison
-.It Li $34 Ta Li >= comparison
-.It Li $35 Ta Li <= comparison
-.It Li $40 Ta Li << operator
-.It Li $41 Ta Li >> operator
-.It Li $42 Ta Li >>> operator
-.It Li $50 Ta Li BANK(symbol) ,
-a
-.Ar LONG
-Symbol ID follows, where -1 means PC
-.It Li $51 Ta Li BANK(section_name) ,
-a null-terminated string follows.
-.It Li $52 Ta Li Current BANK()
-.It Li $53 Ta Li SIZEOF(section_name) ,
-a null-terminated string follows.
-.It Li $54 Ta Li STARTOF(section_name) ,
-a null-terminated string follows.
-.It Li $60 Ta Li HRAMCheck .
-Checks if the value is in HRAM, ANDs it with 0xFF.
-.It Li $61 Ta Li RSTCheck .
-Checks if the value is a RST vector, ORs it with 0xC7.
-.It Li $80 Ta Ar LONG
-integer follows.
-.It Li $81 Ta Ar LONG
-symbol ID follows.
-.El
-.Sh SEE ALSO
-.Xr rgbasm 1 ,
-.Xr rgblink 1 ,
-.Xr rgbds 7 ,
-.Xr gbz80 7
-.Sh HISTORY
-.Nm
-was originally written by Carsten S\(/orensen as part of the ASMotor package,
-and was later packaged in RGBDS by Justin Lloyd.
-It is now maintained by a number of contributors at
-.Lk https://github.com/gbdev/rgbds .
--- a/src/rgbds.7
+++ /dev/null
@@ -1,57 +1,0 @@
-.\"
-.\" This file is part of RGBDS.
-.\"
-.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.Dd March 28, 2021
-.Dt RGBDS 7
-.Os
-.Sh NAME
-.Nm rgbds
-.Nd Rednex Game Boy Development System
-.Sh EXAMPLES
-To get a working ROM image from a single assembly source file:
-.Bd -literal -offset indent
-$ rgbasm \-o bar.o foo.asm
-$ rgblink \-o baz.gb bar.o
-$ rgbfix \-v \-p 0 baz.gb
-.Ed
-Or in a single command line:
-.Bd -literal -offset indent
-$ rgbasm \-o - foo.asm | rgblink \-o - - | rgbfix \-v \-p 0 - > baz.gb
-.Ed
-.Sh SEE ALSO
-.Xr rgbasm 1 ,
-.Xr rgbfix 1 ,
-.Xr rgblink 1 ,
-.Xr rgbds 5 ,
-.Xr gbz80 7
-.Sh HISTORY
-.Bl -item
-.It
-1997, Carsten S\(/orensen (AKA SurfSmurf) writes ASMotor as a general-purpose
-assembler/linker system for DOS/Win32.
-.It
-1999, Justin Lloyd (AKA Otaku no Zoku) adapts ASMotor to read and produce GBZ80
-assembly/machine code, and releases this version as RGBDS.
-.It
-2009, Vegard Nossum adapts the code to be more UNIX-like and releases this
-version as rgbds-linux on GitHub.
-.It
-2010, Anthony J. Bentley forks that repository.
-The fork becomes the reference implementation of rgbds.
-.It
-2017, Bentley's repository is moved to a neutral name.
-It is now maintained by a number of contributors at
-.Lk https://github.com/rednex/rgbds .
-.It
-2018, codebase relicensed under the MIT license.
-.It
-2020, repository is moved to the gbdev organisation, at
-.Lk https://github.com/gbdev/rgbds .
-The
-.Lk https://rgbds.gbdev.io
-website serving documentation and downloads is created.
-.El