gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-27 13:32:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Move all man pages to a separate directory

Browse Source 
Simplifies processing all around, and makes more sense
This commit is contained in:
ISSOtm
2022-05-15 13:11:20 +02:00
parent 0195196425
commit 7e94ecbfe6
15 changed files with 70 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
src/CMakeLists.txt
View File

@@ -97,22 +97,6 @@ foreach(PROG "asm" "fix" "gfx" "link")
install(TARGETS rgb${PROG} RUNTIME DESTINATION bin)
endforeach()
set(MANDIR "share/man")
set(man1 "asm/rgbasm.1"
"fix/rgbfix.1"
"gfx/rgbgfx.1"
"link/rgblink.1")
set(man5 "asm/rgbasm.5"
"link/rgblink.5"
"rgbds.5")
set(man7 "gbz80.7"
"rgbds.7")
foreach(SECTION "man1" "man5" "man7")
set(DEST "${MANDIR}/${SECTION}")
install(FILES ${${SECTION}} DESTINATION ${DEST})
endforeach()
if(LIBPNG_FOUND) # pkg-config
target_include_directories(rgbgfx PRIVATE ${LIBPNG_INCLUDE_DIRS})
target_link_directories(rgbgfx PRIVATE ${LIBPNG_LIBRARY_DIRS})

315
src/asm/rgbasm.1
View File

