gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-21 02:32:06 +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) static void print_usage(void)
{ {
printf( fputs(
"usage: rgbasm [-EhLVvw] [-b chars] [-Dname[=value]] [-g chars] [-i path]\n" "Usage: rgbasm [-EhLVvw] [-b chars] [-D name[=value]] [-g chars] [-i path]\n"
" [-M dependfile] [-o outfile] [-p pad_value]\n" " [-M depend_file] [-o out_file] [-p pad_value] [-r depth]\n"
" [-r recursion_depth] [-W warning] [-w] file.asm\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); exit(1);
} }
@@ -293,9 +303,6 @@ int main(int argc, char *argv[])
if (!cldefines) if (!cldefines)
fatalerror("No memory for command line defines"); fatalerror("No memory for command line defines");
if (argc == 1)
print_usage();
/* yydebug=1; */ /* yydebug=1; */
nMaxRecursionDepth = 64; nMaxRecursionDepth = 64;
@@ -402,8 +409,10 @@ int main(int argc, char *argv[])
DefaultOptions = CurrentOptions; DefaultOptions = CurrentOptions;
if (argc == 0) if (argc == 0) {
fputs("FATAL: no input files\n", stderr);
print_usage(); print_usage();
}
tzMainfile = argv[argc - 1]; tzMainfile = argv[argc - 1];

178
src/asm/rgbasm.1
View File

@@ -7,89 +7,188 @@
.\" .\"
.Dd July 8, 2019 .Dd July 8, 2019
.Dt RGBASM 1 .Dt RGBASM 1
.Os RGBDS Manual .Os
.Sh NAME .Sh NAME
.Nm rgbasm .Nm rgbasm
.Nd Game Boy assembler .Nd Game Boy assembler
.Sh SYNOPSIS .Sh SYNOPSIS
.Nm rgbasm .Nm
.Op Fl EhLVvw .Op Fl EhLVvw
.Op Fl b Ar chars .Op Fl b Ar chars
.Op Fl D Ar name Ns Op = Ns Ar value .Op Fl D Ar name Ns Op = Ns Ar value
.Op Fl g Ar chars .Op Fl g Ar chars
.Op Fl i Ar path .Op Fl i Ar path
.Op Fl M Ar dependfile .Op Fl M Ar depend_file
.Op Fl o Ar outfile .Op Fl o Ar out_file
.Op Fl p Ar pad_value .Op Fl p Ar pad_value
.Op Fl r Ar recursion_depth .Op Fl r Ar recursion_depth
.Ar file .Op Fl W Ar warning
.Ar
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
program creates an object file from an assembly source file. program creates an RGB object file from an assembly source file.
The input The input
.Ar file .Ar file
can be a file path, or can be a file path, or
.Cm \- .Cm \-
denoting denoting
.Cm stdin . .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 .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. Change the two characters used for binary constants.
The defaults are 01. The defaults are 01.
.It Fl D Ar name Ns Op = Ns Ar value .It Fl D Ar name Ns Oo = Ns Ar value Oc , Fl Fl define Ar name Ns Oo = Ns Ar value Oc
Add string symbol to the compiled source code. This is equivalent to Add a string symbol to the compiled source code.
.Ar name This is equivalent to
.Cm EQUS .Ql Ar name Ic EQUS Qq Ar value
.Qq Ar "value" in code, or
in code. If a value is not specified, a value of 1 is given. .Ql Ar name Ic EQUS Qq 1
.It Fl E if
.Ar value
is not specified.
.It Fl E , Fl Fl export-all
Export all labels, including unreferenced and local labels. Export all labels, including unreferenced and local labels.
.It Fl g Ar chars .It Fl g Ar chars , Fl Fl gfx-chars Ar chars
Change the four characters used for binary constants. Change the four characters used for gfx constants.
The defaults are 0123. The defaults are 0123.
.It Fl h .It Fl h , Fl Fl halt-without-nop
By default, By default,
.Nm .Nm
inserts a inserts a
.Sq nop .Ic nop
instruction immediately after any instruction immediately after any
.Sq halt .Ic halt
instruction. instruction.
The The
.Fl h .Fl h
option disables this behavior. option disables this behavior.
.It Fl i Ar path .It Fl i Ar path , Fl Fl include Ar path
Add an include path. Add an include path.
.It Fl L .It Fl L , Fl Fl preserve-ld
Disable the optimization that turns loads of the form Disable the optimization that turns loads of the form
.Sy LD [$FF00+n8],A .Ic LD [$FF00+n8],A
into the opcode 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. 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 Print
.Xr make 1 .Xr make 1
dependencies to dependencies to
.Ar dependfile . .Ar depend_file .
.It Fl o Ar outfile .It Fl o Ar out_file , Fl Fl output Ar out_file
Write an object file to the given filename. 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. When padding an image, pad with this value.
The default is 0x00. 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. 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. Print the version of the program and exit.
.It Fl v .It Fl v , Fl Fl verbose
Be 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 .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 .El
.Sh EXAMPLES .Sh EXAMPLES
You can assemble a source file in two ways. You can assemble a source file in two ways.
Straight forward way: Straightforward way:
.Pp .Pp
.Bd -literal -offset indent .Bd -literal -offset indent
$ rgbasm -o bar.o foo.asm $ rgbasm -o bar.o foo.asm
@@ -102,11 +201,13 @@ $ cat foo.asm | rgbasm -o bar.o -
$ rgbasm -o bar.o - < foo.asm $ rgbasm -o bar.o - < foo.asm
.Ed .Ed
.Pp .Pp
The resulting object file is not yet a usable ROM image \(em it must first be The resulting object file is not yet a usable ROM image \(em it must first be run through
run through
.Xr rgblink 1 .Xr rgblink 1
and and then
.Xr rgbfix 1 . .Xr rgbfix 1 .
.Sh BUGS
Please report bugs on
.Lk https://github.com/rednex/rgbds/issues GitHub .
.Sh SEE ALSO .Sh SEE ALSO
.Xr rgbasm 5 , .Xr rgbasm 5 ,
.Xr rgbfix 1 , .Xr rgbfix 1 ,
@@ -116,7 +217,6 @@ and
.Xr gbz80 7 .Xr gbz80 7
.Sh HISTORY .Sh HISTORY
.Nm .Nm
was originally written by Carsten S\(/orensen as part of the ASMotor package, was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
and was later packaged in RGBDS by Justin Lloyd. It is now maintained by a It is now maintained by a number of contributors at
number of contributors at
.Lk https://github.com/rednex/rgbds . .Lk https://github.com/rednex/rgbds .

852
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" #include "version.h"
/* Shoft options */ /* Short options */
static char const *optstring = "Ccf:i:jk:l:m:n:p:sr:t:Vv"; static char const *optstring = "Ccf:i:jk:l:m:n:p:r:st:Vv";
/* /*
* Equivalent long options * Equivalent long options
@@ -45,16 +45,26 @@ static struct option const longopts[] = {
{ "sgb-compatible", no_argument, NULL, 's' }, { "sgb-compatible", no_argument, NULL, 's' },
{ "title", required_argument, NULL, 't' }, { "title", required_argument, NULL, 't' },
{ "version", no_argument, NULL, 'V' }, { "version", no_argument, NULL, 'V' },
{ "verbose", no_argument, NULL, 'v' }, { "validate", no_argument, NULL, 'v' },
{ NULL, no_argument, NULL, 0 } { NULL, no_argument, NULL, 0 }
}; };
static void print_usage(void) static void print_usage(void)
{ {
printf( fputs(
"usage: rgbfix [-CcjsVv] [-f fix_spec] [-i game_id] [-k licensee_str]\n" "Usage: rgbfix [-jsVv] [-C | -c] [-f <fix_spec>] [-i <game_id>] [-k <licensee>]\n"
" [-l licensee_id] [-m mbc_type] [-n rom_version] [-p pad_value]\n" " [-l <licensee_byte>] [-m <mbc_type>] [-n <rom_version>]\n"
" [-r ram_size] [-t title_str] file\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); exit(1);
} }
@@ -227,8 +237,10 @@ int main(int argc, char *argv[])
argc -= optind; argc -= optind;
argv += optind; argv += optind;
if (argc == 0) if (argc == 0) {
fputs("FATAL: no input files\n", stderr);
print_usage(); print_usage();
}
/* /*
* Open the ROM file * Open the ROM file

95
src/fix/rgbfix.1
View File

@@ -5,15 +5,16 @@
.\" .\"
.\" SPDX-License-Identifier: MIT .\" SPDX-License-Identifier: MIT
.\" .\"
.Dd March 11, 2018 .Dd December 5, 2019
.Dt RGBFIX 1 .Dt RGBFIX 1
.Os RGBDS Manual .Os
.Sh NAME .Sh NAME
.Nm rgbfix .Nm rgbfix
.Nd Game Boy checksum fixer .Nd Game Boy header utility and checksum fixer
.Sh SYNOPSIS .Sh SYNOPSIS
.Nm rgbfix .Nm
.Op Fl CcjsVv .Op Fl jsVv
.Op Fl C | c
.Op Fl f Ar fix_spec .Op Fl f Ar fix_spec
.Op Fl i Ar game_id .Op Fl i Ar game_id
.Op Fl k Ar licensee_str .Op Fl k Ar licensee_str
@@ -28,17 +29,26 @@
The The
.Nm .Nm
program changes headers of Game Boy ROM images. 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: The arguments are as follows:
.Bl -tag -width Ds .Bl -tag -width Ds
.It Fl C .It Fl C , Fl Fl color-only
Set the Game Boy Color\(enonly flag: Set the Game Boy Color\(enonly flag:
.Ad 0x143 .Ad 0x143
= 0xC0. = 0xC0.
If both this and the If both this and the
.Fl c .Fl c
flag are set, this takes precedence. flag are set, this takes precedence.
.It Fl c .It Fl c , Fl Fl color-compatible
Set the Game Boy Color\(encompatible flag: Set the Game Boy Color\(encompatible flag:
.Ad 0x143 .Ad 0x143
= 0x80. = 0x80.
@@ -47,10 +57,9 @@ If both this and the
flag are set, flag are set,
.Fl C .Fl C
takes precedence. 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. Fix certain header values that the Game Boy checks for correctness.
Alternatively, intentionally trash these values by writing their binary inverse Alternatively, intentionally trash these values by writing their binary inverse instead.
instead.
.Ar fix_spec .Ar fix_spec
is a string containing any combination of the following characters: is a string containing any combination of the following characters:
.Pp .Pp
@@ -71,103 +80,97 @@ Fix the global checksum
.It Cm G .It Cm G
Trash the global checksum. Trash the global checksum.
.El .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 Set the game ID string
.Pq Ad 0x13F Ns \(en Ns Ad 0x142 .Pq Ad 0x13F Ns \(en Ns Ad 0x142
to a given string of exactly 4 characters. to a given string of exactly 4 characters.
If both this and the title are set, the game ID will overwrite the If both this and the title are set, the game ID will overwrite the overlapping portion of the title.
overlapping portion of the title. .It Fl j , Fl Fl non-japanese
.It Fl j
Set the non-Japanese region flag: Set the non-Japanese region flag:
.Ad 0x14A .Ad 0x14A
= 1. = 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 Set the new licensee string
.Pq Ad 0x144 Ns \(en Ns Ad 0x145 .Pq Ad 0x144 Ns \(en Ns Ad 0x145
to a given string, truncated to at most two characters. 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, Set the old licensee code,
.Ad 0x14B , .Ad 0x14B ,
to a given value from 0 to 0xFF. to a given value from 0 to 0xFF.
This value is deprecated and should be set to 0x33 in all new software. 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, Set the MBC type,
.Ad 0x147 , .Ad 0x147 ,
to a given value from 0 to 0xFF. 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, Set the ROM version,
.Ad 0x14C , .Ad 0x14C ,
to a given value from 0 to 0xFF. 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. Pad the image to a valid size with a given pad value from 0 to 0xFF.
.Nm .Nm
will automatically pick a size from 32KiB, 64KiB, 128KiB, ..., 8192KiB and will automatically pick a size from 32 KiB, 64 KiB, 128 KiB, ..., 8192 KiB.
give a warning thereafter.
The cartridge size byte The cartridge size byte
.Pq Ad 0x148 .Pq Ad 0x148
will be changed to reflect this new size. 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, Set the RAM size,
.Ad 0x149 , .Ad 0x149 ,
to a given value from 0 to 0xFF. to a given value from 0 to 0xFF.
.It Fl s .It Fl s , Fl Fl sgb-compatible
Set the SGB flag: Set the SGB flag:
.Ad 0x146 .Ad 0x146
= 3. = 3. This flag will be ignored by the SGB unless the old licensee code is 0x33!
.It Fl t Ar title .It Fl t Ar title , Fl Fl title Ar title
Set the title string Set the title string
.Pq Ad 0x134 Ns \(en Ns Ad 0x143 .Pq Ad 0x134 Ns \(en Ns Ad 0x143
to a given string, truncated to at most 16 characters. to a given string, truncated to at most 16 characters.
It is recommended to use 15 characters instead, to avoid clashing with the CGB It is recommended to use 15 characters instead, to avoid clashing with the CGB flag
flag
.Po Fl c .Po Fl c
or or
.Fl C .Fl C
.Pc . .Pc .
If both this and the game ID are set, the game ID will overwrite the If both this and the game ID are set, the game ID will overwrite the overlapping portion of the title.
overlapping portion of the title. .It Fl V , Fl Fl version
.It Fl V
Print the version of the program and exit. Print the version of the program and exit.
.It Fl v .It Fl v , Fl Fl validate
Equivalent to Equivalent to
.Fl f Cm lhg . .Fl f Cm lhg .
.El .El
.Sh EXAMPLES .Sh EXAMPLES
Most values in the ROM header are only cosmetic. Most values in the ROM header are only cosmetic.
The bare minimum requirements for a workable image are checksums, the Nintendo The bare minimum requirements for a workable program are the header checksum, the Nintendo logo, and (if needed) the CGB/SGB flags.
logo, and (if needed) the CGB/SGB flags.
It is a good idea to pad the image to a valid size as well 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 .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: a valid size:
.Pp .Pp
.D1 $ rgbfix -v foo.gb .D1 $ rgbfix -v foo.gb
.Pp .Pp
The following will make a SGB-enabled, color-enabled game with a title of The following will make a SGB-enabled, color-enabled game with a title of
.Dq foobar , .Dq foobar ,
and pad it to a multiple of 32KiB. and pad it to a valid size.
.Po .Po
The Game Boy itself does not use the title, but some emulators or ROM managers The Game Boy itself does not use the title, but some emulators or ROM managers do.
might.
.Pc .Pc
.Pp .Pp
.D1 $ rgbfix -vcs -l 0x33 -p 0 -t foobar baz.gb .D1 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
.Pp .Pp
The following will duplicate the header The following will duplicate the header (sans global checksum) of the game
.Pq sans global checksum
of the game
.Dq Survival Kids : .Dq Survival Kids :
.Pp .Pp
.D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \ .D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \
SurvivalKids.gbc SurvivalKids.gbc
.Sh BUGS
Please report bugs on
.Lk https://github.com/rednex/rgbds/issues GitHub .
.Sh SEE ALSO .Sh SEE ALSO
.Xr rgbasm 1 , .Xr rgbasm 1 ,
.Xr rgblink 1 , .Xr rgblink 1 ,
.Xr rgbds 7 .Xr rgbds 7
.Sh HISTORY .Sh HISTORY
.Nm .Nm
was originally released by Carsten S\(/orensen as a standalone program called was originally released by Carsten S\(/orensen as a standalone program called gbfix, and was later packaged in RGBDS by Justin Lloyd.
gbfix, and was later packaged in RGBDS by Justin Lloyd. It is now maintained by It is now maintained by a number of contributors at
a number of contributors at
.Lk https://github.com/rednex/rgbds . .Lk https://github.com/rednex/rgbds .

6
src/gbz80.7
View File

@@ -7,16 +7,14 @@
.\" .\"
.Dd February 23, 2018 .Dd February 23, 2018
.Dt GBZ80 7 .Dt GBZ80 7
.Os RGBDS Manual .Os
.Sh NAME .Sh NAME
.Nm gbz80 .Nm gbz80
.Nd CPU opcode reference .Nd CPU opcode reference
.Sh DESCRIPTION .Sh DESCRIPTION
This is the list of opcodes supported by This is the list of opcodes supported by
.Xr rgbasm 1 , .Xr rgbasm 1 ,
including a short description, the number of bytes needed to encode them and the 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.
number of CPU cycles at 1MHz (or 2MHz in GBC dual speed mode) needed to complete
them.
.Pp .Pp
Note: All arithmetic/logic operations that use register Note: All arithmetic/logic operations that use register
.Sy A .Sy A

24
src/gfx/main.c
View File

@@ -52,9 +52,20 @@ static struct option const longopts[] = {
static void print_usage(void) static void print_usage(void)
{ {
printf( fputs(
"usage: rgbgfx [-ADFfhmPTuVv] [-o outfile] [-a attrmap] [-d #] [-p palfile]\n" "Usage: rgbgfx [-CDhmuVv] [-f | -F] [-a <attr_map> | -A] [-d <depth>]\n"
" [-t tilemap] [-x #] infile\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); exit(1);
} }
@@ -69,9 +80,6 @@ int main(int argc, char *argv[])
struct Mapfile attrmap = {0}; struct Mapfile attrmap = {0};
char *ext; char *ext;
if (argc == 1)
print_usage();
opts.tilemapfile = ""; opts.tilemapfile = "";
opts.attrmapfile = ""; opts.attrmapfile = "";
opts.palfile = ""; opts.palfile = "";
@@ -145,8 +153,10 @@ int main(int argc, char *argv[])
argc -= optind; argc -= optind;
argv += optind; argv += optind;
if (argc == 0) if (argc == 0) {
fputs("FATAL: no input files\n", stderr);
print_usage(); print_usage();
}
#define WARN_MISMATCH(property) \ #define WARN_MISMATCH(property) \
warnx("The PNG's " property \ warnx("The PNG's " property \

137
src/gfx/rgbgfx.1
View File

@@ -5,20 +5,21 @@
.\" .\"
.\" SPDX-License-Identifier: MIT .\" SPDX-License-Identifier: MIT
.\" .\"
.Dd January 26, 2018 .Dd December 5, 2019
.Dt RGBGFX 1 .Dt RGBGFX 1
.Os RGBDS Manual .Os
.Sh NAME .Sh NAME
.Nm rgbgfx .Nm rgbgfx
.Nd Game Boy graphics converter .Nd Game Boy graphics converter
.Sh SYNOPSIS .Sh SYNOPSIS
.Nm rgbgfx .Nm
.Op Fl ACDfFhmPTuVv .Op Fl CDhmuVv
.Op Fl o Ar outfile .Op Fl f | Fl F
.Op Fl a Ar attrmap .Op Fl a Ar attrmap | Fl A
.Op Fl d Ar depth .Op Fl d Ar depth
.Op Fl p Ar palfile .Op Fl o Ar out_file
.Op Fl t Ar tilemap .Op Fl p Ar pal_file | Fl P
.Op Fl t Ar tilemap | Fl T
.Op Fl x Ar tiles .Op Fl x Ar tiles
.Ar file .Ar file
.Sh DESCRIPTION .Sh DESCRIPTION
@@ -26,106 +27,100 @@ The
.Nm .Nm
program converts PNG images into the Nintendo Game Boy's planar tile format. program converts PNG images into the Nintendo Game Boy's planar tile format.
The resulting colors and their palette indices are determined differently The resulting colors and their palette indices are determined differently depending on the input PNG file:
depending on the input PNG file:
.Bl -dash -width Ds .Bl -dash -width Ds
.It .It
If the file has an embedded palette, that palette's color and order are used. If the file has an embedded palette, that palette's color and order are used.
.It .It
If not, and the image only contains shades of gray, rgbgfx maps them to the If not, and the image only contains shades of gray, rgbgfx maps them to the indices appropriate for each shade.
indices appropriate for each shade. Any undetermined indices are set to Any undetermined indices are set to respective default shades of gray.
respective default shades of gray. For example: if the bit depth is 2 and the 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.
image contains light gray and black, they become the second and fourth colors - If the image has multiple shades that map to the same index, the palette is instead determined as if the image had color.
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 .It
If the image has color (or the grayscale method failed), the colors are sorted If the image has color (or the grayscale method failed), the colors are sorted from lightest to darkest.
from lightest to darkest.
.El .El
The input image may not contain more colors than the selected bit depth The input image may not contain more colors than the selected bit depth allows.
allows. Transparent pixels are set to palette index 0. Transparent pixels are set to palette index 0.
.Sh ARGUMENTS .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 .Bl -tag -width Ds
.It Fl a Ar attrmap .It Fl a Ar attrmap, Fl Fl attr-map Ar attrmap
Generate a file of tile mirroring attributes for OAM or (CGB-only) background Generate a file of tile mirroring attributes for OAM or (CGB-only) background tiles.
tiles. For each tile in the input file, a byte is written representing the 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.
dimensions that the associated tile in the output file should be mirrored.
Useful in combination with Useful in combination with
.Fl m .Fl m
to keep track the mirror direction of mirrored duplicate tiles. to keep track the mirror direction of mirrored duplicate tiles.
.It Fl A .It Fl A , Fl Fl output-attr-map
Same as Same as
.Fl a , .Fl a ,
but the attrmap file output name is made by taking the input filename, removing but the attrmap file output name is made by taking the input filename, removing the file extension, and appending
the file extension, and appending
.Pa .attrmap . .Pa .attrmap .
.It Fl C .It Fl C , Fl Fl color-curve
Use the color curve of the Game Boy Color when generating palettes. 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. 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). The bit depth of the output image (either 1 or 2).
By default, the bit depth is 2 (two bits per pixel). 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. Fix the input PNG file to be a correctly indexed image.
.It Fl F .It Fl F , Fl Fl fix-and-save
Same as Same as
.Fl f , .Fl f ,
but additionally, the supplied command line parameters are saved within the PNG but additionally, the supplied command line parameters are saved within the PNG and will be loaded and automatically used next time.
and will be loaded and automatically used next time. .It Fl h , Fl Fl horizontal
.It Fl h
Lay out tiles horizontally rather than vertically. Lay out tiles horizontally rather than vertically.
.It Fl m .It Fl m , Fl Fl mirror-tiles
Truncate tiles by checking for tiles that are mirrored versions of others and Truncate tiles by checking for tiles that are mirrored versions of others and omitting these from the output file.
omitting these from the output file. Useful with tilemaps and attrmaps together Useful with tilemaps and attrmaps together to keep track of the duplicated tiles and the dimension mirrored.
to keep track of the duplicated tiles and the dimension mirrored. Tiles are Tiles are checked for horizontal, vertical, and horizontal-vertical mirroring.
checked for horizontal, vertical, and horizontal-vertical mirroring. Implies Implies
.Fl u . .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. The name of the output file.
.It Fl p Ar palfile .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 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.
two bits per pixel, 4 bytes for one bit per pixel) containing the RGB15 values If the palette contains too few colors, the remaining entries are set to black.
in little-endian byte order. If the palette contains too few colors, the .It Fl P , Fl Fl output-palette
remaining entries are set to black.
.It Fl P
Same as Same as
.Fl p , .Fl p ,
but the palette file output name is made by taking the input PNG file's but the palette file output name is made by taking the input PNG file's filename, removing the file extension, and appending
filename, removing the file extension, and appending
.Pa .pal . .Pa .pal .
.It Fl t Ar tilemap .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 Generate a file of tile indices.
written representing the index of the associated tile in the output file. 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 Useful in combination with
.Fl u .Fl u
or or
.Fl m .Fl m
to keep track of duplicate tiles. to keep track of duplicate tiles.
.It Fl T .It Fl T , Fl Fl output-tilemap
Same as Same as
.Fl t , .Fl t ,
but the tilemap file output name is made by taking the input filename, removing but the tilemap file output name is made by taking the input filename, removing the file extension, and appending
the file extension, and appending
.Pa .tilemap . .Pa .tilemap .
.It Fl u .It Fl u , Fl Fl unique-tiles
Truncate tiles by checking for tiles that are exact duplicates of others and Truncate tiles by checking for tiles that are exact duplicates of others and omitting these from the output file.
omitting these from the output file. Useful with tilemaps to keep track of the Useful with tilemaps to keep track of the duplicated tiles.
duplicated tiles. .It Fl V , Fl Fl version
.It Fl V
Print the version of the program and exit. Print the version of the program and exit.
.It Fl v .It Fl v , Fl Fl verbose
Verbose. Verbose.
Print errors when the command line parameters and the parameters in Print errors when the command line parameters and the parameters in the PNG file don't match.
the PNG file don't match. .It Fl x Ar tiles , Fl Fl trim-end Ar tiles
.It Fl x Ar tiles
Trim the end of the output file by this many tiles. Trim the end of the output file by this many tiles.
.El .El
.Sh EXAMPLES .Sh EXAMPLES
The following will take a PNG file with a bit depth of 1, 2, or 8, and output The following will take a PNG file with a bit depth of 1, 2, or 8, and output planar 2bpp data:
planar 2bpp data:
.Pp .Pp
.D1 $ rgbgfx -o out.2bpp in.png .D1 $ rgbgfx -o out.2bpp in.png
.Pp .Pp
@@ -134,8 +129,9 @@ The following creates a planar 2bpp file with only unique tiles, and its tilemap
.Pp .Pp
.D1 $ rgbgfx -T -u -o out.2bpp in.png .D1 $ rgbgfx -T -u -o out.2bpp in.png
.Pp .Pp
The following creates a planar 2bpp file with only unique tiles (accounting for The following creates a planar 2bpp file with only unique tiles
tile mirroring) and its associated tilemap .Pa accounting for tile mirroring
and its associated tilemap
.Pa out.tilemap .Pa out.tilemap
and attrmap and attrmap
.Pa out.attrmap : .Pa out.attrmap :
@@ -145,6 +141,9 @@ and attrmap
The following will do nothing: The following will do nothing:
.Pp .Pp
.D1 $ rgbgfx in.png .D1 $ rgbgfx in.png
.Sh BUGS
Please report bugs on
.Lk https://github.com/rednex/rgbds/issues GitHub .
.Sh SEE ALSO .Sh SEE ALSO
.Xr rgbds 7 , .Xr rgbds 7 ,
.Xr rgbasm 1 , .Xr rgbasm 1 ,

18
src/link/main.c
View File

@@ -82,8 +82,20 @@ static struct option const longopts[] = {
*/ */
static void printUsage(void) static void printUsage(void)
{ {
puts("usage: rgblink [-dtVvw] [-l linkerscript] [-m mapfile] [-n symfile] [-O overlay]\n" fputs(
" [-o outfile] [-p pad_value] [-s symbol] file [...]"); "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 no input files were specified, the user must have screwed up */
if (curArgIndex == argc) { if (curArgIndex == argc) {
fputs("No input files\n", stderr); fputs("FATAL: no input files\n", stderr);
printUsage(); printUsage();
exit(1); exit(1);
} }

148
src/link/rgblink.1
View File

@@ -1,107 +1,128 @@
.\" .\"
.\" This file is part of RGBDS. .\" 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 .\" SPDX-License-Identifier: MIT
.\" .\"
.Dd January 26, 2018 .Dd November 26, 2019
.Dt RGBLINK 1 .Dt RGBLINK 1
.Os RGBDS Manual .Os
.Sh NAME .Sh NAME
.Nm rgblink .Nm rgblink
.Nd Game Boy linker .Nd Game Boy linker
.Sh SYNOPSIS .Sh SYNOPSIS
.Nm rgblink .Nm
.Op Fl dtVw .Op Fl dtVvw
.Op Fl m Ar mapfile .Op Fl l Ar linker_script
.Op Fl n Ar symfile .Op Fl m Ar map_file
.Op Fl O Ar overlayfile .Op Fl n Ar sym_file
.Op Fl o Ar outfile .Op Fl O Ar overlay_file
.Op Fl o Ar out_file
.Op Fl p Ar pad_value .Op Fl p Ar pad_value
.Op Fl s Ar symbol .Op Fl s Ar symbol
.Op Fl l Ar linkerscript
.Ar .Ar
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
program links objects created by program links RGB object files, typically created by
.Xr rgbasm 1 .Xr rgbasm 1 ,
into a single Game Boy ROM file. into a single Game Boy ROM file.
The format is documented in
.Xr rgbds 5 .
.Pp .Pp
By default, ROM0 sections created by the assembler are placed in the 16KiB ROM0 sections are placed in the first 16 KiB of the output ROM, and ROMX sections are placed in any 16 KiB
bank 0, and ROMX sections are placed in any bank except bank 0. .Dq bank
If your ROM will only be 32KiB, you can use the except the first.
If your ROM will only be 32 KiB, you can use the
.Fl t .Fl t
option to override this. option to change this.
.Pp .Pp
Similarly, WRAM0 sections are placed in the first 4KiB of WRAM bank 0 and WRAMX Similarly, WRAM0 sections are placed in the first 4 KiB of WRAM
sections are placed in any bank except bank 0. .Pq Dq bank 0 ,
If your ROM doesn't use banked WRAM you can use option 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 .Fl w
option to override this. option to change this.
.Pp .Pp
Also, if your ROM is designed for DMG, you can make sure that you don't use any 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
prohibited section by using the option .Fl d
.Fl d , option, which implies
which implies
.Fl w .Fl w
but also prohibits the use of VRAM bank 1. but also prohibits the use of banked VRAM.
.Pp .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: The arguments are as follows:
.Bl -tag -width Ds .Bl -tag -width Ds
.It Fl m Ar mapfile .It Fl d , Fl Fl dmg
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
Enable DMG mode. Enable DMG mode.
Prohibit the use of sections that doesn't exist on a DMG, such as WRAMX and VRAM Prohibit the use of sections that doesn't exist on a DMG, such as WRAMX and VRAM bank 1.
bank 1.
This option automatically enables This option automatically enables
.Fl w . .Fl w .
.It Fl t .It Fl l Ar linker_script, Fl Fl linkerscript Ar linker_script
Expand the ROM0 section size from 16KiB to the full 32KiB assigned to ROM and Specify a linker script file that tells the linker how sections must be placed in the ROM.
prohibit the use of ROMX sections. The attributes assigned in the linker script must be consistent with any assigned in the code.
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 See
.Xr rgblink 5 .Xr rgblink 5
for more information about its format. for more information about the linker script format.
.It Fl V .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. 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 .El
.Sh EXAMPLES .Sh EXAMPLES
All you need for a basic ROM is an object file, which can be made into a ROM All you need for a basic ROM is an object file, which can be made into a ROM image like so:
image like so:
.Pp .Pp
.D1 $ rgblink -o bar.gb foo.o .D1 $ rgblink -o bar.gb foo.o
.Pp .Pp
The resulting bar.gb will not have correct checksums The resulting
.Pq unless you put them in the assembly source . .Ar bar.gb
will not have correct checksums (unless you put them in the assembly source).
You should use You should use
.Xr rgbfix 1 .Xr rgbfix 1
to fix these so that the program will actually run in a Game Boy: to fix these so that the program will actually run in a Game Boy:
.Pp .Pp
.D1 $ rgbfix -v bar.gb .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 .Sh SEE ALSO
.Xr rgbasm 1 , .Xr rgbasm 1 ,
.Xr rgblink 5 , .Xr rgblink 5 ,
@@ -110,7 +131,6 @@ to fix these so that the program will actually run in a Game Boy:
.Xr rgbds 7 .Xr rgbds 7
.Sh HISTORY .Sh HISTORY
.Nm .Nm
was originally written by Carsten S\(/orensen as part of the ASMotor package, was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
and was later packaged in RGBDS by Justin Lloyd. It is now maintained by a It is now maintained by a number of contributors at
number of contributors at
.Lk https://github.com/rednex/rgbds . .Lk https://github.com/rednex/rgbds .

74
src/link/rgblink.5
View File

@@ -5,22 +5,16 @@
.\" .\"
.\" SPDX-License-Identifier: MIT .\" SPDX-License-Identifier: MIT
.\" .\"
.Dd January 27, 2018 .Dd November 26, 2019
.Dt RGBLINK 5 .Dt RGBLINK 5
.Os RGBDS Manual .Os
.Sh NAME .Sh NAME
.Nm rgblink .Nm rgblink
.Nd linkerscript file format .Nd linker script file format
.Sh DESCRIPTION .Sh DESCRIPTION
The linkerscript is an external file that allows the user to specify the 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.
order of sections without the need for doing so before assembling each object
file.
.Pp .Pp
The placement of sections specified in the linkerscript is done before the A linker script consists on a series of banks followed by a list of sections and, optionally, commands.
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.
They can be lowercase or uppercase, it is ignored. They can be lowercase or uppercase, it is ignored.
Any line can contain a comment starting with Any line can contain a comment starting with
.Ql \&; .Ql \&;
@@ -36,51 +30,53 @@ WRAMX 2
"Some variables" "Some variables"
.Ed .Ed
.Pp .Pp
Numbers can be in decimal or hexadecimal format (the prefix is Numbers can be in decimal or hexadecimal format
.Ql $ ) . .Pq the prefix is Ql $ .
It is an error if any section name or command are found before setting a bank. It is an error if any section name or command is found before setting a bank.
.Pp .Pp
Files can be included by using the Files can be included by using the
.Ar INCLUDE .Ic INCLUDE
keyword followed by a string with the path of the file that has to be included. keyword, followed by a string with the path of the file that has to be included.
.Pp .Pp
The possible bank types are: The possible bank types are:
.Sy ROM0 , ROMX , VRAM , WRAM0 , WRAMX , OAM .Cm ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM
and and
.Sy HRAM . .Cm HRAM .
Types Unless there is a single bank, which can occur with types
.Sy ROMX , VRAM , WRAMX .Cm ROMX , VRAM , SRAM
and and
.Sy SRAM .Cm WRAMX ,
are banked, which means that it is needed to specify a bank after the type. it is needed to specify a bank number after the type.
.Pp .Pp
When a new bank statement is found, sections found after it will be placed When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
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.
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.
.Pp .Pp
The only two commands are The only two commands are
.Ar ORG .Ic ORG
and and
.Ar ALIGN : .Ic ALIGN :
.Bl -bullet .Bl -bullet
.It .It
.Ar ORG .Ic ORG
sets the address in which new sections will be placed. sets the address in which new sections will be placed.
It can not be lower than the current address. It can not be lower than the current address.
.It .It
.Ar ALIGN .Ic ALIGN
will increase the address until it is aligned to the specified boundary (it will increase the address until it is aligned to the specified boundary
tries to set to 0 the number of bits specified after the command: .Po it tries to set to 0 the number of bits specified after the command:
.Sy ALIGN 8 .Ql ALIGN 8
will align to $100). will align to $100
.Pc .
.El .El
.Pp .Pp
Note: The bank, alignment, address and type of sections can be specified both .Sy Note:
in the source code and in the linkerscript. 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 linkerscript the bank must be 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.
left unassigned in the source code or be the same as the one specified in the For example,
linkerscript. The address and alignment musn't be set. .Ql ALIGN[8]
in the source code is compatible with
.Ql ORG $F00
in the linker script.
.Sh SEE ALSO .Sh SEE ALSO
.Xr rgbasm 1 , .Xr rgbasm 1 ,
.Xr rgblink 1 , .Xr rgblink 1 ,

40
src/rgbds.5
View File

@@ -7,7 +7,7 @@
.\" .\"
.Dd January 26, 2018 .Dd January 26, 2018
.Dt RGBDS 5 .Dt RGBDS 5
.Os RGBDS Manual .Os
.Sh NAME .Sh NAME
.Nm rgbds .Nm rgbds
.Nd object file format documentation .Nd object file format documentation
@@ -16,16 +16,14 @@ This is the description of the object files used by
.Xr rgbasm 1 .Xr rgbasm 1
and and
.Xr rgblink 1 . .Xr rgblink 1 .
Please, note that the specifications may change. .Em Please note that the specifications may change.
This toolchain is in development and new features may require adding more 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.
information to the current format, or modifying some fields, which would break
compatibility with older versions.
.Pp .Pp
.Sh FILE STRUCTURE .Sh FILE STRUCTURE
The following types are used: The following types are used:
.Pp .Pp
.Ar LONG .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 .Ar BYTE
is an 8‐bit integer. is an 8‐bit integer.
.Ar STRING .Ar STRING
@@ -131,17 +129,15 @@ ENDR
.Ss RPN DATA .Ss RPN DATA
Expressions in the object file are stored as RPN. Expressions in the object file are stored as RPN.
This is an expression of the form This is an expression of the form
.Do 2 5 + Dc . .Dq 2 5 + .
This will first push the value This will first push the value
.Do 2 Dc to the stack. .Do 2 Dc to the stack, then
Then .Dq 5 .
.Do 5 Dc .
The The
.Do + Dc operator pops two arguments from the stack, adds them, and then pushes .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.
the result on the stack, effectively replacing the two top arguments with their In the RGB format, RPN expressions are stored as
sum. .Ar BYTE Ns s
In the RGB format, RPN expressions are stored as BYTEs with some bytes being with some bytes being special prefixes for integers and symbols.
special prefixes for integers and symbols.
.Pp .Pp
.Bl -column -offset indent ".Sy String" ".Sy String" .Bl -column -offset indent ".Sy String" ".Sy String"
.It Sy Value Ta Sy Meaning .It Sy Value Ta Sy Meaning
@@ -166,19 +162,19 @@ special prefixes for integers and symbols.
.It Li $35 Ta Li <= comparison .It Li $35 Ta Li <= comparison
.It Li $40 Ta Li << operator .It Li $40 Ta Li << operator
.It Li $41 Ta Li >> operator .It Li $41 Ta Li >> operator
.It Li $50 Ta Li BANK(symbol), .It Li $50 Ta Li BANK(symbol) ,
a a
.Ar LONG .Ar LONG
Symbol ID follows. Symbol ID follows.
.It Li $51 Ta Li BANK(section_name), .It Li $51 Ta Li BANK(section_name) ,
a null-terminated string follows. 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. .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 .It Li $80 Ta Ar LONG
integer follows. integer follows.
.It Li $81 Ta Ar LONG .It Li $81 Ta Ar LONG
Symbol ID follows. symbol ID follows.
.El .El
.Pp .Pp
.Sh SEE ALSO .Sh SEE ALSO
@@ -187,7 +183,7 @@ Symbol ID follows.
.Xr rgbds 7 , .Xr rgbds 7 ,
.Xr gbz80 7 .Xr gbz80 7
.Sh HISTORY .Sh HISTORY
.Nm rgbds .Nm
was originally written by Carsten S\(/orensen as part of the ASMotor package, was originally written by Carsten S\(/orensen as part of the ASMotor package,
and was later packaged in RGBDS by Justin Lloyd. and was later packaged in RGBDS by Justin Lloyd.
It is now maintained by a number of contributors at It is now maintained by a number of contributors at

2
src/rgbds.7
View File

@@ -7,7 +7,7 @@
.\" .\"
.Dd March 7, 2018 .Dd March 7, 2018
.Dt RGBDS 7 .Dt RGBDS 7
.Os RGBDS Manual .Os
.Sh NAME .Sh NAME
.Nm rgbds .Nm rgbds
.Nd Rednex Game Boy Development System .Nd Rednex Game Boy Development System