mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-22 11:12:07 +00:00
Move all man pages to a separate directory
Simplifies processing all around, and makes more sense
This commit is contained in:
ISSOtm
243
src/fix/rgbfix.1
243
src/fix/rgbfix.1
@@ -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 .
|
||||
Reference in New Issue
Block a user