@@ -1,315 +0,0 @@
.\"
.\" This file is part of RGBDS.
.\"
.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd March 28, 2021
.Dt RGBASM 1
.Os
.Sh NAME
.Nm rgbasm
.Nd Game Boy assembler
.Sh SYNOPSIS
.Nm
.Op Fl EhLVvw
.Op Fl b Ar chars
.Op Fl D Ar name Ns Op = Ns Ar value
.Op Fl g Ar chars
.Op Fl i Ar path
.Op Fl M Ar depend_file
.Op Fl MG
.Op Fl MP
.Op Fl MT Ar target_file
.Op Fl MQ Ar target_file
.Op Fl o Ar out_file
.Op Fl p Ar pad_value
.Op Fl r Ar recursion_depth
.Op Fl W Ar warning
.Ar
.Sh DESCRIPTION
The
.Nm
program creates an RGB object file from an assembly source file.
The input
.Ar file
can be a file path, or
.Cm \-
denoting
.Cm stdin .
.Pp
Note that options can be abbreviated as long as the abbreviation is unambiguous:
.Fl Fl verb
is
.Fl Fl verbose ,
but
.Fl Fl ver
is invalid because it could also be
.Fl Fl version .
The arguments are as follows:
.Bl -tag -width Ds
.It Fl b Ar chars , Fl Fl binary-digits Ar chars
Change the two characters used for binary constants.
The defaults are 01.
.It Fl D Ar name Ns Oo = Ns Ar value Oc , Fl Fl define Ar name Ns Oo = Ns Ar value Oc
Add a string symbol to the compiled source code.
This is equivalent to
.Ql Ar name Ic EQUS \(dq Ns Ar value Ns \(dq
in code, or
.Ql Ar name Ic EQUS \(dq1\(dq
if
.Ar value
is not specified.
.It Fl E , Fl Fl export-all
Export all labels, including unreferenced and local labels.
.It Fl g Ar chars , Fl Fl gfx-chars Ar chars
Change the four characters used for gfx constants.
The defaults are 0123.
.It Fl h , Fl Fl halt-without-nop
By default,
.Nm
inserts a
.Ic nop
instruction immediately after any
.Ic halt
instruction.
The
.Fl h
option disables this behavior.
.It Fl i Ar path , Fl Fl include Ar path
Add an include path.
.It Fl L , Fl Fl preserve-ld
Disable the optimization that turns loads of the form
.Ic LD [$FF00+n8],A
into the opcode
.Ic LDH [$FF00+n8],A
in order to have full control of the result in the final ROM.
.It Fl M Ar depend_file , Fl Fl dependfile Ar depend_file
Print
.Xr make 1
dependencies to
.Ar depend_file .
.It Fl MG
To be used in conjunction with
.Fl M .
This makes
.Nm
assume that missing files are auto-generated: when
.Ic INCLUDE
or
.Ic INCBIN
is attempted on a non-existent file, it is added as a dependency, then
.Nm
exits normally instead of erroring out.
This feature is used in automatic updating of makefiles.
.It Fl MP
When enabled, this causes a phony target to be added for each dependency other than the main file.
This prevents
.Xr make 1
from erroring out when dependency files are deleted.
.It Fl MT Ar target_file
Add a target to the rules emitted by
.Fl M .
The exact string provided will be written, including spaces and special characters.
.Dl Fl MT No fileA Fl MT No fileB
is equivalent to
.Dl Fl MT No 'fileA fileB' .
If neither this nor
.Fl MQ
is specified, the output file name is used.
.It Fl MQ Ar target_file
Same as
.Fl MT ,
but additionally escapes any special
.Xr make 1
characters, essentially
.Sq $ .
.It Fl o Ar out_file , Fl Fl output Ar out_file
Write an object file to the given filename.
.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
When padding an image, pad with this value.
The default is 0x00.
.It Fl r Ar recursion_depth , Fl Fl recursion-depth Ar recursion_depth
Specifies the recursion depth at which RGBASM will assume being in an infinite loop.
.It Fl V , Fl Fl version
Print the version of the program and exit.
.It Fl v , Fl Fl verbose
Be verbose.
.It Fl W Ar warning , Fl Fl warning Ar warning
Set warning flag
.Ar warning .
A warning message will be printed if
.Ar warning
is an unknown warning flag.
See the
.Sx DIAGNOSTICS
section for a list of warnings.
.It Fl w
Disable all warning output, even when turned into errors.
.El
.Sh DIAGNOSTICS
Warnings are diagnostic messages that indicate possibly erroneous behavior that does not necessarily compromise the assembling process.
The following options alter the way warnings are processed.
.Bl -tag -width Ds
.It Fl Werror
Make all warnings into errors.
.It Fl Werror=
Make the specified warning into an error.
A warning's name is appended
.Pq example: Fl Werror=obsolete ,
and this warning is implicitly enabled and turned into an error.
This is an error if used with a meta warning, such as
.Fl Werror=all .
.El
.Pp
The following warnings are
.Dq meta
warnings, that enable a collection of other warnings.
If a specific warning is toggled via a meta flag and a specific one, the more specific one takes priority.
The position on the command-line acts as a tie breaker, the last one taking effect.
.Bl -tag -width Ds
.It Fl Wall
This enables warnings that are likely to indicate an error or undesired behavior, and that can easily be fixed.
.It Fl Wextra
This enables extra warnings that are less likely to pose a problem, but that may still be wanted.
.It Fl Weverything
Enables literally every warning.
.El
.Pp
The following warnings are actual warning flags; with each description, the corresponding warning flag is included.
Note that each of these flag also has a negation (for example,
.Fl Wcharmap-redef
enables the warning that
.Fl Wno-charmap-redef
disables).
Only the non-default flag is listed here.
Ignoring the
.Dq no-
prefix, entries are listed alphabetically.
.Bl -tag -width Ds
.It Fl Wno-assert
Warn when
.Ic WARN Ns No -type
assertions fail. (See
.Dq Aborting the assembly process
in
.Xr rgbasm 5
for
.Ic ASSERT ) .
.It Fl Wbackwards-for
Warn when
.Ic FOR
loops have their start and stop values switched according to the step value.
This warning is enabled by
.Fl Wall .
.It Fl Wbuiltin-args
Warn about incorrect arguments to built-in functions, such as
.Fn STRSUB
with indexes outside of the string's bounds.
This warning is enabled by
.Fl Wall .
.It Fl Wcharmap-redef
Warn when re-defining a charmap mapping.
This warning is enabled by
.Fl Wall .
.It Fl Wdiv
Warn when dividing the smallest negative integer (-2**31) by -1, which yields itself due to integer overflow.
.It Fl Wempty-macro-arg
Warn when a macro argument is empty.
This warning is enabled by
.Fl Wextra .
.It Fl Wempty-strrpl
Warn when
.Fn STRRPL
is called with an empty string as its second argument (the substring to replace).
This warning is enabled by
.Fl Wall .
.It Fl Wlarge-constant
Warn when a constant too large to fit in a signed 32-bit integer is encountered.
This warning is enabled by
.Fl Wall .
.It Fl Wlong-string
Warn when a string too long to fit in internal buffers is encountered.
This warning is enabled by
.Fl Wall .
.It Fl Wmacro-shift
Warn when shifting macro arguments past their limits.
This warning is enabled by
.Fl Wextra .
.It Fl Wno-obsolete
Warn when obsolete constructs such as the
.Ic _PI
constant or
.Ic PRINTT
directive are encountered.
.It Fl Wnumeric-string=
Warn when a multi-character string is treated as a number.
.Fl Wnumeric-string=0
or
.Fl Wno-numeric-string
disables this warning.
.Fl Wnumeric-string=1
or just
.Fl Wnumeric-string
warns about strings longer than four characters, since four or fewer characters fit within a 32-bit integer.
.Fl Wnumeric-string=2
warns about any multi-character string.
.It Fl Wshift
Warn when shifting right a negative value.
Use a division by 2**N instead.
.It Fl Wshift-amount
Warn when a shift's operand is negative or greater than 32.
.It Fl Wtruncation=
Warn when an implicit truncation (for example,
.Ic db
to an 8-bit value) loses some bits.
.Fl Wtruncation=0
or
.Fl Wno-truncation
disables this warning.
.Fl Wtruncation=1
warns when an N-bit value's absolute value is 2**N or greater.
.Fl Wtruncation=2
or just
.Fl Wtruncation
also warns when an N-bit value is less than -2**(N-1), which will not fit in two's complement encoding.
.It Fl Wno-user
Warn when the
.Ic WARN
built-in is executed. (See
.Dq Aborting the assembly process
in
.Xr rgbasm 5
for
.Ic WARN ) .
.El
.Sh EXAMPLES
You can assemble a source file in two ways.
.Pp
Straightforward way:
.Dl $ rgbasm -o bar.o foo.asm
.Pp
Pipes way:
.Dl $ cat foo.asm | rgbasm -o bar.o -
.Dl $ rgbasm -o bar.o - < foo.asm
.Pp
The resulting object file is not yet a usable ROM image\(emit must first be run through
.Xr rgblink 1
and then
.Xr rgbfix 1 .
.Sh BUGS
Please report bugs on
.Lk https://github.com/gbdev/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbasm 5 ,
.Xr rgbfix 1 ,
.Xr rgblink 1 ,
.Xr rgbds 5 ,
.Xr rgbds 7 ,
.Xr gbz80 7
.Sh HISTORY
.Nm
was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .

2071
src/asm/rgbasm.5
View File

File diff suppressed because it is too large Load Diff

243
src/fix/rgbfix.1
View File

@@ -1,243 +0,0 @@
.\"
.\" This file is part of RGBDS.
.\"
.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd March 28, 2021
.Dt RGBFIX 1
.Os
.Sh NAME
.Nm rgbfix
.Nd Game Boy header utility and checksum fixer
.Sh SYNOPSIS
.Nm
.Op Fl jOsVv
.Op Fl C | c
.Op Fl f Ar fix_spec
.Op Fl i Ar game_id
.Op Fl k Ar licensee_str
.Op Fl l Ar licensee_id
.Op Fl m Ar mbc_type
.Op Fl n Ar rom_version
.Op Fl p Ar pad_value
.Op Fl r Ar ram_size
.Op Fl t Ar title_str
.Op Ar
.Sh DESCRIPTION
The
.Nm
program changes headers of Game Boy ROM images, typically generated by
.Xr rgblink 1 ,
though it will work with
.Em any
Game Boy ROM.
It also performs other correctness operations, such as padding.
.Nm
only changes the fields for which it has values specified.
Developers are advised to fill those fields with 0x00 bytes in their source code before running
.Nm ,
and to have already populated whichever fields they don't specify using
.Nm .
.Pp
Note that options can be abbreviated as long as the abbreviation is unambiguous:
.Fl Fl color-o
is
.Fl Fl color-only ,
but
.Fl Fl color
is invalid because it could also be
.Fl Fl color-compatible .
Options later in the command line override those set earlier.
Accepted options are as follows:
.Bl -tag -width Ds
.It Fl C , Fl Fl color-only
Set the Game Boy Color\(enonly flag
.Pq Ad 0x143
to 0xC0.
This overrides
.Fl c
if it was set prior.
.It Fl c , Fl Fl color-compatible
Set the Game Boy Color\(encompatible flag:
.Pq Ad 0x143
to 0x80.
This overrides
.Fl c
if it was set prior.
.It Fl f Ar fix_spec , Fl Fl fix-spec Ar fix_spec
Fix certain header values that the Game Boy checks for correctness.
Alternatively, intentionally trash these values by writing their binary inverse instead.
.Ar fix_spec
is a string containing any combination of the following characters:
.Pp
.Bl -tag -compact -width xx
.It Cm l
Fix the Nintendo logo
.Pq Ad 0x104 Ns \(en Ns Ad 0x133 .
.It Cm L
Trash the Nintendo logo.
.It Cm h
Fix the header checksum
.Pq Ad 0x14D .
.It Cm H
Trash the header checksum.
.It Cm g
Fix the global checksum
.Pq Ad 0x14E Ns \(en Ns Ad 0x14F .
.It Cm G
Trash the global checksum.
.El
.It Fl i Ar game_id , Fl Fl game-id Ar game_id
Set the game ID string
.Pq Ad 0x13F Ns \(en Ns Ad 0x142
to a given string.
If it's longer than 4 chars, it will be truncated, and a warning emitted.
.It Fl j , Fl Fl non-japanese
Set the non-Japanese region flag
.Pq Ad 0x14A
to 0x01.
.It Fl k Ar licensee_str , Fl Fl new-licensee Ar licensee_str
Set the new licensee string
.Pq Ad 0x144 Ns \(en Ns Ad 0x145
to a given string.
If it's longer than 2 chars, it will be truncated, and a warning emitted.
.It Fl l Ar licensee_id , Fl Fl old-licensee Ar licensee_id
Set the old licensee code
.Pq Ad 0x14B
to a given value from 0 to 0xFF.
This value is deprecated and should be set to 0x33 in all new software.
.It Fl m Ar mbc_type , Fl Fl mbc-type Ar mbc_type
Set the MBC type
.Pq Ad 0x147
to a given value from 0 to 0xFF.
.Pp
This value may also be an MBC name.
The list of accepted names can be obtained by passing
.Ql Cm help
as the argument.
Any amount of whitespace (space and tabs) is allowed around plus signs, and the order of "components" is free, as long as the MBC name is first.
There are special considerations to take for the TPP1 mapper; see the
.Sx TPP1
section below.
.It Fl n Ar rom_version , Fl Fl rom-version Ar rom_version
Set the ROM version
.Pq Ad 0x14C
to a given value from 0 to 0xFF.
.It Fl O , Fl Fl overwrite
Allow overwriting different non-zero bytes in the header without a warning being emitted.
.It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
Pad the ROM image to a valid size with a given pad value from 0 to 255 (0xFF).
.Nm
will automatically pick a size from 32 KiB, 64 KiB, 128 KiB, ..., 8192 KiB.
The cartridge size byte
.Pq Ad 0x148
will be changed to reflect this new size.
The recommended padding value is 0xFF, to speed up writing the ROM to flash chips, and to avoid "nop slides" into VRAM.
.It Fl r Ar ram_size , Fl Fl ram-size Ar ram_size
Set the RAM size
.Pq Ad 0x149
to a given value from 0 to 0xFF.
.It Fl s , Fl Fl sgb-compatible
Set the SGB flag
.Pq Ad 0x146
to 0x03.
This flag will be ignored by the SGB unless the old licensee code is 0x33!
If this is given as well as
.Fl l ,
but is not set to 0x33, a warning will be printed.
.It Fl t Ar title , Fl Fl title Ar title
Set the title string
.Pq Ad 0x134 Ns \(en Ns Ad 0x143
to a given string.
If the title is longer than the max length, it will be truncated, and a warning emitted.
The max length is 11 characters if the game ID
.Pq Fl i
is specified, 15 characters if the CGB flag
.Fl ( c
or
.Fl C )
is specified but the game ID is not, and 16 characters otherwise.
.It Fl V , Fl Fl version
Print the version of the program and exit.
.It Fl v , Fl Fl validate
Equivalent to
.Fl f Cm lhg .
.El
.Sh EXAMPLES
Most values in the ROM header do not matter to the actual console, and most are seldom useful anyway.
The bare minimum requirements for a workable program are the header checksum, the Nintendo logo, and (if needed) the CGB/SGB flags.
It is a good idea to pad the image to a valid size as well
.Pq Do valid Dc meaning a power of 2, times 32 KiB .
.Pp
The following will make a plain, non-color Game Boy game without checking for
a valid size:
.Pp
.D1 $ rgbfix -v foo.gb
.Pp
The following will make a SGB-enabled, color-enabled game with a title of
.Dq foobar ,
and pad it to a valid size.
.Pq The Game Boy itself does not use the title, but some emulators or ROM managers do.
.Pp
.D1 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
.Pp
The following will duplicate the header of the game
.Dq Survival Kids ,
sans global checksum:
.Pp
.D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \
SurvivalKids.gbc
.Sh TPP1
TPP1 is a homebrew mapper designed as a functional superset of the common traditional MBCs, allowing larger ROM and RAM sizes combined with other hardware features.
Its specification, as well as more resources, can be found online at
.Lk https://github.com/TwitchPlaysPokemon/tpp1 .
.Ss MBC name
The MBC name for TPP1 is more complex than standard mappers.
It must be followed with the revision number, of the form
.Ql major.minor ,
where both
.Ql major
and
.Ql minor
are decimal, 8-bit integers.
There may be any amount of spaces or underscores between
.Ql TPP1
and the revision number.
.Nm
only supports 1.x revisions, and will reject everything else.
.Pp
Like other mappers, the name may be followed with a list of optional,
.Ql + Ns
-separated features; however,
.Ql RAM
should not be specified, as the TPP1 mapper implicitly requests RAM if a non-zero RAM size is specified.
Therefore,
.Nm
will ignore the
.Ql RAM
feature on a TPP1 mapper with a warning.
.Ss Special considerations
TPP1 overwrites the byte at
.Ad 0x14A ,
usually indicating the region destination
.Pq see Fl j ,
with one of its three identification bytes.
Therefore,
.Nm
will warn about and ignore
.Fl j
if used in combination with TPP1.
.Sh BUGS
Please report bugs on
.Lk https://github.com/gbdev/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
.Xr rgbds 7
.Sh HISTORY
.Nm
was originally released by Carsten S\(/orensen as a standalone program called gbfix, and was later packaged in RGBDS by Justin Lloyd.
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .

1881
src/gbz80.7
View File

File diff suppressed because it is too large Load Diff

160
src/gfx/rgbgfx.1
View File

@@ -1,160 +0,0 @@
.\"
.\" This file is part of RGBDS.
.\"
.\" Copyright (c) 2013-2021, stag019 and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd March 28, 2021
.Dt RGBGFX 1
.Os
.Sh NAME
.Nm rgbgfx
.Nd Game Boy graphics converter
.Sh SYNOPSIS
.Nm
.Op Fl CDhmuVv
.Op Fl f | Fl F
.Op Fl a Ar attrmap | Fl A
.Op Fl d Ar depth
.Op Fl o Ar out_file
.Op Fl p Ar pal_file | Fl P
.Op Fl t Ar tilemap | Fl T
.Op Fl x Ar tiles
.Ar file
.Sh DESCRIPTION
The
.Nm
program converts PNG images into the Nintendo Game Boy's planar tile format.
.Pp
The resulting colors and their palette indices are determined differently depending on the input PNG file:
.Bl -dash -width Ds
.It
If the file has an embedded palette, that palette's color and order are used.
.It
If not, and the image only contains shades of gray, rgbgfx maps them to the indices appropriate for each shade.
Any undetermined indices are set to respective default shades of gray.
For example: if the bit depth is 2 and the image contains light gray and black, they become the second and fourth colors, and the first and third colors get set to default white and dark gray.
If the image has multiple shades that map to the same index, the palette is instead determined as if the image had color.
.It
If the image has color (or the grayscale method failed), the colors are sorted from lightest to darkest.
.El
.Pp
The input image may not contain more colors than the selected bit depth allows.
Transparent pixels are set to palette index 0.
.Sh ARGUMENTS
Note that options can be abbreviated as long as the abbreviation is unambiguous:
.Fl Fl verb
is
.Fl Fl verbose ,
but
.Fl Fl ver
is invalid because it could also be
.Fl Fl version .
The arguments are as follows:
.Bl -tag -width Ds
.It Fl a Ar attrmap , Fl Fl attr-map Ar attrmap
Generate a file of tile mirroring attributes for OAM or (CGB-only) background tiles.
For each tile in the input file, a byte is written representing the dimensions that the associated tile in the output file should be mirrored.
Useful in combination with
.Fl m
to keep track the mirror direction of mirrored duplicate tiles.
.It Fl A , Fl Fl output-attr-map
Same as
.Fl a ,
but the attrmap file output name is made by taking the input filename, removing the file extension, and appending
.Pa .attrmap .
.It Fl C , Fl Fl color-curve
Use the color curve of the Game Boy Color when generating palettes.
.It Fl D , Fl Fl debug
Debug features are enabled.
.It Fl d Ar depth , Fl Fl depth Ar depth
The bit depth of the output image (either 1 or 2).
By default, the bit depth is 2 (two bits per pixel).
.It Fl f , Fl Fl fix
Fix the input PNG file to be a correctly indexed image.
.It Fl F , Fl Fl fix-and-save
Same as
.Fl f ,
but additionally, the supplied command line parameters are saved within the PNG and will be loaded and automatically used next time.
.It Fl h , Fl Fl horizontal
Lay out tiles in column-major order (column by column), instead of the default row-major order (line by line).
Especially useful for "8x16" OBJ mode, if the input image is 16 pixels tall.
.It Fl m , Fl Fl mirror-tiles
Truncate tiles by checking for tiles that are mirrored versions of others and omitting these from the output file.
Useful with tilemaps and attrmaps together to keep track of the duplicated tiles and the dimension mirrored.
Tiles are checked for horizontal, vertical, and horizontal-vertical mirroring.
Implies
.Fl u .
.It Fl o Ar out_file , Fl Fl output Ar out_file
The name of the output file.
.It Fl p Ar pal_file , Fl Fl palette Ar pal_file
Output the image's palette in standard GBC palette format: bytes (8 bytes for two bits per pixel, 4 bytes for one bit per pixel) containing the RGB15 values in little-endian byte order.
If the palette contains too few colors, the remaining entries are set to black.
.It Fl P , Fl Fl output-palette
Same as
.Fl p ,
but the palette file output name is made by taking the input PNG file's filename, removing the file extension, and appending
.Pa .pal .
.It Fl t Ar tilemap , Fl Fl tilemap Ar tilemap
Generate a file of tile indices.
For each tile in the input file, a byte is written representing the index of the associated tile in the output file.
Useful in combination with
.Fl u
or
.Fl m
to keep track of duplicate tiles.
.It Fl T , Fl Fl output-tilemap
Same as
.Fl t ,
but the tilemap file output name is made by taking the input filename, removing the file extension, and appending
.Pa .tilemap .
.It Fl u , Fl Fl unique-tiles
Truncate tiles by checking for tiles that are exact duplicates of others and omitting these from the output file.
Useful with tilemaps to keep track of the duplicated tiles.
.It Fl V , Fl Fl version
Print the version of the program and exit.
.It Fl v , Fl Fl verbose
Verbose.
Print errors when the command line parameters and the parameters in the PNG file don't match.
.It Fl x Ar tiles , Fl Fl trim-end Ar tiles
Trim the end of the output file by this many tiles.
.El
.Sh EXAMPLES
The following will take a PNG file with a bit depth of 1, 2, or 8, and output planar 2bpp data:
.Pp
.D1 $ rgbgfx -o out.2bpp in.png
.Pp
The following creates a planar 2bpp file with only unique tiles, and its tilemap
.Pa out.tilemap :
.Pp
.D1 $ rgbgfx -T -u -o out.2bpp in.png
.Pp
The following creates a planar 2bpp file with only unique tiles
.Pa accounting for tile mirroring
and its associated tilemap
.Pa out.tilemap
and attrmap
.Pa out.attrmap :
.Pp
.D1 $ rgbgfx -A -T -m -o out.2bpp in.png
.Pp
The following will do nothing:
.Pp
.D1 $ rgbgfx in.png
.Sh BUGS
Please report bugs on
.Lk https://github.com/gbdev/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbds 7 ,
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
.Xr rgbfix 1 ,
.Xr gbz80 7
.Sh HISTORY
.Nm
was created by
.An stag019
to be included in RGBDS.
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .

205
src/link/rgblink.1
View File

@@ -1,205 +0,0 @@
.\"
.\" This file is part of RGBDS.
.\"
.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd March 28, 2021
.Dt RGBLINK 1
.Os
.Sh NAME
.Nm rgblink
.Nd Game Boy linker
.Sh SYNOPSIS
.Nm
.Op Fl dtVvwx
.Op Fl l Ar linker_script
.Op Fl m Ar map_file
.Op Fl n Ar sym_file
.Op Fl O Ar overlay_file
.Op Fl o Ar out_file
.Op Fl p Ar pad_value
.Op Fl S Ar spec
.Op Fl s Ar symbol
.Ar
.Sh DESCRIPTION
The
.Nm
program links RGB object files, typically created by
.Xr rgbasm 1 ,
into a single Game Boy ROM file.
The format is documented in
.Xr rgbds 5 .
.Pp
ROM0 sections are placed in the first 16 KiB of the output ROM, and ROMX sections are placed in any 16 KiB
.Dq bank
except the first.
If your ROM will only be 32 KiB, you can use the
.Fl t
option to change this.
.Pp
Similarly, WRAM0 sections are placed in the first 4 KiB of WRAM
.Pq Dq bank 0 ,
and WRAMX sections are placed in any bank of the last 4 KiB.
If your ROM doesn't use banked WRAM, you can use the
.Fl w
option to change this.
.Pp
Also, if your ROM is designed for a monochrome Game Boy, you can make sure that you don't use any incompatible section by using the
.Fl d
option, which implies
.Fl w
but also prohibits the use of banked VRAM.
.Pp
Note that options can be abbreviated as long as the abbreviation is unambiguous:
.Fl Fl verb
is
.Fl Fl verbose ,
but
.Fl Fl ver
is invalid because it could also be
.Fl Fl version .
The arguments are as follows:
.Bl -tag -width Ds
.It Fl d , Fl Fl dmg
Enable DMG mode.
Prohibit the use of sections that doesn't exist on a DMG, such as VRAM bank 1.
This option automatically enables
.Fl w .
.It Fl l Ar linker_script , Fl Fl linkerscript Ar linker_script
Specify a linker script file that tells the linker how sections must be placed in the ROM.
The attributes assigned in the linker script must be consistent with any assigned in the code.
See
.Xr rgblink 5
for more information about the linker script format.
.It Fl m Ar map_file , Fl Fl map Ar map_file
Write a map file to the given filename, listing how sections and symbols were assigned.
.It Fl n Ar sym_file , Fl Fl sym Ar sym_file
Write a symbol file to the given filename, listing the address of all exported symbols.
Several external programs can use this information, for example to help debugging ROMs.
.It Fl O Ar overlay_file , Fl Fl overlay Ar overlay_file
If specified, sections will be overlaid "on top" of the provided ROM image.
In that case, all sections must be fixed.
This may be used to patch an existing binary.
.It Fl o Ar out_file , Fl Fl output Ar out_file
Write the ROM image to the given file.
.It Fl p Ar pad_value , Fl Fl pad Ar pad_value
When inserting padding between sections, pad with this value.
Has no effect if
.Fl O
is specified.
The default is 0.
.It Fl S Ar spec , Fl Fl scramble Ar spec
Enables a different
.Dq scrambling
algorithm for placing sections.
See
.Sx Scrambling algorithm
below for an explanation and a description of
.Ar spec .
.It Fl s Ar symbol , Fl Fl smart Ar symbol
This option is ignored.
It was supposed to perform smart linking but fell into disrepair, and so has been removed.
It will be reimplemented at some point.
.It Fl t , Fl Fl tiny
Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to ROM.
ROMX sections that are fixed to a bank other than 1 become errors, other ROMX sections are treated as ROM0.
Useful for ROMs that fit in 32 KiB.
.It Fl V , Fl Fl version
Print the version of the program and exit.
.It Fl v , Fl Fl verbose
Verbose: enable printing more information to standard error.
.It Fl w , Fl Fl wramx
Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to WRAM.
WRAMX sections that are fixed to a bank other than 1 become errors, other WRAMX sections are treated as WRAM0.
.It Fl x , Fl Fl nopad
Disables padding the end of the final file.
This option automatically enables
.Fl t .
You can use this when not not making a ROM.
When making a ROM, be careful that not using this is not a replacement for
.Xr rgbfix 1 Ap s Fl p
option!
.El
.Ss Scrambling algorithm
The default section placement algorithm tries to minimize the number of banks used;
.Dq scrambling
instead places sections into a given pool of banks, trying to minimize the number of sections sharing a given bank.
This is useful to catch broken bank assumptions, such as expecting two different sections to land in the same bank (that is not guaranteed unless both are manually assigned the same bank number).
.Pp
A scrambling spec is a comma-separated list of region specs.
A trailing comma is allowed, as well as whitespace between all specs and their components.
Each region spec has the following form:
.D1 Ar region Ns Op = Ns Ar size
.Ar region
must be one of the following (case-insensitive), while
.Ar size
must be a positive decimal integer between 1 and the corresponding maximum.
Certain regions allow omitting the size, in which case it defaults to its max value.
.Bl -column "Region name" "Max value" "Size optional"
Region name Ta Max size Ta Size optional
.Cm romx Ta 65535 Ta \&No
.Cm sram Ta 255 Ta \&No
.Cm wramx Ta 7 Ta Yes
.El
.Pp
A
.Ar size
of 0 disables scrambling for that region.
.Pp
For example,
.Ql romx=64,wramx=4
will scramble
.Ic ROMX
sections among ROM banks 1 to 64,
.Ic WRAMX
sections among RAM banks 1 to 4, and will not scramble
.Ic SRAM
sections.
.Pp
Later region specs override earlier ones; for example,
.Ql romx=42, Romx=0
disables scrambling for
.Cm romx .
.Pp
.Cm wramx
scrambling is silently ignored if
.Fl w
is passed (including if implied by
.Fl d ) ,
as
.Ic WRAMX
sections will be treated as
.Ic WRAM0 .
.Sh EXAMPLES
All you need for a basic ROM is an object file, which can be made into a ROM image like so:
.Pp
.Dl $ rgblink -o bar.gb foo.o
.Pp
The resulting
.Ar bar.gb
will not have correct checksums (unless you put them in the assembly source).
You should use
.Xr rgbfix 1
to fix these so that the program will actually run in a Game Boy:
.Pp
.Dl $ rgbfix -v bar.gb
.Pp
Here is a more complete example:
.Pp
.Dl $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o
.Sh BUGS
Please report bugs on
.Lk https://github.com/gbdev/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 5 ,
.Xr rgbfix 1 ,
.Xr rgbds 5 ,
.Xr rgbds 7
.Sh HISTORY
.Nm
was originally written by Carsten S\(/orensen as part of the ASMotor package, and was later packaged in RGBDS by Justin Lloyd.
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .

90
src/link/rgblink.5
View File

@@ -1,90 +0,0 @@
.\"
.\" This file is part of RGBDS.
.\"
.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd March 28, 2021
.Dt RGBLINK 5
.Os
.Sh NAME
.Nm rgblink
.Nd linker script file format
.Sh DESCRIPTION
The linker script is an external file that allows the user to specify the order of sections at link time and in a centralized manner.
.Pp
A linker script consists on a series of banks followed by a list of sections and, optionally, commands.
They can be lowercase or uppercase, it is ignored.
Any line can contain a comment starting with
.Ql \&;
that ends at the end of the line:
.Bd -literal -offset indent
ROMX $F ; This is a comment
"Functions to read array"
ALIGN 8
"Array aligned to 256 bytes"
WRAMX 2
"Some variables"
.Ed
.Pp
Numbers can be in decimal or hexadecimal format
.Pq the prefix is Ql $ .
It is an error if any section name or command is found before setting a bank.
.Pp
Files can be included by using the
.Ic INCLUDE
keyword, followed by a string with the path of the file that has to be included.
.Pp
The possible bank types are:
.Cm ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM
and
.Cm HRAM .
Unless there is a single bank, which can occur with types
.Cm ROMX , VRAM , SRAM
and
.Cm WRAMX ,
it is needed to specify a bank number after the type.
.Pp
When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
If the linker script switches to a different bank and then comes back to a previous one, it will continue from the last address that was used.
.Pp
The only two commands are
.Ic ORG
and
.Ic ALIGN :
.Bl -bullet
.It
.Ic ORG
sets the address in which new sections will be placed.
It can not be lower than the current address.
.It
.Ic ALIGN
will increase the address until it is aligned to the specified boundary
.Po it tries to set to 0 the number of bits specified after the command:
.Ql ALIGN 8
will align to $100
.Pc .
.El
.Pp
.Sy Note:
The bank, alignment, address and type of sections can be specified both in the source code and in the linker script.
For a section to be able to be placed with the linker script, the bank, address and alignment must be left unassigned in the source code or be compatible with what is specified in the linker script.
For example,
.Ql ALIGN[8]
in the source code is compatible with
.Ql ORG $F00
in the linker script.
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
.Xr rgbfix 1 ,
.Xr rgbds 5 ,
.Xr rgbds 7
.Sh HISTORY
.Nm
was originally written by Carsten S\(/orensen as part of the ASMotor package,
and was later packaged in RGBDS by Justin Lloyd.
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .

275
src/rgbds.5
View File

@@ -1,275 +0,0 @@
.\"
.\" This file is part of RGBDS.
.\"
.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd March 28, 2021
.Dt RGBDS 5
.Os
.Sh NAME
.Nm rgbds
.Nd object file format documentation
.Sh DESCRIPTION
This is the description of the object files used by
.Xr rgbasm 1
and
.Xr rgblink 1 .
.Em Please note that the specifications may change .
This toolchain is in development and new features may require adding more information to the current format, or modifying some fields, which would break compatibility with older versions.
.Sh FILE STRUCTURE
The following types are used:
.Pp
.Ar LONG
is a 32-bit integer stored in little-endian format.
.Ar BYTE
is an 8-bit integer.
.Ar STRING
is a 0-terminated string of
.Ar BYTE .
.Bd -literal
; Header
BYTE ID[4] ; "RGB9"
LONG RevisionNumber ; The format's revision number this file uses.
LONG NumberOfSymbols ; The number of symbols used in this file.
LONG NumberOfSections ; The number of sections used in this file.
; File info
LONG NumberOfNodes ; The number of nodes contained in this file.
REPT NumberOfNodes ; IMPORTANT NOTE: the nodes are actually written in
; **reverse** order, meaning the node with ID 0 is
; the last one in the file!
LONG ParentID ; ID of the parent node, -1 means this is the root.
LONG ParentLineNo ; Line at which the parent context was exited.
; Meaningless on the root node.
BYTE Type ; 0 = REPT node
; 1 = File node
; 2 = Macro node
IF Type != 0 ; If the node is not a REPT...
STRING Name ; The node's name: either a file name, or macro name
; prefixed by its definition file name.
ELSE ; If the node is a REPT, it also contains the iter
; counts of all the parent REPTs.
LONG Depth ; Size of the array below.
LONG Iter[Depth] ; The number of REPT iterations by increasing depth.
ENDC
ENDR
; Symbols
REPT NumberOfSymbols ; Number of symbols defined in this object file.
STRING Name ; The name of this symbol. Local symbols are stored
; as "Scope.Symbol".
BYTE Type ; 0 = LOCAL symbol only used in this file.
; 1 = IMPORT this symbol from elsewhere
; 2 = EXPORT this symbol to other objects.
IF (Type & 0x7F) != 1 ; If symbol is defined in this object file.
LONG SourceFile ; File where the symbol is defined.
LONG LineNum ; Line number in the file where the symbol is defined.
LONG SectionID ; The section number (of this object file) in which
; this symbol is defined. If it doesn't belong to any
; specific section (like a constant), this field has
; the value -1.
LONG Value ; The symbols value. It's the offset into that
; symbol's section.
ENDC
ENDR
; Sections
REPT NumberOfSections
STRING Name ; Name of the section
LONG Size ; Size in bytes of this section
BYTE Type ; 0 = WRAM0
; 1 = VRAM
; 2 = ROMX
; 3 = ROM0
; 4 = HRAM
; 5 = WRAMX
; 6 = SRAM
; 7 = OAM
; Bits 7 and 6 are independent from the above value:
; Bit 7 encodes whether the section is unionized
; Bit 6 encodes whether the section is a fragment
; Bits 6 and 7 may not be both set at the same time!
LONG Org ; Address to fix this section at. -1 if the linker should
; decide (floating address).
LONG Bank ; Bank to load this section into. -1 if the linker should
; decide (floating bank). This field is only valid for ROMX,
; VRAM, WRAMX and SRAM sections.
BYTE Align ; Alignment of this section, as N bits. 0 when not specified.
LONG Ofs ; Offset relative to the alignment specified above.
; Must be below 1 << Align.
IF (Type == ROMX) || (Type == ROM0) ; Sections that can contain data.
BYTE Data[Size] ; Raw data of the section.
LONG NumberOfPatches ; Number of patches to apply.
REPT NumberOfPatches
LONG SourceFile ; ID of the source file node (for printing
; error messages).
LONG LineNo ; Line at which the patch was created.
LONG Offset ; Offset into the section where patch should
; be applied (in bytes).
LONG PCSectionID ; Index within the file of the section in which
; PC is located.
; This is usually the same section that the
; patch should be applied into, except e.g.
; with LOAD blocks.
LONG PCOffset ; PC's offset into the above section.
; Used because the section may be floating, so
; PC's value is not known to RGBASM.
BYTE Type ; 0 = BYTE patch.
; 1 = little endian WORD patch.
; 2 = little endian LONG patch.
; 3 = JR offset value BYTE patch.
LONG RPNSize ; Size of the buffer with the RPN.
; expression.
BYTE RPN[RPNSize] ; RPN expression. Definition below.
ENDR
ENDC
ENDR
; Assertions
LONG NumberOfAssertions
REPT NumberOfAssertions
LONG SourceFile ; ID of the source file node (for printing the failure).
LONG LineNo ; Line at which the assertion was created.
LONG Offset ; Offset into the section where the assertion is located.
LONG SectionID ; Index within the file of the section in which PC is
; located, or -1 if defined outside a section.
LONG PCOffset ; PC's offset into the above section.
; Used because the section may be floating, so PC's value
; is not known to RGBASM.
BYTE Type ; 0 = Prints the message but allows linking to continue
; 1 = Prints the message and evaluates other assertions,
; but linking fails afterwards
; 2 = Prints the message and immediately fails linking
LONG RPNSize ; Size of the RPN expression's buffer.
BYTE RPN[RPNSize] ; RPN expression, same as patches. Assert fails if == 0.
STRING Message ; A message displayed when the assert fails. If set to
; the empty string, a generic message is printed instead.
ENDR
.Ed
.Ss RPN DATA
Expressions in the object file are stored as RPN.
This is an expression of the form
.Dq 2 5 + .
This will first push the value
.Do 2 Dc to the stack, then
.Dq 5 .
The
.Do + Dc operator pops two arguments from the stack, adds them, and then pushes the result on the stack, effectively replacing the two top arguments with their sum.
In the RGB format, RPN expressions are stored as
.Ar BYTE Ns s
with some bytes being special prefixes for integers and symbols.
.Bl -column -offset indent "Sy String" "Sy String"
.It Sy Value Ta Sy Meaning
.It Li $00 Ta Li + operator
.It Li $01 Ta Li - operator
.It Li $02 Ta Li * operator
.It Li $03 Ta Li / operator
.It Li $04 Ta Li % operator
.It Li $05 Ta Li unary -
.It Li $06 Ta Li ** operator
.It Li $10 Ta Li \&| operator
.It Li $11 Ta Li & operator
.It Li $12 Ta Li ^ operator
.It Li $13 Ta Li unary ~
.It Li $21 Ta Li && comparison
.It Li $22 Ta Li || comparison
.It Li $23 Ta Li unary \&!
.It Li $30 Ta Li == comparison
.It Li $31 Ta Li != comparison
.It Li $32 Ta Li > comparison
.It Li $33 Ta Li < comparison
.It Li $34 Ta Li >= comparison
.It Li $35 Ta Li <= comparison
.It Li $40 Ta Li << operator
.It Li $41 Ta Li >> operator
.It Li $42 Ta Li >>> operator
.It Li $50 Ta Li BANK(symbol) ,
a
.Ar LONG
Symbol ID follows, where -1 means PC
.It Li $51 Ta Li BANK(section_name) ,
a null-terminated string follows.
.It Li $52 Ta Li Current BANK()
.It Li $53 Ta Li SIZEOF(section_name) ,
a null-terminated string follows.
.It Li $54 Ta Li STARTOF(section_name) ,
a null-terminated string follows.
.It Li $60 Ta Li HRAMCheck .
Checks if the value is in HRAM, ANDs it with 0xFF.
.It Li $61 Ta Li RSTCheck .
Checks if the value is a RST vector, ORs it with 0xC7.
.It Li $80 Ta Ar LONG
integer follows.
.It Li $81 Ta Ar LONG
symbol ID follows.
.El
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
.Xr rgbds 7 ,
.Xr gbz80 7
.Sh HISTORY
.Nm
was originally written by Carsten S\(/orensen as part of the ASMotor package,
and was later packaged in RGBDS by Justin Lloyd.
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .

57
src/rgbds.7
View File

@@ -1,57 +0,0 @@
.\"
.\" This file is part of RGBDS.
.\"
.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd March 28, 2021
.Dt RGBDS 7
.Os
.Sh NAME
.Nm rgbds
.Nd Rednex Game Boy Development System
.Sh EXAMPLES
To get a working ROM image from a single assembly source file:
.Bd -literal -offset indent
$ rgbasm \-o bar.o foo.asm
$ rgblink \-o baz.gb bar.o
$ rgbfix \-v \-p 0 baz.gb
.Ed
Or in a single command line:
.Bd -literal -offset indent
$ rgbasm \-o - foo.asm | rgblink \-o - - | rgbfix \-v \-p 0 - > baz.gb
.Ed
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgbfix 1 ,
.Xr rgblink 1 ,
.Xr rgbds 5 ,
.Xr gbz80 7
.Sh HISTORY
.Bl -item
.It
1997, Carsten S\(/orensen (AKA SurfSmurf) writes ASMotor as a general-purpose
assembler/linker system for DOS/Win32.
.It
1999, Justin Lloyd (AKA Otaku no Zoku) adapts ASMotor to read and produce GBZ80
assembly/machine code, and releases this version as RGBDS.
.It
2009, Vegard Nossum adapts the code to be more UNIX-like and releases this
version as rgbds-linux on GitHub.
.It
2010, Anthony J. Bentley forks that repository.
The fork becomes the reference implementation of rgbds.
.It
2017, Bentley's repository is moved to a neutral name.
It is now maintained by a number of contributors at
.Lk https://github.com/rednex/rgbds .
.It
2018, codebase relicensed under the MIT license.
.It
2020, repository is moved to the gbdev organisation, at
.Lk https://github.com/gbdev/rgbds .
The
.Lk https://rgbds.gbdev.io
website serving documentation and downloads is created.
.El