diff options
Diffstat (limited to 'rom2cart.1')
-rw-r--r-- | rom2cart.1 | 244 |
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. +. |