ref: f26cfa2d94171225a912ec6b8e067f960b071965
parent: d3328406a2d2baf1365e1a9f8503c31f1f725384
parent: b81faeccfa9a47cce998d570a664defe65b33aef
author: Eldred Habert <[email protected]>
date: Tue Jan 7 17:44:58 EST 2020
Merge pull request #455 from ISSOtm/man Overhaul RGBDS man pages and help messages
--- a/src/asm/main.c
+++ b/src/asm/main.c
@@ -268,10 +268,20 @@
static void print_usage(void)
{- printf(
-"usage: rgbasm [-EhLVvw] [-b chars] [-Dname[=value]] [-g chars] [-i path]\n"
-" [-M dependfile] [-o outfile] [-p pad_value]\n"
-" [-r recursion_depth] [-W warning] [-w] file.asm\n");
+ fputs(
+"Usage: rgbasm [-EhLVvw] [-b chars] [-D name[=value]] [-g chars] [-i path]\n"
+" [-M depend_file] [-o out_file] [-p pad_value] [-r depth]\n"
+" [-W warning] <file> ...\n"
+"Useful options:\n"
+" -E, --export-all export all labels\n"
+" -M, --dependfile <path> set the output dependency file\n"
+" -o, --output <path> set the output object file\n"
+" -p, --pad-value <value> set the value to use for `ds'\n"
+" -V, --version print RGBASM version and exit\n"
+" -W, --warning <warning> enable or disable warnings\n"
+"\n"
+"For help, use `man rgbasm' or go to https://rednex.github.io/rgbds/\n",
+ stderr);
exit(1);
}
@@ -293,9 +303,6 @@
if (!cldefines)
fatalerror("No memory for command line defines");- if (argc == 1)
- print_usage();
-
/* yydebug=1; */
nMaxRecursionDepth = 64;
@@ -402,8 +409,10 @@
DefaultOptions = CurrentOptions;
- if (argc == 0)
+ if (argc == 0) {+ fputs("FATAL: no input files\n", stderr);print_usage();
+ }
tzMainfile = argv[argc - 1];
--- a/src/asm/rgbasm.1
+++ b/src/asm/rgbasm.1
@@ -7,26 +7,27 @@
.\"
.Dd July 8, 2019
.Dt RGBASM 1
-.Os RGBDS Manual
+.Os
.Sh NAME
.Nm rgbasm
.Nd Game Boy assembler
.Sh SYNOPSIS
-.Nm rgbasm
+.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 dependfile
-.Op Fl o Ar outfile
+.Op Fl M Ar depend_file
+.Op Fl o Ar out_file
.Op Fl p Ar pad_value
.Op Fl r Ar recursion_depth
-.Ar file
+.Op Fl W Ar warning
+.Ar
.Sh DESCRIPTION
The
.Nm
-program creates an object file from an assembly source file.
+program creates an RGB object file from an assembly source file.
The input
.Ar file
can be a file path, or
@@ -33,63 +34,161 @@
.Cm \-
denoting
.Cm stdin .
-Its arguments are as follows:
+.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
+.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 Op = Ns Ar value
-Add string symbol to the compiled source code. This is equivalent to
-.Ar name
-.Cm EQUS
-.Qq Ar "value"
-in code. If a value is not specified, a value of 1 is given.
-.It Fl E
+.It Fl D Ar name Ns Oo = Ns Ar value Oc , Fl Fl define Ar name Ns Oo = Ns Ar value Oc
+Add a string symbol to the compiled source code.
+This is equivalent to
+.Ql Ar name Ic EQUS Qq Ar value
+in code, or
+.Ql Ar name Ic EQUS Qq 1
+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
-Change the four characters used for binary constants.
+.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
+.It Fl h , Fl Fl halt-without-nop
By default,
.Nm
inserts a
-.Sq nop
+.Ic nop
instruction immediately after any
-.Sq halt
+.Ic halt
instruction.
The
.Fl h
option disables this behavior.
-.It Fl i Ar path
+.It Fl i Ar path , Fl Fl include Ar path
Add an include path.
-.It Fl L
+.It Fl L , Fl Fl preserve-ld
Disable the optimization that turns loads of the form
-.Sy LD [$FF00+n8],A
+.Ic LD [$FF00+n8],A
into the opcode
-.Sy LDH [$FF00+n8],A
+.Ic LDH [$FF00+n8],A
in order to have full control of the result in the final ROM.
-.It Fl M Ar dependfile
+.It Fl M Ar depend_file , Fl Fl dependfile Ar depend_file
.Xr make 1
dependencies to
-.Ar dependfile .
-.It Fl o Ar outfile
+.Ar depend_file .
+.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
+.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
+.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
+.It Fl V , Fl Fl version
Print the version of the program and exit.
-.It Fl v
+.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 warning output.
+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 Wempty-entry
+enables the warning that Fl Wno-empty-entry
+disables).
+Only the non-default flag is listed here.
+Ignoring the
+.Dq no-
+prefix, entries are listed alphabetically.
+.Bl -tag -width Ds
+.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 Wdiv
+Warn when dividing the smallest negative integer by -1, which yields itself due to integer overflow.
+.It Fl Wempty-entry
+Warn when an empty entry is encountered in a
+.Ic db , dw , dl
+list.
+This warning is enabled by
+.Fl Wextra .
+.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 Wobsolete
+Warn when obsolete constructs such as the
+.Ic jp [hl]
+instruction or
+.Cm HOME
+section type are encountered.
+This warning is enabled by
+.Fl Wextra .
+.It Fl Wshift
+Warn when shifting triggers C undefined behavior, potentially causing unpredictable behavior.
+Shfting behavior will be changed and this warning removed before next release.
+.It Fl Wno-user
+Warns when the built-in function
+.Fn WARN
+is executed.
+.El
.Sh EXAMPLES
You can assemble a source file in two ways.
-Straight forward way:
+Straightforward way:
.Pp
.Bd -literal -offset indent
$ rgbasm -o bar.o foo.asm
@@ -102,11 +201,13 @@
$ rgbasm -o bar.o - < foo.asm
.Ed
.Pp
-The resulting object file is not yet a usable ROM image \(em it must first be
-run through
+The resulting object file is not yet a usable ROM image \(em it must first be run through
.Xr rgblink 1
-and
+and then
.Xr rgbfix 1 .
+.Sh BUGS
+Please report bugs on
+.Lk https://github.com/rednex/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbasm 5 ,
.Xr rgbfix 1 ,
@@ -116,7 +217,6 @@
.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
+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/rednex/rgbds .
--- a/src/asm/rgbasm.5
+++ b/src/asm/rgbasm.5
@@ -5,9 +5,9 @@
.\"
.\" SPDX-License-Identifier: MIT
.\"
-.Dd March 13, 2018
+.Dd December 5, 2019
.Dt RGBASM 5
-.Os RGBDS Manual
+.Os
.Sh NAME
.Nm rgbasm
.Nd language documentation
@@ -14,15 +14,14 @@
.Sh DESCRIPTION
This is the full description of the language used by
.Xr rgbasm 1 .
-The description of the instructions supported by the GameBoy CPU is in
+The description of the instructions supported by the Game Boy CPU is in
.Xr gbz80 7 .
.Pp
.Sh GENERAL
.Ss Syntax
-The syntax is line‐based, just as in any other assembler, meaning that you do
-one instruction or pseudo‐op per line:
+The syntax is line‐based, just as in any other assembler, meaning that you do one instruction or pseudo‐op per line:
.Pp
-.Dl Oo Ar label Oc Oo Ar instruction Oc Oo Ar \&;comment Oc
+.Dl Oo Ar label Oc Oo Ar instruction Oc Oo Ar ;\ comment Oc
.Pp
Example:
.Pp
@@ -37,11 +36,10 @@
In both cases, a comment ends at the end of the line.
The most common one is: anything that follows a semicolon
.Ql \&;
-(that isn't inside a string) is a comment.
+that isn't inside a string is a comment.
There is another format: anything that follows a
.Ql *
-that is placed right at the start of
-a line is a comment.
+that is placed right at the start of a line is a comment.
The assembler removes all comments from the code before doing anything else.
.Pp
Sometimes lines can be too long and it may be necessary to split them.
@@ -58,7 +56,7 @@
like this:
.Pp
.Bd -literal -offset indent
- DB STRCAT("Hello ", \[rs]+ db STRCAT("Hello ", \[rs]"world!")
.Ed
.Pp
@@ -72,17 +70,13 @@
.Ic SECTION Ar name , type Ns Bo Ar addr Bc , Ar options
.Pp
Before you can start writing code, you must define a section.
-This tells the assembler what kind of information follows and, if it is code,
-where to put it.
+This tells the assembler what kind of information follows and, if it is code, where to put it.
.Pp
.Ar name
-is a string enclosed in double quotes and can be a new name or the name of an
-existing section.
-All sections assembled at the same time that have the same name and type are
-considered to be the same section, and their code is put together in the object
-file generated by the assembler.
-All other sections must have a unique name, even in different source files, or
-the linker will treat it as an error.
+is a string enclosed in double quotes and can be a new name or the name of an existing section.
+All sections assembled at the same time that have the same name are considered to be the same section, and their code is put together in the object file generated by the assembler.
+If the type doesn't match, an error occurs.
+All other sections must have a unique name, even in different source files, or the linker will treat it as an error.
.Pp
Possible section
.Ar type Ns s
@@ -92,12 +86,23 @@
.It Cm ROM0
A ROM section.
.Ar addr
-can range from $0000–$3FFF (or $0000–$7FFF if tiny ROM mode is enabled in
-.Xr rgblink 1 ) .
+can range from
+.Ad $0000
+to
+.Ad $3FFF ,
+or
+.Ad $0000
+to
+.Ad $7FFF
+if tiny ROM mode is enabled in
+.Xr rgblink 1 .
.It Cm ROMX
A banked ROM section.
.Ar addr
-can range from $4000–$7FFF.
+can range from
+.Ad $4000
+to
+.Ad $7FFF .
.Ar bank
can range from 1 to 511.
Not available if tiny ROM mode is enabled in
@@ -105,7 +110,10 @@
.It Cm VRAM
A banked video RAM section.
.Ar addr
-can range from $8000–$9FFF.
+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
.Xr rgblink 1 .
@@ -115,7 +123,10 @@
.It Cm SRAM
A banked external (save) RAM section.
.Ar addr
-can range from $A000–$BFFF.
+can range from
+.Ad $A000
+to
+.Ad $BFFF .
.Ar bank
can range from 0 to 15.
Memory in this section can only be allocated with
@@ -124,7 +135,15 @@
.It Cm WRAM0
A general-purpose RAM section.
.Ar addr
-can range from $C000–$CFFF, or $C000–$DFFF if DMG mode is enabled in
+can range from
+.Ad $C000
+to
+.Ad $CFFF ,
+or
+.Ad $C000
+to
+.Ad $DFFF
+if DMG mode is enabled in
.Xr rgblink 1 .
Memory in this section can only be allocated with
.Sy DS ,
@@ -132,18 +151,24 @@
.It Cm WRAMX
A banked general-purpose RAM section.
.Ar addr
-can range from $D000–$DFFF.
+can range from
+.Ad $D000
+to
+.Ad $DFFF .
.Ar bank
can range from 1 to 7.
+Not available if DMG mode is enabled in
+.Xr rgblink 1 .
Memory in this section can only be allocated with
.Sy DS ,
not filled with data.
-Not available if DMG mode is enabled in
-.Xr rgblink 1 .
.It Cm OAM
-An object attributes RAM section.
+An object attribute RAM section.
.Ar addr
-can range from $FE00-$FE9F.
+can range from
+.Ad $FE00
+to
+.Ad $FE9F .
Memory in this section can only be allocated with
.Sy DS ,
not filled with data.
@@ -150,7 +175,10 @@
.It Cm HRAM
A high RAM section.
.Ar addr
-can range from $FF80–$FFFE.
+can range from
+.Ad $FF80
+to
+.Ad $FFFE.
Memory in this section can only be allocated with
.Sy DS ,
not filled with data.
@@ -159,9 +187,9 @@
If you use this method of allocating HRAM the assembler will
.Em not
choose the short addressing mode in the LD instructions
-.Sy LD [$FF00+n8],A
+.Ic ld [$FF00+n8],A
and
-.Sy LD A,[$FF00+n8]
+.Ic ld A,[$FF00+n8]
because the actual address calculation is done by the linker.
If you find this undesirable you can use
.Ic RSSET , RB ,
@@ -168,19 +196,14 @@
or
.Ic RW
instead or use the
-.Sy LDH [$FF00+n8],A
+.Sy ldh [$FF00+n8],A
and
-.Sy LDH A,[$FF00+n8]
+.Sy ldh A,[$FF00+n8]
syntax instead.
-This forces the assembler to emit the correct instruction and the linker to
-check if the value is in the correct range.
-This optimization can be disabled by passing the
-.Fl L
-flag to
-.Xr rgbasm 1 .
+This forces the assembler to emit the correct instruction and the linker to check if the value is in the correct range.
.El
.Pp
-.Ar option Ns s are comma separated and may include:
+.Ar option Ns s are comma-separated and may include:
.Bl -tag
.It Cm BANK Ns Bq Ar bank
Specify which
@@ -203,13 +226,11 @@
.Cm 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 linkerscript file.
+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.
+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:
.Bd -literal -offset indent
@@ -239,8 +260,7 @@
SECTION "CoolStuff",ROMX[$4567],BANK[3]
.Ed
.Pp
-And if you only want to force the section into a certain bank, and not it's
-position within the bank, that's also possible:
+And if you only want to force the section into a certain bank, and not its position within the bank, that's also possible:
.Pp
.Bd -literal -offset indent
SECTION "CoolStuff",ROMX,BANK[7]
@@ -247,8 +267,7 @@
.Ed
.Pp
Alignment examples:
-one use could be when using DMA to copy data or when it is needed to align the
-start of an array to 256 bytes to optimize the code that accesses it.
+one use could be when using DMA to copy data or when it is needed to align the start of an array to 256 bytes to optimize the code that accesses it.
.Pp
.Bd -literal -offset indent
SECTION "OAM Data",WRAM0,ALIGN[8] ; align to 256 bytes
@@ -262,9 +281,8 @@
type thing you can quite easily write an intelligent macro (called
.Ic ORG
for example) that uses
-.Ic @
-for the section name and determines
-correct section type etc as arguments for
+.Ic \[rs]@
+for the section name, and determines the correct section type etc. as arguments for
.Ic SECTION .
.Ss Section Stack
.Ic POPS
@@ -276,10 +294,8 @@
will push the current section context on the section stack.
.Ic POPS
can then later be used to restore it.
-Useful for defining sections in included files when you don't want to destroy
-the section context for the program that included your file.
-The number of entries in the stack is limited only by the amount of memory in
-your machine.
+Useful for defining sections in included files when you don't want to destroy the section context for the program that included your file.
+The number of entries in the stack is limited only by the amount of memory in your machine.
.Sh SYMBOLS
.Pp
.Ss Symbols
@@ -287,20 +303,19 @@
.Pp
.Bl -hang
.It Sy Label
-Used to assign a memory location with a name
+Used to give a name to a memory location.
.It Sy EQUate
Give a constant a name.
-.It Sy SET
-Almost the same as EQUate, but you can change the value of a SET during
-assembling.
-.It Sy Structure Po Sy the RS group Pc
+.It Ic SET
+Almost the same as EQUate, but you can change the value of a SET during assembling.
+.It Sy Structure Pq Sy the RS group
Define a structure easily.
-.It Sy String equate Pq Sy EQUS
+.It Sy String equate Pq Ic EQUS
Give a frequently used string a name.
Can also be used as a mini-macro, like
.Fd #define
in C.
-.It Sy MACRO
+.It Ic MACRO
A block of code or pseudo instructions that you invoke like any other mnemonic.
You can give them arguments too.
.El
@@ -309,9 +324,7 @@
.Bl -hang
.It Sy Label
.Pp
-One of the assembler's main tasks is to keep track of addresses for you so you
-don't have to remember obscure numbers but can make do with a meaningful name, a
-label.
+One of the assembler's main tasks is to keep track of addresses for you so you don't have to remember obscure numbers but can make do with a meaningful name: a label.
.Pp
This can be done in a number of ways:
.Pp
@@ -325,11 +338,19 @@
ThisWillBeExported.too::
.Ed
.Pp
-In the line where a label is defined there musn't be any whitespace before it.
+.Em \&In the line where a label is defined there mustn't be any whitespace before it .
Local labels are only accessible within the scope they are defined.
A scope starts after a global label and ends at the next global label.
-Declaring a label (global or local) with :: does an EXPORT at the same time.
-Local labels can be declared as scope.local or simply as as .local.
+Declaring a label (global or local) with :: does an
+.Ic EXPORT
+at the same time.
+(See
+.Sx Exporting and importing symbols
+below).
+Local labels can be declared as
+.Ql scope.local
+or simply as as
+.Ql .local .
If the former notation is used, the scope must be the actual current scope.
.Pp
Labels will normally change their value during the link process and are thus not
@@ -337,30 +358,27 @@
The exception is the case in which the base address of a section is fixed, so
the address of the label is known at assembly time.
.Pp
-The subtraction of two labels is only constant (known at assembly time) if they
-are two local labels that belong to the same scope, or they are two global
-labels that belong to sections with fixed base addresses.
+The subtraction of two labels is only constant (known at assembly time) if they are two local labels that belong to the same scope, or they are two global labels that belong to sections with fixed base addresses.
.Pp
-.It Sy EQU
+.It Ic EQU
.Pp
-EQUates are constant symbols.
-They can, for example, be used for things such as bit-definitions of hardware
-registers.
+EQUates are constant symbols, and can be imported or exported.
+They can, for example, be used for things such as bit definitions of hardware registers.
.Pp
.Bd -literal -offset indent
-EXIT_OK EQU $00
-EXIT_FAILURE EQU $01
+SCREEN_WIDTH equ 160 ; In pixels
+SCREEN_HEIGHT equ 144
.Ed
.Pp
-Note that a colon (:) following the label-name is not allowed.
-EQUates cannot be exported and imported.
+Note that a colon
+.Ql \&:
+following the name is not allowed.
They don't change their value during the link process.
.It Sy SET
.Pp
-SETs are similar to EQUates.
-They are also constant symbols in the sense that their values are defined during
-the assembly process.
-These symbols are normally used in macros.
+SETs are similar to EQUates, and can be imported and exported as well.
+They are also constant symbols in the sense that their values are defined during the assembly process.
+These symbols are typically used in macros.
.Pp
.Bd -literal -offset indent
ARRAY_SIZE EQU 4
@@ -368,9 +386,12 @@
COUNT SET ARRAY_SIZE+COUNT
.Ed
.Pp
-Note that a colon (:) following the label-name is not allowed.
-SETs cannot be exported and imported.
-Alternatively you can use = as a synonym for SET.
+Note that a colon
+.Ql \&:
+following the name is not allowed.
+Alternatively you can use
+.Ql =
+as a synonym for SET.
.Pp
.Bd -literal -offset indent
COUNT = 2
@@ -401,28 +422,27 @@
.Pp
.Bl -column "RSSET constexpr"
.It Sy Command Ta Sy Meaning
-.It Ic RSRESET Ta Resets the _RS counter to zero.
-.It Ic RSSET Ar constexpr Ta Sets the
-.Ic _RS No counter to Ar constexpr .
-.It Ic RB Ar constexpr Ta Sets the preceding symbol to
-.Ic _RS No and adds Ar constexpr No to Ic _RS .
-.It Ic RW Ar constexpr Ta Sets the preceding symbol to
-.Ic _RS No and adds Ar constexpr No * 2 to Ic _RS.
-.It Ic RL Ar constexpr Ta Sets the preceding symbol to
-.Ic _RS No and adds Ar constexpr No * 4 to Ic _RS.
+.It Ic RSRESET Ta Resets the Ic _RS No counter to zero.
+.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.
+(In practice, this one cannot be used due to a bug).
.El
.Pp
-Note that a colon (:) following the symbol-name is not allowed.
+Note that a colon
+.Ql \&:
+following the name is not allowed.
.Sy RS
-symbols cannot be exported and imported.
+symbols can be exported and imported.
They don't change their value during the link process.
.Pp
-.It Sy EQUS
+.It Ic EQUS
.Pp
-EQUS is used to define string-symbols.
-Wherever the assembler meets a string symbol its name is replaced with its
-value.
-If you are familiar with C you can think of it as the same as
+.Ic EQUS
+is used to define string symbols.
+Wherever the assembler meets a string symbol its name is replaced with its value.
+If you are familiar with C you can think of it as similar to
.Fd #define .
.Pp
.Bd -literal -offset indent
@@ -433,9 +453,6 @@
db PLAYER_NAME
.Ed
.Pp
-Note that : following the label-name is not allowed, and that strings must be
-quoted to be useful.
-.Pp
This will be interpreted as:
.Pp
.Bd -literal -offset indent
@@ -443,27 +460,41 @@
db "John"
.Ed
.Pp
-String-symbols can also be used to define small one-line macros:
+String symbols can also be used to define small one-line macros:
.Pp
.Bd -literal -offset indent
PUSHA EQUS "push af\[rs]npush bc\[rs]npush de\[rs]npush hl\[rs]n"
.Ed
.Pp
-Note that a colon (:) following the label-name is not allowed.
+Note that a colon
+.Ql \&:
+following the name is not allowed.
String equates can't be exported or imported.
.Pp
.Sy Important note :
-An EQUS can be expanded to a string that contains another EQUS
+An
+.Ic EQUS
+can be expanded to a string that contains another
+.Ic EQUS
and it will be expanded as well.
-If this creates an infinite loop, RGBASM will error out once a certain depth is reached. See the -r command-line option.
-Also, a MACRO can have inside an EQUS which references the same MACRO, which has
-the same problem.
+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
+.Ic EQUS
+which references the same macro, which has the same problem.
.Pp
-.It Sy MACRO
+.It Ic MACRO
.Pp
One of the best features of an assembler is the ability to write macros for it.
-Macros also provide a method of passing arguments to them and they can then
-react to the input using IF-constructs.
+Macros also provide a method of passing arguments to them and they can then react to the input using
+.Sy IF
+constructs.
.Pp
.Bd -literal -offset indent
MyMacro: MACRO
@@ -472,7 +503,9 @@
ENDM
.Ed
.Pp
-Note that a colon (:) following the macro-name is required.
+Note that a colon
+.Ql \&:
+following the macro's name is required.
Macros can't be exported or imported.
It's valid to call a macro from a macro (yes, even the same one).
.Pp
@@ -486,12 +519,23 @@
sub a,87
.Ed
.Pp
-When the assembler meets MyMacro it will insert the macrodefinition (the text
-enclosed in
+When the assembler meets MyMacro it will insert the macro definition (the code enclosed in
.Ic MACRO
/
.Ic ENDM ) .
.Pp
+Line continuations work as usual inside macros or lists of arguments of macros.
+However, some characters need to be escaped, as in the following example:
+.Pp
+.Bd -literal -offset indent
+PrintMacro : MACRO
+ PRINTT \[rs]1
+ENDM
+
+ PrintMacro STRCAT("Hello"\[rs], \[rs]+ " world\[rs]\[rs]n")
+.Ed
+.Pp
Suppose your macro contains a loop.
.Pp
.Bd -literal -offset indent
@@ -500,14 +544,13 @@
\&.loop ld [hl+],a
dec c
jr nz,.loop
- ENDM
+ENDM
.Ed
.Pp
-This is fine.
-That is, if you only use the macro once per scope.
-To get around this problem there is a special label string equate called
+This is fine, but only if you use the macro no more than once per scope.
+To get around this problem there is a special string equate called
.Ic \[rs]@
-that you can append to your labels and it will then expand to a unique string.
+that you will then expand to a unique string.
.Pp
.Ic \[rs]@
also works in REPT-blocks should you have any loops there.
@@ -517,32 +560,27 @@
\&.loop\[rs]@ ld [hl+],a
dec c
jr nz,.loop\[rs]@
- ENDM
+ENDM
.Ed
.Pp
.Sy Important note :
-Since a MACRO can call itself (or a different MACRO that calls the first one)
-there can be problems of circular dependency.
-They trap the assembler in an infinite loop, so you have to be careful when
-using recursion with MACROs.
-Also, a MACRO can have inside an EQUS which references the same MACRO, which has
-the same problem.
+Since a macro can call itself (or a different macro that calls the first one), there can be circular dependency problems.
+They trap the assembler in an infinite loop, so you have to be careful when using recursion with macros.
+Also, a macro can have inside an
+.Sy EQUS
+which references the same macro, which has the same problem.
.Pp
.Sy Macro Arguments
.Pp
-I'd like LoopyMacro a lot better if I didn't have to pre-load the registers
-with values and then call it.
-What I'd like is the ability to pass it arguments and it then loaded the
-registers itself.
+I'd like LoopyMacro a lot better if I didn't have to pre-load the registers with values and then call it.
+What I'd like is the ability to pass it arguments and then it loads the registers itself.
.Pp
And I can do that.
In macros you can get the arguments by using the special macro string equates
.Ic \[rs]1
through
-.Ic \[rs]9 ,
-.Ic \[rs]1
-being the first argument
-specified on the calling of the macro.
+.Ic \[rs]9 , \[rs]1
+being the first argument specified on the calling of the macro.
.Pp
.Bd -literal -offset indent
LoopyMacro: MACRO
@@ -555,8 +593,7 @@
ENDM
.Ed
.Pp
-Now I can call the macro specifying two arguments.
-The first being the address and the second being a bytecount.
+Now I can call the macro specifying two arguments, the first being the address and the second being a byte count.
The macro will then reset all bytes in this range.
.Pp
.Bd -literal -offset indent
@@ -563,37 +600,32 @@
LoopyMacro MyVars,54
.Ed
.Pp
-Arguments are passed as string equates.
-There's no need to enclose them in quotes.
-An expression will not be evaluated first but passed directly.
+Arguments are passed as string equates, although there's no need to enclose them in quotes.
+Thus, an expression will not be evaluated first but passed directly.
This means that it's probably a very good idea to use brackets around
.Ic \[rs]1
to
.Ic \[rs]9
if you perform further calculations on them.
-For instance, if you pass 1 + 2 as the first argument and then do
-.Ic PRINTV
-.Ic \[rs]1
-* 2
-you will get the value 5 on screen and not 6 as you might have expected.
+For instance, consider the following:
.Pp
-In reality, up to 256 arguments can be passed to a macro, but you can only use
-the first 9 like this.
-If you want to use the rest, you need to use the keyword
-.Ic SHIFT .
-.Pp
-Line continuations work as usual inside macros or lists of arguments of macros.
-However, some characters need to be escaped, as in the following example:
-.Pp
.Bd -literal -offset indent
-PrintMacro : MACRO
- PRINTT \[rs]1
+print_double: MACRO
+ PRINTV \1 * 2
ENDM
-
- PrintMacro STRCAT("Hello"\[rs], \[rs]- " world\[rs]\[rs]n")
+ print_double 1 + 2
.Ed
.Pp
+The
+.Ic PRINTV
+statement will expand to
+.Ql PRINTV 1 + 2 * 2 ,
+which will print 5 and not 6 as you might have expected.
+.Pp
+In reality, up to 256 arguments can be passed to a macro, but you can only use the first 9 like this.
+If you want to use the rest, you need to use the keyword
+.Ic SHIFT .
+.Pp
.Ic SHIFT
is a special command only available in macros.
Very useful in REPT-blocks.
@@ -600,8 +632,7 @@
It will shift the arguments by one to the left.
.Ic \[rs]1
will get the value of
-.Ic \[rs]2 ,
-.Ic \[rs]2
+.Ic \[rs]2 , \[rs]2
will get the value in
.Ic \[rs]3
and so forth.
@@ -610,34 +641,34 @@
.Pp
.El
.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.
+Importing and exporting of symbols is a feature that is very useful when your project spans many source files and, for example, you need to jump to a routine defined in another file.
.Pp
-Exporting of symbols has to be done manually, importing is done automatically
-if the assembler doesn't know where a symbol is defined.
+Exporting of symbols has to be done manually, importing is done automatically if the assembler doesn't know where a symbol is defined.
+.Bd -literal -offset indent
+.Ic EXPORT Ar symbol1 Bq , Ar symbol2 , No ...
+.Ed
.Pp
-.Ic EXPORT Ar label Bq , Ar label No , ...
+The assembler will make
+.Ar symbol1 , symbol2
+and so on accessible to other files during the link process.
+.Bd -literal -offset indent
+.Ic GLOBAL Ar symbol1 Bq , ...
+.Ed
.Pp
-The assembler will make label accessible to other files during the link process.
-.Pp
-.Ic GLOBAL Ar label Bq , Ar label No , ...
-.Pp
-If label is defined during the assembly it will be exported, if not, it will be
-imported.
-Handy (very!) for include-files.
-Note that, since importing is done automatically, this keyword has the same
-effect as
+If
+.Ar symbol
+is already defined, it will be exported, otherwise it will be imported.
+Note that, since importing is done automatically, this keyword has the same effect as
.Ic EXPORT .
+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.
-USE WITH EXTREME CAUTION!!!
+allows you to completely remove a symbol from the symbol table as if it had never existed.
+.Em USE WITH EXTREME CAUTION!!!
I can't stress this enough, you seriously need to know what you are doing.
-DON'T purge symbol that you use in expressions the linker needs to calculate.
-In fact, it's probably not even safe to purge anything other than string symbols
-and macros.
+DON'T purge a symbol that you use in expressions the linker needs to calculate.
+In fact, it's probably not even safe to purge anything other than string symbols and macros.
.Pp
.Bd -literal -offset indent
Kamikaze EQUS "I don't want to live anymore"
@@ -647,7 +678,9 @@
.Pp
Note that string symbols that are part of a
.Ic PURGE
-command WILL NOT BE EXPANDED as the ONLY exception to this rule.
+command
+.Em will not be expanded
+as the ONLY exception to the rule.
.Ss Predeclared Symbols
The following symbols are defined by the assembler:
.Pp
@@ -675,10 +708,32 @@
.El
.Pp
.Sh DEFINING DATA
+.Ss Declaring variables in a RAM section
+.Ic DS
+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
+below).
+.Pp
+.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
.Ic DB
defines a list of bytes that will be stored in the final image.
-Ideal for tables and text (which is not zero-terminated).
+Ideal for tables and text.
+Note that strings are not zero-terminated!
.Pp
.Bd -literal -offset indent
DB 1,2,3,4,"This is a string"
@@ -686,9 +741,9 @@
.Pp
Alternatively, you can use
.Ic DW
-to store a list of words (16-bits) or
+to store a list of words (16-bit) or
.Ic DL
-to store a list of doublewords/longs (32-bits).
+to store a list of double-words/longs (32-bit).
Strings are not allowed as arguments to
.Ic DW
and
@@ -695,8 +750,7 @@
.Ic DL .
.Pp
You can also use
-.Ic DB ,
-.Ic DW
+.Ic DB , DW
and
.Ic DL
without arguments, or leaving empty elements at any point in the list.
@@ -712,36 +766,26 @@
and
.Ic DL
can be used in a
-.Sy WRAM0 No / Sy WRAMX No / Sy HRAM No / Sy VRAM No / Sy SRAM
+.Cm WRAM0
+/
+.Cm WRAMX
+/
+.Cm HRAM
+/
+.Cm VRAM
+/
+.Cm SRAM
section.
-.Ss Declaring variables in a RAM section
-.Ic DS
-allocates a number of bytes.
-The content is undefined.
-This is the preferred method of allocationg space in a RAM section.
-You can, however, use
-.Ic DB ,
-.Ic DW
-and
-.Ic DL
-without any arguments instead.
-.Pp
-.Bd -literal -offset indent
-DS str_SIZEOF ;allocate str_SIZEOF bytes
-.Ed
-.Pp
.Ss Including binary files
-You probably have some graphics you'd like to include.
+You probably have some graphics, level data, etc. you'd like to include.
Use
.Ic INCBIN
to include a raw binary file as it is.
-If the file isn't found in the current directory, the include-path list passed
-to the linker on the command line will be searched.
+If the file isn't found in the current directory, the include-path list passed to the linker on the command line will be searched.
.Pp
.Bd -literal -offset indent
INCBIN "titlepic.bin"
-INCBIN "sprites/hero.bin"\ ; UNIX
-INCBIN "sprites\[rs]\[rs]hero.bin"\ ; Windows
+INCBIN "sprites/hero.bin"
.Ed
.Pp
You can also include only part of a file with
@@ -752,37 +796,38 @@
INCBIN "data.bin",78,256
.Ed
.Ss Unions
-Unions allow multiple memory allocations to share the same space in memory,
-like unions in C.
-This allows you to easily reuse memory for different purposes, depending on
-the game's state.
+Unions allow multiple memory allocations to share the same space in memory, like unions in C.
+This allows you to easily reuse memory for different purposes, depending on the game's state.
.Pp
You create unions using the
-.Ic UNION ,
-.Ic NEXTU
+.Ic UNION , NEXTU
and
.Ic ENDU
keywords.
.Ic NEXTU
-lets you create a new block of allocations, and you may use it as many times
-within a union as necessary.
+lets you create a new block of allocations, and you may use it as many times within a union as necessary.
.Pp
.Bd -literal -offset indent
-UNION
+ UNION
Name: ds 8
Nickname: ds 8
-NEXTU
+ NEXTU
Health: dw
Something: ds 3
Lives: db
-NEXTU
+ NEXTU
Temporary: ds 19
-ENDU
+ ENDU
.Ed
.Pp
This union will use up 19 bytes, as this is the size of the largest block
-(the last one, containing 'Temporary').
-Of course, as 'Name', 'Health', and 'Temporary' all point to the same memory
+.Pq the last one, containing Sq Temporary .
+Of course, as
+.Sq Name ,
+.Sq Health ,
+and
+.Sq Temporary
+all point to the same memory
locations, writes to any one of these will affect values read from the others.
.Pp
Unions may be used in any section, but code and data may not be included.
@@ -790,8 +835,7 @@
.Pp
.Ss Printing things during assembly
These three instructions type text and values to stdout.
-Useful for debugging macros or wherever you may feel the need to tell yourself
-some important information.
+Useful for debugging macros or wherever you may feel the need to tell yourself some important information.
.Pp
.Bd -literal -offset indent
PRINTT "I'm the greatest programmer in the whole wide world\[rs]n"
@@ -803,10 +847,12 @@
.Bl -inset
.It Ic PRINTT
prints out a string.
+Be careful to add a line feed
+.Pq Qq \[rs]n
+at the end, as it is not added automatically.
.It Ic PRINTV
-prints out an integer value in hexadecimal or, as in the example, the result of
-a calculation.
-Unsurprisingly, you can also print out a constant symbols value.
+prints out an integer value in hexadecimal or, as in the example, the result of a calculation.
+Unsurprisingly, you can also print out a constant symbol's value.
.It Ic PRINTI
prints out a signed integer value.
.It Ic PRINTF
@@ -813,7 +859,7 @@
prints out a fixed point value.
.El
.Ss Automatically repeating blocks of code
-Suppose you're feeling lazy and you want to unroll a time consuming loop.
+Suppose you want to unroll a time consuming loop without copy-pasting it.
.Ic REPT
is here for that purpose.
Everything between
@@ -820,10 +866,9 @@
.Ic REPT
and
.Ic ENDR
-will be repeated a number of times just as if you done a copy/paste operation
-yourself.
+will be repeated a number of times just as if you had done a copy/paste operation yourself.
The following example will assemble
-.Sy add a,c
+.Ql add a,c
four times:
.Pp
.Bd -literal -offset indent
@@ -840,30 +885,28 @@
; --
; -- Generate a 256 byte sine table with values between 0 and 128
; --
-ANGLE SET 0.0
+ANGLE = 0.0
REPT 256
- DB (MUL(64.0,SIN(ANGLE))+64.0)>>16
-ANGLE SET ANGLE+256.0
+ db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
+ANGLE = ANGLE+256.0
ENDR
.Ed
.Pp
.Ic REPT
-is also very useful in recursive macros and, as in macros, you can also use the
-special label operator
+is also very useful in recursive macros and, as in macros, you can also use the special string symbol
.Ic \[rs]@ .
-REPT-blocks can be nested.
+.Ic REPT
+blocks can be nested.
.Ss Aborting the assembly process
.Ic FAIL
and
.Ic WARN
-can be used to print errors and warnings respectively during the assembly
-process.
+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.
+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
@@ -872,9 +915,8 @@
.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 will be
-searched.
+to process another assembler file and then return to the current file when done.
+If the file isn't found in the current directory the include path list will be searched.
You may nest
.Ic INCLUDE
calls infinitely (or until you run out of memory, whichever comes first).
@@ -882,12 +924,9 @@
.Bd -literal -offset indent
INCLUDE "irq.inc"
.Ed
-.Pp
.Ss Conditional assembling
The four commands
-.Ic IF ,
-.Ic ELIF ,
-.Ic ELSE ,
+.Ic IF , ELIF , ELSE ,
and
.Ic ENDC
are used to conditionally assemble parts of your file.
@@ -908,7 +947,13 @@
and
.Ic ELSE
blocks are optional.
-.Ic IF No / Ic ELIF No / Ic ELSE No / Ic ENDC
+.Ic IF
+/
+.Ic ELIF
+/
+.Ic ELSE
+/
+.Ic ENDC
blocks can be nested.
.Pp
Note that if an
@@ -926,7 +971,7 @@
Also, if there is more than one
.Ic ELSE
block, all of them but the first one are ignored.
-.Ss Integer and Boolean expressions
+.Ss Integer and boolean expressions
An expression can be composed of many things.
Expressions are always evaluated using signed 32-bit math.
.Pp
@@ -936,27 +981,20 @@
.Pp
There are a number of numeric formats.
.Pp
-.Bl -dash -compact
-.It
-Hexadecimal: $0123456789ABCDEF.
-Case-insensitive
-.It
-Decimal: 0123456789
-.It
-Octal: &01234567
-.It
-Binary: %01
-.It
-Fixedpoint (16.16): 01234.56789
-.It
-Character constant: "ABYZ"
-.It
-Gameboy graphics: \`0123
+.Bl -column -offset indent "Fixed point (16.16)" "Prefix"
+.It Sy Format type Ta Sy Prefix Ta Sy Accepted characters
+.It Hexadecimal Ta $ Ta 0123456789ABCDEF
+.It Decimal Ta none Ta 0123456789
+.It Octal Ta & Ta 01234567
+.It Binary Ta % Ta 01
+.It Fixed point (16.16) Ta none Ta 01234.56789
+.It Character constant Ta none Ta Qq ABYZ
+.It Gameboy graphics Ta \` Ta 0123
.El
.Pp
The last one, Gameboy graphics, is quite interesting and useful.
The values are actually pixel values and it converts the
-.Do chunky Dc data to Do planar Dc data as used in the Gameboy.
+.Do chunky Dc data to Do planar Dc data as used in the Game Boy.
.Pp
.Bd -literal -offset indent
DW \`01012323
@@ -963,13 +1001,11 @@
.Ed
.Pp
Admittedly, an expression with just a single number is quite boring.
-To spice things up a bit there are a few operators you can use to perform
-calculations between numbers.
+To spice things up a bit there are a few operators you can use to perform calculations between numbers.
.Pp
.Sy Operators
.Pp
-A great number of operators you can use in expressions are available (listed in
-order of precedence):
+A great number of operators you can use in expressions are available (listed from highest to lowest precedence):
.Pp
.Bl -column -offset indent "Operator"
.It Sy Operator Ta Sy Meaning
@@ -986,36 +1022,25 @@
.It Li \&! Ta Unary Boolean not
.El
.Pp
-The result of the boolean operators is zero if when FALSE and non-zero when
-TRUE.
-It is legal to use an integer as the condition for IF blocks.
+The result of the boolean operators is zero when FALSE and non-zero when TRUE.
+It is legal to use an integer as the condition for
+.Sy IF
+blocks.
You can use symbols instead of numbers in your expression if you wish.
.Pp
-An expression is said to be constant when it doesn't change its value during
-linking.
+An expression is said to be constant when it doesn't change its value during linking.
This basically means that you can't use labels in those expressions.
-The instructions in the macro-language all require expressions that are
-constant.
-The only exception is the subtraction of labels in the same section or labels
-that belong to sections with a fixed base addresses, all of which must be
-defined in the same source file (the calculation cannot be passed to the object
-file generated by the assembler).
+The only exception is the subtraction of labels in the same section or labels that belong to sections with a fixed base addresses, all of which must be defined in the same source file (the calculation cannot be deferred to the linker).
In this case, the result is a constant that can be calculated at assembly time.
+The instructions in the macro-language all require expressions that are constant.
.Pp
.Ss Fixed‐point Expressions
-Fixed point constants are basically normal 32-bit constants where the upper 16
-bits are used for the integer part and the lower 16 bits are used for the
-fraction (65536ths).
-This means that you can use them in normal integer expression, and some integer
-operators like plus and minus don't care whether the operands are integer or
-fixed-point.
-You can easily convert a fixed-point number to an integer by shifting it right
-16 bits.
-It follows that you can convert an integer to a fixed-point number by shifting
-it left.
+Fixed point constants are basically normal 32-bit constants where the upper 16 bits are used for the integer part and the lower 16 bits are used for the fraction (65536ths).
+This means that you can use them in normal integer expressions, and some integer operators like plus and minus don't care whether the operands are integer or fixed-point.
+You can easily convert a fixed-point number to an integer by shifting it right by 16 bits.
+It follows that you can convert an integer to a fixed-point number by shifting it left.
.Pp
-Some things are different for fixed-point math, though, which is why you have
-the following functions to use:
+Some things are different for fixed-point math, though, which is why you have the following functions to use:
.EQ
delim $$
.EN
@@ -1036,10 +1061,9 @@
delim off
.EN
.Pp
-These functions are extremely useful for automatic generation of various tables.
-A circle has 65536.0 degrees.
-Sine values are between
-.Bq -1.0 ; 1.0 .
+These functions are useful for automatic generation of various tables.
+Example: assuming a circle has 65536.0 degrees, and sine values are between
+.Bq -1.0 ; 1.0 :
.Pp
.Bd -literal -offset indent
; --
@@ -1053,10 +1077,9 @@
.Ed
.Pp
.Ss String Expressions
-The most basic string expression is any number of characters contained in double
-quotes ("for instance").-Like in C, the escape character is \[rs], and there are a number of commands you
-can use within a string:
+The most basic string expression is any number of characters contained in double quotes
+.Pq Ql \&"for instance" .
+Like in C, the escape character is \[rs], and there are a number of commands you can use within a string:
.Pp
.Bl -column -offset indent "String"
.It Sy String Ta Sy Meaning
@@ -1068,70 +1091,56 @@
.It Li \[rs]n Ta Newline ($0A)
.It Li \[rs]t Ta Tab ($09)
.It Li \[rs]1 - \[rs]9 Ta Macro argument (Only the body of a macros)
-.It Li \[rs]@ Ta Label name suffix (Only in the body of macros and repts)
+.It Li \[rs]@ Ta Label name suffix (Only in the body of macros and REPTs)
.El
.Pp
A funky feature is
-.Sy {symbol}+.Ql {symbol}within a string.
This will examine the type of the symbol and insert its value accordingly.
If symbol is a string symbol, the symbols value is simply copied.
-If it's a numeric symbol, the value is converted to hexadecimal notation and
-inserted as a string with a dollar prepended.
+If it's a numeric symbol, the value is converted to hexadecimal notation and inserted as a string with a dollar sign
+.Sq $
+prepended.
.Pp
-It's possible to change the way numeric symbols are converted by specifying
-a print type like so:
-.Sy {d:symbol}+It's possible to change the way numeric symbols are converted by specifying a print type like so:
+.Ql {d:symbol} .Valid print types are:
-.Bl -column -offset indent
+.Bl -column -offset indent "Print type" "Lowercase hexadecimal" "Example"
.It Sy Print type Ta Sy Format Ta Sy Example
.It Li d Ta Decimal Ta 42
.It Li x Ta Lowercase hexadecimal Ta 2a
.It Li X Ta Uppercase hexadecimal Ta 2A
.It Li b Ta Binary Ta 101010
+.El
.Pp
Note that print types should only be used with numeric values, not strings.
.Pp
HINT: The
-.Sy {symbol}+.Ic {symbol}construct can also be used outside strings.
-The symbol's value is again inserted as a string.
-This is just a short way of doing
-.Dq {symbol} .+The symbol's value is again inserted directly.
.Pp
-Whenever the macro-language expects a string you can actually use a string
-expression.
-This consists of one or more of these function (yes, you can nest them).
-Note that some of these functions actually return an integer and can be used as
-part of an integer expression!
+Whenever the macro-language expects a string you can actually use a string expression.
+This consists of one or more of these functions (yes, you can nest them).
+Note that some of these functions actually return an integer and can be used as part of an integer expression!
.Pp
.Bl -column "STRSUB_str,_pos,_len"
.It Sy Name Ta Sy Operation
-.It Fn STRLEN string Ta Returns the number of characters in string
-.It Fn STRCAT str1 str2 Ta Appends str2 to str1.
-.It Fn STRCMP str1 str2 Ta Returns negative if str1 is alphabetically lower
-than str2, zero if they match, positive if str1 is greater than str2.
-.It Fn STRIN str1 str2 Ta Returns the position of str2 in str1 or zero if it's
-not present (first character is position 1).
-.It Fn STRSUB str pos len Ta Returns a substring from str starting at pos
-(first character is position 1) and with len characters.
-.It Fn STRUPR str Ta Converts all characters in str to capitals and returns the
-new string.
-.It Fn STRLWR str Ta Converts all characters in str to lower case and returns
-the new string.
+.It Fn STRLEN string Ta Returns the number of characters in Ar string .
+.It Fn STRCAT str1 str2 Ta Appends Ar str2 No to Ar str1 .
+.It Fn STRCMP str1 str2 Ta Returns negative if Ar str1 No is alphabetically lower than Ar str2 No , zero if they match, positive if Ar str1 No is greater than Ar str2 .
+.It Fn STRIN str1 str2 Ta Returns the position of Ar str2 No in Ar str1 No or zero if it's not present Pq first character is position 1 .
+.It Fn STRSUB str pos len Ta Returns a substring from Ar str No starting at Ar pos Po first character is position 1 Pc and with Ar len No characters.
+.It Fn STRUPR str Ta Converts all characters in Ar str No to capitals and returns the new string.
+.It Fn STRLWR str Ta Converts all characters in Ar str No to lower case and returns the new string.
.El
-.Pp
.Ss Character maps
+When writing text that is meant to be displayed in the Game Boy, the ASCII characters used in the source code may not be the same ones used in the tileset used in the ROM.
+For example, the tiles used for uppercase letters may be placed starting at tile index 128, which makes it difficult to add text strings to the ROM.
.Pp
-When writing text that is meant to be displayed in the Game Boy, the ASCII
-characters used in the source code may not be the same ones used in the tileset
-used in the ROM.
-For example, the tiles used for uppercase letters may be placed starting at tile
-index 128, which makes it difficult to add text strings to the ROM.
+Character maps allow the code to map strings up to 16 characters long to an abitrary 8-bit value:
.Pp
-Character maps allow the code to map strings up to 16 characters long to an
-abitrary 8-bit value:
-.Pp
.Bd -literal -offset indent
CHARMAP "<LF>", 10
CHARMAP "í", 20
@@ -1138,37 +1147,28 @@
CHARMAP "A", 128
.Ed
.Pp
-It is possible to create multiple character maps and then switch between them
-as desired. This can be used to encode debug information in ASCII and use
-a different encoding for other purposes, for example. Initially, there is
-one character map called
+It is possible to create multiple character maps and then switch between them as desired.
+This can be used to encode debug information in ASCII and use a different encoding for other purposes, for example.
+Initially, there is one character map called
.Sy main
-and it is automatically selected as the current character map from the
-beginning. There is also a character map stack that can be used to save and
-restore which character map is currently active.
+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
-.Ic name .
-.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called
-. Ic name ,
-copied from character map
-.Ic basename .
-.It Ic SETCHARMAP Ar name Ta Switch to character map Ic name .
+.It Ic NEWCHARMAP Ar name Ta Creates a new, empty character map called Ar name .
+.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename .
+.It Ic SETCHARMAP Ar name Ta Switch to character map Ar name .
.It Ic PUSHC Ta Push the current character map onto the stack.
.It Ic POPC Ta Pop a character map off the stack and switch to it.
.El
.Pp
.Sy Note:
-Character maps affect all strings in the file from the point in which they are
-defined, until switching to a different character map.
-This means that any string that the code may want to print as debug information
-will also be affected by it.
+Character maps affect all strings in the file from the point in which they are defined, until switching to a different character map.
+This means that any string that the code may want to print as debug information will also be affected by it.
.Pp
.Sy Note:
The output value of a mapping can be 0.
-If this happens, the assembler will treat this as the end of the string and the
-rest of it will be trimmed.
+If this happens, the assembler will treat this as the end of the string and the rest of it will be trimmed.
.Pp
.Ss Other functions
There are a few other functions that do various useful things:
@@ -1187,28 +1187,20 @@
If
.Ar arg
is a label, it returns the bank number the label is in.
-For labels, as the linker has to resolve this, it can't be used when the
-expression has to be constant.
+For labels, as the linker has to resolve this, it can't be used when the expression has to be constant.
.It Fn DEF label Ta Returns TRUE if
.Ar label
has been defined.
-.It Fn HIGH arg Ta Returns the top 8 bits of the operand if
-.Ar arg
-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
-is a label or constant, or the bottom 8-bit register if it is a 16-bit register
-(AF isn't a valid register for this function).
+.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 .
.El
-.Pp
.Sh MISCELLANEOUS
.Ss Changing options while assembling
.Ic OPT
-can be used to change some of the options during assembling the
-source instead of defining them on the commandline.
+can be used to change some of the options during assembling from within the source, instead of defining them on the command-line.
.Pp
.Ic OPT
-takes a comma-seperated list of options as its argument:
+takes a comma-separated list of options as its argument:
.Pp
.Bd -literal -offset indent
PUSHO
@@ -1219,9 +1211,9 @@
.Ed
.Pp
The options that OPT can modify are currently:
-.Sy b , e
+.Cm b , e
and
-.Sy g .
+.Cm g .
.Pp
.Ic POPO
and
@@ -1233,7 +1225,7 @@
can then later be used to restore them.
Useful if you want to change some options in an include file and you don't want
to destroy the options set by the program that included your file.
-The stacks number of entries is limited only by the amount of memory in your
+The stack's number of entries is limited only by the amount of memory in your
machine.
.Sh SEE ALSO
.Xr rgbasm 1 ,
@@ -1243,7 +1235,7 @@
.Xr rgbds 7 ,
.Xr gbz80 7
.Sh HISTORY
-.Nm rgbds
+.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
--- a/src/fix/main.c
+++ b/src/fix/main.c
@@ -17,8 +17,8 @@
#include "version.h"
-/* Shoft options */
-static char const *optstring = "Ccf:i:jk:l:m:n:p:sr:t:Vv";
+/* Short options */
+static char const *optstring = "Ccf:i:jk:l:m:n:p:r:st:Vv";
/*
* Equivalent long options
@@ -45,16 +45,26 @@
{ "sgb-compatible", no_argument, NULL, 's' }, { "title", required_argument, NULL, 't' }, { "version", no_argument, NULL, 'V' },- { "verbose", no_argument, NULL, 'v' },+ { "validate", no_argument, NULL, 'v' }, { NULL, no_argument, NULL, 0 }};
static void print_usage(void)
{- printf(
-"usage: rgbfix [-CcjsVv] [-f fix_spec] [-i game_id] [-k licensee_str]\n"
-" [-l licensee_id] [-m mbc_type] [-n rom_version] [-p pad_value]\n"
-" [-r ram_size] [-t title_str] file\n");
+ fputs(
+"Usage: rgbfix [-jsVv] [-C | -c] [-f <fix_spec>] [-i <game_id>] [-k <licensee>]\n"
+" [-l <licensee_byte>] [-m <mbc_type>] [-n <rom_version>]\n"
+" [-p <pad_value>] [-r <ram_size>] [-t <title_str>] <file>\n"
+"Useful options:\n"
+" -m, --mbc-type <value> set the MBC type byte to this value; refer\n"
+" to the man page for a list of values\n"
+" -p, --pad-value <value> pad to the next valid size using this value\n"
+" -r, --ram-size <code> set the cart RAM size byte to this value\n"
+" -V, --version print RGBFIX version and exit\n"
+" -v, --validate fix the header logo and both checksums (-f lhg)\n"
+"\n"
+"For help, use `man rgbfix' or go to https://rednex.github.io/rgbds/\n",
+ stderr);
exit(1);
}
@@ -227,8 +237,10 @@
argc -= optind;
argv += optind;
- if (argc == 0)
+ if (argc == 0) {+ fputs("FATAL: no input files\n", stderr);print_usage();
+ }
/*
* Open the ROM file
--- a/src/fix/rgbfix.1
+++ b/src/fix/rgbfix.1
@@ -5,15 +5,16 @@
.\"
.\" SPDX-License-Identifier: MIT
.\"
-.Dd March 11, 2018
+.Dd December 5, 2019
.Dt RGBFIX 1
-.Os RGBDS Manual
+.Os
.Sh NAME
.Nm rgbfix
-.Nd Game Boy checksum fixer
+.Nd Game Boy header utility and checksum fixer
.Sh SYNOPSIS
-.Nm rgbfix
-.Op Fl CcjsVv
+.Nm
+.Op Fl jsVv
+.Op Fl C | c
.Op Fl f Ar fix_spec
.Op Fl i Ar game_id
.Op Fl k Ar licensee_str
@@ -28,10 +29,19 @@
The
.Nm
program changes headers of Game Boy ROM images.
-It also performs other filetype operations, such as truncation.
+It also performs other correctness operations, such as padding.
+.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 C
+.It Fl C , Fl Fl color-only
Set the Game Boy Color\(enonly flag:
.Ad 0x143
= 0xC0.
@@ -38,7 +48,7 @@
If both this and the
.Fl c
flag are set, this takes precedence.
-.It Fl c
+.It Fl c , Fl Fl color-compatible
Set the Game Boy Color\(encompatible flag:
.Ad 0x143
= 0x80.
@@ -47,10 +57,9 @@
flag are set,
.Fl C
takes precedence.
-.It Fl f Ar fix_spec
+.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.
+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
@@ -71,75 +80,70 @@
.It Cm G
Trash the global checksum.
.El
-.It Fl i Ar game_id
+.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 of exactly 4 characters.
-If both this and the title are set, the game ID will overwrite the
-overlapping portion of the title.
-.It Fl j
+If both this and the title are set, the game ID will overwrite the overlapping portion of the title.
+.It Fl j , Fl Fl non-japanese
Set the non-Japanese region flag:
.Ad 0x14A
= 1.
-.It Fl k Ar licensee_str
+.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, truncated to at most two characters.
-.It Fl l Ar licensee_id
+.It Fl l Ar licensee_id , Fl Fl old-licensee Ar licensee_id
Set the old licensee code,
.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
+.It Fl m Ar mbc_type , Fl Fl mbc-type Ar mbc_type
Set the MBC type,
.Ad 0x147 ,
to a given value from 0 to 0xFF.
-.It Fl n Ar rom_version
+.It Fl n Ar rom_version , Fl Fl rom-version Ar rom_version
Set the ROM version,
.Ad 0x14C ,
to a given value from 0 to 0xFF.
-.It Fl p Ar pad_value
+.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
Pad the image to a valid size with a given pad value from 0 to 0xFF.
.Nm
-will automatically pick a size from 32KiB, 64KiB, 128KiB, ..., 8192KiB and
-give a warning thereafter.
+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.
-.It Fl r Ar ram_size
+.It Fl r Ar ram_size , Fl Fl ram-size Ar ram_size
Set the RAM size,
.Ad 0x149 ,
to a given value from 0 to 0xFF.
-.It Fl s
+.It Fl s , Fl Fl sgb-compatible
Set the SGB flag:
.Ad 0x146
-= 3.
-.It Fl t Ar title
+= 3. This flag will be ignored by the SGB unless the old licensee code is 0x33!
+.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, truncated to at most 16 characters.
-It is recommended to use 15 characters instead, to avoid clashing with the CGB
-flag
+It is recommended to use 15 characters instead, to avoid clashing with the CGB flag
.Po Fl c
or
.Fl C
.Pc .
-If both this and the game ID are set, the game ID will overwrite the
-overlapping portion of the title.
-.It Fl V
+If both this and the game ID are set, the game ID will overwrite the overlapping portion of the title.
+.It Fl V , Fl Fl version
Print the version of the program and exit.
-.It Fl v
+.It Fl v , Fl Fl validate
Equivalent to
.Fl f Cm lhg .
.El
.Sh EXAMPLES
Most values in the ROM header are only cosmetic.
-The bare minimum requirements for a workable image are checksums, the Nintendo
-logo, and (if needed) the CGB/SGB flags.
+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 multiple of 32KiB .
+.Pq Do valid Dc meaning a power of 2, times 32 KiB .
.Pp
-The following will make a plain, no-color Game Boy game without checking for
+The following will make a plain, non-color Game Boy game without checking for
a valid size:
.Pp
.D1 $ rgbfix -v foo.gb
@@ -146,21 +150,21 @@
.Pp
The following will make a SGB-enabled, color-enabled game with a title of
.Dq foobar ,
-and pad it to a multiple of 32KiB.
+and pad it to a valid size.
.Po
-The Game Boy itself does not use the title, but some emulators or ROM managers
-might.
+The Game Boy itself does not use the title, but some emulators or ROM managers do.
.Pc
.Pp
-.D1 $ rgbfix -vcs -l 0x33 -p 0 -t foobar baz.gb
+.D1 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
.Pp
-The following will duplicate the header
-.Pq sans global checksum
-of the game
+The following will duplicate the header (sans global checksum) of the game
.Dq Survival Kids :
.Pp
.D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \
SurvivalKids.gbc
+.Sh BUGS
+Please report bugs on
+.Lk https://github.com/rednex/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
@@ -167,7 +171,6 @@
.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
+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/rednex/rgbds .
--- a/src/gbz80.7
+++ b/src/gbz80.7
@@ -7,7 +7,7 @@
.\"
.Dd February 23, 2018
.Dt GBZ80 7
-.Os RGBDS Manual
+.Os
.Sh NAME
.Nm gbz80
.Nd CPU opcode reference
@@ -14,9 +14,7 @@
.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.
+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
--- a/src/gfx/main.c
+++ b/src/gfx/main.c
@@ -52,9 +52,20 @@
static void print_usage(void)
{- printf(
-"usage: rgbgfx [-ADFfhmPTuVv] [-o outfile] [-a attrmap] [-d #] [-p palfile]\n"
-" [-t tilemap] [-x #] infile\n");
+ fputs(
+"Usage: rgbgfx [-CDhmuVv] [-f | -F] [-a <attr_map> | -A] [-d <depth>]\n"
+" [-o <out_file>] [-p <pal_file> | -P] [-t <tile_map> | -T]\n"
+" [-x <tiles>] <file>\n"
+"Useful options:\n"
+" -f, --fix make the input image an indexed PNG\n"
+" -m, --mirror-tiles optimize out mirrored tiles\n"
+" -o, --output <path> set the output binary file\n"
+" -t, --tilemap <path> set the output tilemap file\n"
+" -u, --unique-tiles optimize out identical tiles\n"
+" -V, --version print RGBGFX version and exit\n"
+"\n"
+"For help, use `man rgbgfx' or go to https://rednex.github.io/rgbds/\n",
+ stderr);
exit(1);
}
@@ -69,9 +80,6 @@
struct Mapfile attrmap = {0};char *ext;
- if (argc == 1)
- print_usage();
-
opts.tilemapfile = "";
opts.attrmapfile = "";
opts.palfile = "";
@@ -145,8 +153,10 @@
argc -= optind;
argv += optind;
- if (argc == 0)
+ if (argc == 0) {+ fputs("FATAL: no input files\n", stderr);print_usage();
+ }
#define WARN_MISMATCH(property) \
warnx("The PNG's " property \--- a/src/gfx/rgbgfx.1
+++ b/src/gfx/rgbgfx.1
@@ -5,20 +5,21 @@
.\"
.\" SPDX-License-Identifier: MIT
.\"
-.Dd January 26, 2018
+.Dd December 5, 2019
.Dt RGBGFX 1
-.Os RGBDS Manual
+.Os
.Sh NAME
.Nm rgbgfx
.Nd Game Boy graphics converter
.Sh SYNOPSIS
-.Nm rgbgfx
-.Op Fl ACDfFhmPTuVv
-.Op Fl o Ar outfile
-.Op Fl a Ar attrmap
+.Nm
+.Op Fl CDhmuVv
+.Op Fl f | Fl F
+.Op Fl a Ar attrmap | Fl A
.Op Fl d Ar depth
-.Op Fl p Ar palfile
-.Op Fl t Ar tilemap
+.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
@@ -26,106 +27,100 @@
.Nm
program converts PNG images into the Nintendo Game Boy's planar tile format.
-The resulting colors and their palette indices are determined differently
-depending on the input PNG file:
+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.
+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.
+If the image has color (or the grayscale method failed), the colors are sorted from lightest to darkest.
.El
-The input image may not contain more colors than the selected bit depth
-allows. Transparent pixels are set to palette index 0.
+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
-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.
+.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
+.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
+but the attrmap file output name is made by taking the input filename, removing the file extension, and appending
.Pa .attrmap .
-.It Fl C
+.It Fl C , Fl Fl color-curve
Use the color curve of the Game Boy Color when generating palettes.
-.It Fl D
+.It Fl D , Fl Fl debug
Debug features are enabled.
-.It Fl d Ar depth
+.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
+.It Fl f , Fl Fl fix
Fix the input PNG file to be a correctly indexed image.
-.It Fl F
+.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
+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 horizontally rather than vertically.
-.It Fl m
-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
+.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 outfile
+.It Fl o Ar out_file , Fl Fl output Ar out_file
The name of the output file.
-.It Fl p Ar palfile
-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
+.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
+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
-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.
+.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
+.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
+but the tilemap file output name is made by taking the input filename, removing the file extension, and appending
.Pa .tilemap .
-.It Fl u
-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
+.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
+.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
+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:
+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
@@ -134,8 +129,9 @@
.Pp
.D1 $ rgbgfx -T -u -o out.2bpp in.png
.Pp
-The following creates a planar 2bpp file with only unique tiles (accounting for
-tile mirroring) and its associated tilemap
+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 :
@@ -145,6 +141,9 @@
The following will do nothing:
.Pp
.D1 $ rgbgfx in.png
+.Sh BUGS
+Please report bugs on
+.Lk https://github.com/rednex/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbds 7 ,
.Xr rgbasm 1 ,
--- a/src/link/main.c
+++ b/src/link/main.c
@@ -82,8 +82,20 @@
*/
static void printUsage(void)
{- puts("usage: rgblink [-dtVvw] [-l linkerscript] [-m mapfile] [-n symfile] [-O overlay]\n"- " [-o outfile] [-p pad_value] [-s symbol] file [...]");
+ fputs(
+"Usage: rgblink [-dtVvw] [-l script] [-m map_file] [-n sym_file]\n"
+" [-O overlay_file] [-o out_file] [-p pad_value] [-s symbol]\n"
+" <file> ...\n"
+"Useful options:\n"
+" -l, --linkerscript <path> set the input linker script\n"
+" -m, --map <path> set the output map file\n"
+" -n, --sym <path> set the output symbol list file\n"
+" -o, --output <path> set the output file\n"
+" -p, --pad <value> set the value to pad between sections with\n"
+" -V, --version print RGBLINK version and exits\n"
+"\n"
+"For help, use `man rgblink' or go to https://rednex.github.io/rgbds/\n",
+ stderr);
}
/**
@@ -159,7 +171,7 @@
/* If no input files were specified, the user must have screwed up */
if (curArgIndex == argc) {- fputs("No input files\n", stderr);+ fputs("FATAL: no input files\n", stderr);printUsage();
exit(1);
}
--- a/src/link/rgblink.1
+++ b/src/link/rgblink.1
@@ -1,107 +1,128 @@
.\"
.\" This file is part of RGBDS.
.\"
-.\" Copyright (c) 2010-2018, Anthony J. Bentley and RGBDS contributors.
+.\" Copyright (c) 2010-2019, Anthony J. Bentley and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
-.Dd January 26, 2018
+.Dd November 26, 2019
.Dt RGBLINK 1
-.Os RGBDS Manual
+.Os
.Sh NAME
.Nm rgblink
.Nd Game Boy linker
.Sh SYNOPSIS
-.Nm rgblink
-.Op Fl dtVw
-.Op Fl m Ar mapfile
-.Op Fl n Ar symfile
-.Op Fl O Ar overlayfile
-.Op Fl o Ar outfile
+.Nm
+.Op Fl dtVvw
+.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 symbol
-.Op Fl l Ar linkerscript
.Ar
.Sh DESCRIPTION
The
.Nm
-program links objects created by
-.Xr rgbasm 1
+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
-By default, ROM0 sections created by the assembler are placed in the 16KiB
-bank 0, and ROMX sections are placed in any bank except bank 0.
-If your ROM will only be 32KiB, you can use the
+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 override this.
+option to change this.
.Pp
-Similarly, WRAM0 sections are placed in the first 4KiB of WRAM bank 0 and WRAMX
-sections are placed in any bank except bank 0.
-If your ROM doesn't use banked WRAM you can use option
+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 override this.
+option to change this.
.Pp
-Also, if your ROM is designed for DMG, you can make sure that you don't use any
-prohibited section by using the option
-.Fl d ,
-which implies
+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 VRAM bank 1.
+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 m Ar mapfile
-Write a mapfile to the given filename.
-.It Fl n Ar symfile
-Write a symbol file to the given filename.
-.It Fl O Ar overlayfile
-The ROM image to overlay sections over.
-When an overlay ROM is provided, all sections must be fixed.
-This may be used to patch an existing binary.
-.It Fl o Ar outfile
-Write ROM image to the given filename.
-.It Fl p Ar pad_value
-When padding an image, pad with this value.
-The default is 0x00.
-.It Fl s Ar symbol
-???
-.It Fl w
-Expand the WRAM0 section size from 4KiB to the full 8KiB assigned to WRAM and
-prohibit the use of WRAMX sections.
-.It Fl d
+.It Fl d , Fl Fl dmg
Enable DMG mode.
-Prohibit the use of sections that doesn't exist on a DMG, such as WRAMX and VRAM
-bank 1.
+Prohibit the use of sections that doesn't exist on a DMG, such as WRAMX and VRAM bank 1.
This option automatically enables
.Fl w .
-.It Fl t
-Expand the ROM0 section size from 16KiB to the full 32KiB assigned to ROM and
-prohibit the use of ROMX sections.
-Useful for ROMs that fit in 32 KiB.
-.It Fl l Ar linkerscript
-Specify a linkerscript file that tells the linker how sections must be placed in
-the ROM.
-This file has priority over the attributes assigned in the source code, but they
-have to be consistent.
-See
+.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 its format.
-.It Fl V
+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 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 tiny
+Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to ROM and prohibit the use of ROMX sections.
+Useful for ROMs that fit in 32 KiB.
+.It Fl V , Fl version
Print the version of the program and exit.
+.It Fl v , Fl verbose
+Verbose: enable printing more information to standard error.
+.It Fl w , Fl wramx
+Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to WRAM and prohibit the use of WRAMX sections.
.El
.Sh EXAMPLES
-All you need for a basic ROM is an object file, which can be made into a ROM
-image like so:
+All you need for a basic ROM is an object file, which can be made into a ROM image like so:
.Pp
.D1 $ rgblink -o bar.gb foo.o
.Pp
-The resulting bar.gb will not have correct checksums
-.Pq unless you put them in the assembly source .
+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
.D1 $ rgbfix -v bar.gb
+.Pp
+Here is a more complete example:
+.Pp
+.D1 $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o
+.Sh BUGS
+Please report bugs on
+.Lk https://github.com/rednex/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 5 ,
@@ -110,7 +131,6 @@
.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
+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/rednex/rgbds .
--- a/src/link/rgblink.5
+++ b/src/link/rgblink.5
@@ -5,22 +5,16 @@
.\"
.\" SPDX-License-Identifier: MIT
.\"
-.Dd January 27, 2018
+.Dd November 26, 2019
.Dt RGBLINK 5
-.Os RGBDS Manual
+.Os
.Sh NAME
.Nm rgblink
-.Nd linkerscript file format
+.Nd linker script file format
.Sh DESCRIPTION
-The linkerscript is an external file that allows the user to specify the
-order of sections without the need for doing so before assembling each object
-file.
+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
-The placement of sections specified in the linkerscript is done before the
-sections whose placement is defined in the source code.
-.Pp
-A linkerscript consists on a series of banks followed by a list of sections
-and, optionally, commands.
+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 \&;
@@ -36,51 +30,53 @@
"Some variables"
.Ed
.Pp
-Numbers can be in decimal or hexadecimal format (the prefix is
-.Ql $ ) .
-It is an error if any section name or command are found before setting a bank.
+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
-.Ar INCLUDE
-keyword followed by a string with the path of the file that has to be included.
+.Ic INCLUDE
+keyword, followed by a string with the path of the file that has to be included.
.Pp
The possible bank types are:
-.Sy ROM0 , ROMX , VRAM , WRAM0 , WRAMX , OAM
+.Cm ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM
and
-.Sy HRAM .
-Types
-.Sy ROMX , VRAM , WRAMX
+.Cm HRAM .
+Unless there is a single bank, which can occur with types
+.Cm ROMX , VRAM , SRAM
and
-.Sy SRAM
-are banked, which means that it is needed to specify a bank after the type.
+.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 linkerscript switches to a different bank and then it comes back to the
-previous one it will continue from the last address that was used.
+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
-.Ar ORG
+.Ic ORG
and
-.Ar ALIGN :
+.Ic ALIGN :
.Bl -bullet
.It
-.Ar ORG
+.Ic ORG
sets the address in which new sections will be placed.
It can not be lower than the current address.
.It
-.Ar ALIGN
-will increase the address until it is aligned to the specified boundary (it
-tries to set to 0 the number of bits specified after the command:
-.Sy ALIGN 8
-will align to $100).
+.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
-Note: The bank, alignment, address and type of sections can be specified both
-in the source code and in the linkerscript.
-For a section to be able to be placed with the linkerscript the bank must be
-left unassigned in the source code or be the same as the one specified in the
-linkerscript. The address and alignment musn't be set.
+.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 ,
--- a/src/rgbds.5
+++ b/src/rgbds.5
@@ -7,7 +7,7 @@
.\"
.Dd January 26, 2018
.Dt RGBDS 5
-.Os RGBDS Manual
+.Os
.Sh NAME
.Nm rgbds
.Nd object file format documentation
@@ -16,16 +16,14 @@
.Xr rgbasm 1
and
.Xr rgblink 1 .
-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.
+.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.
.Pp
.Sh FILE STRUCTURE
The following types are used:
.Pp
.Ar LONG
-is a 32‐bit integer stored in little‐endian format (Intel).
+is a 32‐bit integer stored in little‐endian format.
.Ar BYTE
is an 8‐bit integer.
.Ar STRING
@@ -131,17 +129,15 @@
.Ss RPN DATA
Expressions in the object file are stored as RPN.
This is an expression of the form
-.Do 2 5 + Dc .
+.Dq 2 5 + .
This will first push the value
-.Do 2 Dc to the stack.
-Then
-.Do 5 Dc .
+.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 BYTEs with some bytes being
-special prefixes for integers and symbols.
+.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.
.Pp
.Bl -column -offset indent ".Sy String" ".Sy String"
.It Sy Value Ta Sy Meaning
@@ -166,19 +162,19 @@
.It Li $35 Ta Li <= comparison
.It Li $40 Ta Li << operator
.It Li $41 Ta Li >> operator
-.It Li $50 Ta Li BANK(symbol),
+.It Li $50 Ta Li BANK(symbol) ,
a
.Ar LONG
Symbol ID follows.
-.It Li $51 Ta Li BANK(section_name),
+.It Li $51 Ta Li BANK(section_name) ,
a null-terminated string follows.
-.It Li $52 Ta Li Current BANK() .
-.It Li $60 Ta Li HRAMCheck.
-Check if the value is in HRAM, AND it with 0xFF.
+.It Li $52 Ta Li Current BANK()
+.It Li $60 Ta Li HRAMCheck .
+Checks if the value is in HRAM, AND it with 0xFF.
.It Li $80 Ta Ar LONG
integer follows.
.It Li $81 Ta Ar LONG
-Symbol ID follows.
+symbol ID follows.
.El
.Pp
.Sh SEE ALSO
@@ -187,7 +183,7 @@
.Xr rgbds 7 ,
.Xr gbz80 7
.Sh HISTORY
-.Nm rgbds
+.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
--- a/src/rgbds.7
+++ b/src/rgbds.7
@@ -7,7 +7,7 @@
.\"
.Dd March 7, 2018
.Dt RGBDS 7
-.Os RGBDS Manual
+.Os
.Sh NAME
.Nm rgbds
.Nd Rednex Game Boy Development System