initial commit

1 files changed, 244 insertions, 0 deletions

diff --git a/rom2cart.1 b/rom2cart.1
new file mode 100644
index 0000000..d339b02
--- /dev/null
+++ b/rom2cart.1
@@ -0,0 +1,244 @@
+.\" 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 "2022-08-29" "0.2.0" "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).
+.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).
+.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 v2.0.3 (types 1\-43). 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) format.
+.sp
+The next 4 bytes contain cartridge checksum in MSB format (ROM only).
+.sp
+The next 4 bytes are currently unused (zero).
+.sp
+The rest of the file contains the ROM data: 4, 8, 16, 32, 40, 64,  128,
+256, 512 or 1024 kilobytes.
+.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),
+\fBcart2xex\fP(1),
+\fBdasm2atasm\fP(1),
+\fBfenders\fP(1),
+\fBrom2cart\fP(1),
+\fBunmac65\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.
+.