path: root/rom2cart.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "ROM2CART" 1 "2024-04-26" "0.2.1" "Urchlay's Atari 8-bit Tools"
.SH NAME
rom2cart \- Convert a raw ROM image to an Atari800 CART image, or vice versa
.\" RST source for rom2cart(1) man page. Convert with:
.
.\" rst2man.py rom2cart.rst > rom2cart.1
.
.\" rst2man.py comes from the SBo development/docutils package.
.
.SH SYNOPSIS
.sp
\fBrom2cart\fP [\fI\-chlnrv\fP] [\-m \fImachine\fP] [\-t \fItype\fP] [\-T \fIforced\-type\fP] [\-C \fIforced\-checksum\fP] [\-U \fIunused\-data\fP] [\fIinfile\fP] [\fIoutfile\fP]
.sp
\fBcart2rom\fP [\fIinfile\fP] [\fIoutfile\fP]
.SH DESCRIPTION
.sp
\fBrom2cart\fP converts between raw ROM dumps and Atari800 \fB\&.CAR\fP
images. Despite the name, conversion can be done in either direction.
\fBcart2rom\fP is equivalent to \fBrom2cart \-r\fP\&.
.sp
Input ROM files may be either raw dumps or Atari800 .CAR format.
Output will be a \fB\&.CAR\fP file, or (with \fB\-r\fP) a raw dump.
.sp
When reading a raw dump, \fBrom2cart\fP attempts to determine
the correct image type based on the file size, machine type
(specified  via  \fB\-m\fP,  or guessed  by  looking  at the ROM
content), and (optional) user\-supplied type number or name (\fB\-t\fP).
If \fBrom2cart\fP is unable to narrow  the  selection  down  to  one
image  type,  it will "guess" by choosing the lowest\-numbered type
that matches the given parameters (unless \fB\-n\fP is given to prevent
this behavior, in which case it will exit with an error message).
.sp
When writing a \fB\&.CAR\fP file, \fBrom2cart\fP will calculate the checksum
automatically and store it in the \fBCART\fP header (unless \fB\-C\fP is
used to force  the checksum).
.SH OPTIONS
.sp
Standard options:
.INDENT 0.0
.TP
.B  \-c
Check ROM and print info only; do not create any output.
.TP
.B  \-h
Print help (usage) message and exit.
.TP
.B  \-l
Print a complete list of known image types and exit.
.TP
.BI \-m \ machine
Sets  the  machine  type for the image. Valid machine values are
\fB5200\fP and \fB8bit\fP (may be abbreviated as \fB5\fP and \fB8\fP).  This is used  as
a hint by the type\-guessing algorithm to narrow down the search.
May be used in combination with \fB\-t\fP\&. Without \fB\-t\fP, only the machine
type  and  file size are used to guess the image type.  This option
has no effect with \fB\-T\fP\&.
.TP
.B  \-n
Do not guess image type, if unable to determine it exactly  from the
file   size  and  any  supplied  \fB\-t\fP/\fB\-T\fP/\fB\-m\fP  arguments.
The type\-matching is still done, and if only one  type  matches,
it will  be  used.  This option only has an effect if type\-matching
results in two or more possible matches.  This option has no effect
with \fB\-T\fP\&.
.TP
.B  \-r
Output  a  raw image dump, rather than a \fB\&.CAR\fP image. Most useful
when input is a \fB\&.CAR\fP image, but may be used with raw  input  (in
which  case, the output file will be a copy of the input, but it
will only be created if \fBrom2cart\fP thinks the input is a valid raw
dump). If output filename not specified, it will be derived from
the input filename, and will end in \fI\&.rom\fP\&.
.TP
.BI \-t \ type
Set the image type. type may be either a valid numeric type or
a name.   If a numeric type is given, it must be a valid type, the
file size must be correct for the type, and if  given,  the  machine
type (\fB\-m\fP option) must match the type. If a name is given, it is used
to search the list of known types;  only  names  that match will be
considered as possible types.  This is a case\-insensitive substring
match.
.TP
.B  \-v
Verbose operation. May be given twice, for extra verbosity.
.UNINDENT
.sp
Advanced options:
.sp
The "advanced" options are considered advanced because they\(aqre  capable
of  creating a bogus \fB\&.CAR\fP file that Atari800 won\(aqt accept. They\(aqre also
useful for debugging \fBrom2cart\fP or Atari800 itself.
.INDENT 0.0
.TP
.BI \-T \ type
Force the image type. Unlike \fB\-t\fP, the \fItype\fP given must be numeric,
and  is not required to be a known type. When using this option,
the file size is not checked. \fB\-T\fP is intended to be used for  image
types  that  were not yet in existence when this version of \fBrom2cart\fP
was written.
.TP
.BI \-C \ sum
Force the checksum field in the output \fB\&.CAR\fP image to  \fIsum\fP\&.
Intended for debugging purposes. Atari800 will refuse to load
\fB\&.CAR\fP images with invalid checksums.  \fIsum\fP is a 32\-bit unsigned
value, and  may  be given in hex (prefixed with $ or 0x) or decimal
(no prefix).  This option has no effect if the output is a raw  dump
(\fB\-r\fP option).
.TP
.BI \-U \ data
Set the unused bytes (offsets 12\-15) in the \fBCART\fP header to \fIdata\fP\&.
Currently, these bytes are unused by Atari800, but  future  versions
may define a use for them. Normally, \fBrom2cart\fP sets them to all
zeroes.  \fIdata\fP is a 32\-bit unsigned value, and may  be  given in hex
(prefixed with $ or 0x) or decimal (no prefix).  This option has no
effect if the output is a raw dump (\fB\-r\fP option).
.TP
.B  \-H
Test the code\-detection heuristics: examine the first 8K of the ROM and
look for writes to $D2xx (8\-bit computer) or $E8xx (5200) to guess the
machine type for the ROM. This option exists only for testing: normally,
the machine type gets guessed by the cartridge option bytes, and the
code\-detection is only done if the option byte tests are inconclusive.
.UNINDENT
.SH NOTES
.sp
\fIinfile\fP may be \(aq\-\(aq to read from standard input. \fIoutfile\fP may  be  \(aq\-\(aq  to
write  to standard output. \fBrom2cart\fP will refuse to write binary data to
a terminal.
.sp
If \fIoutfile\fP is omitted, but \fIinfile\fP is provided, the output filename will
be  constructed  from  \fIinfile\fP  by replacing the filename extension with
\fI\&.car\fP (or \fI\&.rom\fP if \fB\-r\fP is given), or by appending \fI\&.car\fP (or \fI\&.rom\fP) if  there
is no extension.
.sp
\fBrom2cart\fP contains an internal database of image types. The current
version uses the list from Atari800 v5.2.0 (types 1\-103 and 160). If  you
need  to create  a  \fB\&.CAR\fP  image  of  a  type  not  supported  in this
version of \fBrom2cart\fP, you can use the \fB\-T\fP option.  Alternatively, look
for  a  newer version  of \fBrom2cart\fP\&. If no new version exists, bug the
author until he releases one!
.sp
The \fB\-T\fP option should be used with caution. It disables all  the
checks that are normally done, and can be used to create \fB\&.CAR\fP files
with arbitrary types and data sizes (e.g. a 16K  image  with  its
type  set  to "Standard  8K",  or an image whose type isn\(aqt recognized
by Atari800 at all).  With \fB\-T\fP, it\(aqs up to you to ensure that the image
type  and  size is correct.
.SH CART FORMAT
.sp
The  \fB\&.CAR\fP  format  is  fully  documented in \fIcart.txt\fP, supplied
with the Atari800 source distribution. The following is an abbreviated
description.
.sp
A \fB\&.CAR\fP image consists of a 16\-byte header followed by the ROM data.
.sp
The first 4 bytes contain \(aqC\(aq \(aqA\(aq \(aqR\(aq \(aqT\(aq in ASCII.
.sp
The next 4 bytes contain the cartridge type in MSB (aka \fIbig\-endian\fP)
32\-bit integer format.
.sp
The next 4 bytes contain cartridge checksum in MSB format (ROM only;
the header is not checksummed).
.sp
The next 4 bytes are currently unused (zero).
.sp
The rest of the file contains the ROM data, up to 32Mbytes as of
Atari800 5.2.0. The cartridge type determines the amount of data; see
\fIcart.txt\fP or the output of \fBrom2cart \-l\fP\&.
.sp
The latest version of \fIcart.txt\fP can be found at:
.INDENT 0.0
.INDENT 3.5
\fI\%https://raw.githubusercontent.com/atari800/atari800/master/DOC/cart.txt\fP
.UNINDENT
.UNINDENT
.SH HEURISTICS
.sp
If  none  of  the  \fB\-m\fP,  \fB\-n\fP,  \fB\-T\fP  options are given, the machine type is
guessed according to these rules:
.sp
First, examine the option byte (3rd\-to\-last in the ROM image). If
it\(aqs \fI$FF\fP or in the range \fI$50\-$59\fP, assume 5200. If it\(aqs \fI$04\fP, \fI$05\fP, or
\fI$80\fP, assume 8\-bit computer.
.sp
If the option byte doesn\(aqt help, and if the ROM is  32K  or  larger
in size, the cartridge init address (last two bytes of ROM) is
checked. If it falls in the range \fI$4000\-$7FFF\fP, it must be a 5200 ROM
(because  cartridge ROM starts at \fI$8000\fP on the 8\-bit).
.sp
If  the  ROM  is  less  than  32K,  and/or its init address is
>=$8000, rom2cart searches the first 8K of ROM data, looking  for
6502  machine code  that  writes  to  \fI$E8xx\fP  (5200 POKEY) or \fI$D2xx\fP
(8\-bit POKEY).  If there are 3 or more "5200 POKEY" writes and zero or
one  "8\-bit  POKEY) writes,  assume 5200. If 3 or more "8\-bit POKEY"
writes and zero or one "5200 POKEY" writes, assume 8\-bit.
.sp
If the machine type is still unknown, \fBrom2cart\fP  will  choose
the  lowest\-numbered  cartridge  type  that matches the ROM size,
regardless of machine type.
.SH EXIT STATUS
.sp
Exit status is zero for success, non\-zero for failure.
.SH COPYRIGHT
.sp
WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
.SH AUTHOR
.INDENT 0.0
.IP B. 3
Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&.
.UNINDENT
.SH SEE ALSO
.sp
\fBa8eol\fP(1),
\fBa8utf8\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBdasm2atasm\fP(1),
\fBf2toxex\fP(1),
\fBfenders\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBxexamine\fP(1),
\fBxexcat\fP(1),
\fBxexsplit\fP(1),
\fBxfd2atr\fP(1).
.sp
Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC  Reference
Manual\fP,  the  \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc.
.\" Generated by docutils manpage writer.
.