diff options
Diffstat (limited to 'rom2cart.rst')
| -rw-r--r-- | rom2cart.rst | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/rom2cart.rst b/rom2cart.rst new file mode 100644 index 0000000..0edc57d --- /dev/null +++ b/rom2cart.rst @@ -0,0 +1,202 @@ +.. RST source for rom2cart(1) man page. Convert with: +.. rst2man.py rom2cart.rst > rom2cart.1 +.. rst2man.py comes from the SBo development/docutils package. + +======== +rom2cart +======== + +---------------------------------------------------------------- +Convert a raw ROM image to an Atari800 CART image, or vice versa +---------------------------------------------------------------- + +.. include:: manhdr.rst + +SYNOPSIS +======== + +**rom2cart** [*-chlnrv*] [-m *machine*] [-t *type*] [-T *forced-type*] [-C *forced-checksum*] [-U *unused-data*] [*infile*] [*outfile*] + +**cart2rom** [*infile*] [*outfile*] + +DESCRIPTION +=========== + +**rom2cart** converts between raw ROM dumps and Atari800 **.CAR** +images. Despite the name, conversion can be done in either direction. +**cart2rom** is equivalent to **rom2cart -r**. + +Input ROM files may be either raw dumps or Atari800 .CAR format. +Output will be a **.CAR** file, or (with **-r**) a raw dump. + +When reading a raw dump, **rom2cart** attempts to determine +the correct image type based on the file size, machine type +(specified via **-m**, or guessed by looking at the ROM +content), and (optional) user-supplied type number or name (**-t**). +If **rom2cart** 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 **-n** is given to prevent +this behavior). + +When writing a **.CAR** file, **rom2cart** will calculate the checksum +automatically and store it in the **CART** header (unless **-C** is +used to force the checksum). + +OPTIONS +======= + +Standard options: + +-c + Check ROM and print info only; do not create any output. + +-h + Print help (usage) message and exit. + +-l + Print a complete list of known image types and exit. + +-m machine + Sets the machine type for the image. Valid machine values are + **5200** and **8bit** (may be abbreviated as **5** and **8**). This is used as + a hint by the type-guessing algorithm to narrow down the search. + May be used in combination with **-t**. Without **-t**, only the machine + type and file size are used to guess the image type. This option + has no effect with **-T**. + +-n + Do not guess image type, if unable to determine it exactly from the + file size and any supplied **-t**/**-T**/**-m** 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 **-T**. + +-r + Output a raw image dump, rather than a **.CAR** image. Most useful + when input is a **.CAR** 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 **rom2cart** 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 *.rom*. + +-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 (**-m** 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. + +-v + Verbose operation. May be given twice, for extra verbosity. + +Advanced options: + +The "advanced" options are considered advanced because they're capable +of creating a bogus **.CAR** file that Atari800 won't accept. They're also +useful for debugging **rom2cart** or Atari800 itself. + +-T type + Force the image type. Unlike **-t**, the *type* given must be numeric, + and is not required to be a known type. When using this option, + the file size is not checked. **-T** is intended to be used for image + types that were not yet in existence when this version of **rom2cart** + was written. + +-C sum + Force the checksum field in the output **.CAR** image to *sum*. + Intended for debugging purposes. Atari800 will refuse to load + **.CAR** images with invalid checksums. *sum* 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 + (**-r** option). + +-U data + Set the unused bytes (offsets 12-15) in the **CART** header to *data*. + Currently, these bytes are unused by Atari800, but future versions + may define a use for them. Normally, **rom2cart** sets them to all + zeroes. *data* 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 (**-r** option). + +NOTES +===== + +*infile* may be '-' to read from standard input. *outfile* may be '-' to +write to standard output. **rom2cart** will refuse to write binary data to +a terminal. + +If *outfile* is omitted, but *infile* is provided, the output filename will +be constructed from *infile* by replacing the filename extension with +*.car* (or *.rom* if **-r** is given), or by appending *.car* (or *.rom*) if there +is no extension. + +**rom2cart** 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 **.CAR** image of a type not supported in this +version of **rom2cart**, you can use the **-T** option. Alternatively, look +for a newer version of **rom2cart**. If no new version exists, bug the +author until he releases one! + +The **-T** option should be used with caution. It disables all the +checks that are normally done, and can be used to create **.CAR** 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't recognized +by Atari800 at all). With **-T**, it's up to you to ensure that the image +type and size is correct. + +CART FORMAT +=========== + +The **.CAR** format is fully documented in *cart.txt*, supplied +with the Atari800 source distribution. The following is an abbreviated +description. + +A **.CAR** image consists of a 16-byte header followed by the ROM data. + +The first 4 bytes contain 'C' 'A' 'R' 'T' in ASCII. + +The next 4 bytes contain the cartridge type in MSB (aka +*big-endian*) format. + +The next 4 bytes contain cartridge checksum in MSB format (ROM only). + +The next 4 bytes are currently unused (zero). + +The rest of the file contains the ROM data: 4, 8, 16, 32, 40, 64, 128, +256, 512 or 1024 kilobytes. + +HEURISTICS +========== + +If none of the **-m**, **-n**, **-T** options are given, the machine type is +guessed according to these rules: + +First, examine the option byte (3rd-to-last in the ROM image). If +it's *$FF* or in the range *$50-$59*, assume 5200. If it's *$04*, *$05*, or +*$80*, assume 8-bit computer. + +If the option byte doesn't 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 *$4000-$7FFF*, it must be a 5200 ROM +(because cartridge ROM starts at *$8000* on the 8-bit). + +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 *$E8xx* (5200 POKEY) or *$D2xx* +(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. + +If the machine type is still unknown, **rom2cart** will choose +the lowest-numbered cartridge type that matches the ROM size, +regardless of machine type. + +EXIT STATUS +=========== + +Exit status is zero for success, non-zero for failure. + +.. include:: manftr.rst |