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

Overhaul RGBDS man pages and help messages

Browse Source
This commit is contained in:
ISSOtm
2019-12-07 02:54:18 +01:00
parent 373762dedc
commit 34618e0294
13 changed files with 903 additions and 739 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
src/fix/main.c
View File

@@ -17,8 +17,8 @@
#include "version.h"
/* Shoft options */
static char const *optstring = "Ccf:i:jk:l:m:n:p:sr:t:Vv";
/* Short options */
static char const *optstring = "Ccf:i:jk:l:m:n:p:r:st:Vv";
/*
* Equivalent long options
@@ -51,10 +51,24 @@ static struct option const longopts[] = {
static void print_usage(void)
{
printf(
"usage: rgbfix [-CcjsVv] [-f fix_spec] [-i game_id] [-k licensee_str]\n"
" [-l licensee_id] [-m mbc_type] [-n rom_version] [-p pad_value]\n"
" [-r ram_size] [-t title_str] file\n");
fputs(
"usage: rgbfix [<options>] <file>\n"
" -C, --color-only flag the ROM as Color-only\n"
" -c, --color-compatible flag the ROM as color-compatible\n"
" -f, --fix-spec <flags> specify how to fix or trash the header\n"
" -i, --game-id <ID> set the 4 characters at 0x13F-0x142\n"
" -j, --non-japanese flag the ROM as exclusively overseas\n"
" -k, --new-licensee <code> set the new licensee str to at most two chars\n"
" -l, --old-licensee <value> set the old licensee code to this byte\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"
" -n, --rom-version <version> set the ROM's revision byte\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"
" -s, --sgb-compatible set the SGB compatibility flag\n"
" -t, --title <string> set the ROM's title (16 chars max, 15 is best)\n"
" -V, --version print RGBFIX version and exit\n"
" -v, --verbose report more information\n", stderr);
exit(1);
}
@@ -227,8 +241,10 @@ int main(int argc, char *argv[])
argc -= optind;
argv += optind;
if (argc == 0)
if (argc == 0) {
fputs("FATAL: no input files\n", stderr);
print_usage();
}
/*
* Open the ROM file

95
src/fix/rgbfix.1
View File

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