gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-20 18:22:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #455 from ISSOtm/man

Browse Source 
Overhaul RGBDS man pages and help messages
This commit is contained in:
Eldred Habert
2020-01-07 22:44:58 +01:00
committed by GitHub
parent d3328406a2 b81faeccfa
commit f26cfa2d94
13 changed files with 887 additions and 740 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
src/asm/main.c
View File

@@ -268,10 +268,20 @@ static struct option const longopts[] = {
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 @@ int main(int argc, char *argv[])
if (!cldefines)
fatalerror("No memory for command line defines");
if (argc == 1)
print_usage();
/* yydebug=1; */
nMaxRecursionDepth = 64;
@@ -402,8 +409,10 @@ int main(int argc, char *argv[])
DefaultOptions = CurrentOptions;
if (argc == 0)
if (argc == 0) {
fputs("FATAL: no input files\n", stderr);
print_usage();
}
tzMainfile = argv[argc - 1];

176
src/asm/rgbasm.1
View File

@@ -7,85 +7,184 @@
.\"
.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
.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
Print
.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.
@@ -102,11 +201,13 @@ $ cat foo.asm | rgbasm -o bar.o -
$ rgbasm -o bar.o - < foo.asm
.Ed
.Pp
The resulting object file is not yet a usable ROM image \(em it must first be
run through
The resulting object file is not yet a usable ROM image \(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 @@ and
.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 .

840
src/asm/rgbasm.5
View File

File diff suppressed because it is too large Load Diff

28
src/fix/main.c
View File

@@ -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 @@ static struct option const longopts[] = {
{ "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 @@ int main(int argc, char *argv[])
argc -= optind;
argv += optind;
if (argc == 0)
if (argc == 0) {
fputs("FATAL: no input files\n", stderr);
print_usage();
}
/*
* Open the ROM file

95
src/fix/rgbfix.1
View File

@@ -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,17 +29,26 @@
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.
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 @@ If both this and the
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,103 +80,97 @@ Fix the global checksum
.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
.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 ,
.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 .

6
src/gbz80.7
View File

@@ -7,16 +7,14 @@
.\"
.Dd February 23, 2018
.Dt GBZ80 7
.Os RGBDS Manual
.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.
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

24
src/gfx/main.c
View File

@@ -52,9 +52,20 @@ static struct option const longopts[] = {
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 @@ int main(int argc, char *argv[])
struct Mapfile attrmap = {0};
char *ext;
if (argc == 1)
print_usage();
opts.tilemapfile = "";
opts.attrmapfile = "";
opts.palfile = "";
@@ -145,8 +153,10 @@ int main(int argc, char *argv[])
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 \

137
src/gfx/rgbgfx.1
View File

@@ -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 @@ The
.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 @@ The following creates a planar 2bpp file with only unique tiles, and its tilemap
.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 @@ and attrmap
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 ,

18
src/link/main.c
View File

@@ -82,8 +82,20 @@ static struct option const longopts[] = {
*/
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 @@ int main(int argc, char *argv[])
/* 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);
}

146
src/link/rgblink.1
View File

@@ -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.
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.
.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 @@ to fix these so that the program will actually run in a Game Boy:
.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 .

72
src/link/rgblink.5
View File

@@ -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 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 @@ WRAMX 2
"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 ,

34
src/rgbds.5
View File

@@ -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 @@ This is the description of the object files used by
.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 @@ ENDR
.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
@@ -172,13 +168,13 @@ a
Symbol ID follows.
.It Li $51 Ta Li BANK(section_name) ,
a null-terminated string follows.
.It Li $52 Ta Li Current BANK() .
.It Li $52 Ta Li Current BANK()
.It Li $60 Ta Li HRAMCheck .
Check if the value is in HRAM, AND it with 0xFF.
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 @@ Symbol ID follows.
.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

2
src/rgbds.7
View File

@@ -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