ROM2CART(1)

NAME
rom2cart - Convert a raw ROM image to an Atari800 CART image, or vice versa

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, in which case it will exit with an error message).

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).

-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.

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 v5.2.0 (types 1-103 and 160). 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) 32-bit integer format.

The next 4 bytes contain cartridge checksum in MSB format (ROM only; the header is not checksummed).

The next 4 bytes are currently unused (zero).

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 cart.txt or the output of rom2cart -l.

The latest version of cart.txt can be found at: https://raw.githubusercontent.com/atari800/atari800/master/DOC/cart.txt

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.

COPYRIGHT

WTFPL. See http://www.wtfpl.net/txt/copying/ for details.

AUTHOR

B.  Watson <urchlay@slackware.uk>; Urchlay on irc.libera.chat ##atari.

SEE ALSO

a8cat(1), a8eol(1), a8xd(1), atr2xfd(1), atrsize(1), axe(1), bas2aplus(1), blob2c(1), blob2xex(1), cart2xex(1), cxrefbas(1), dasm2atasm(1), diffbas(1), dumpbas(1), f2toxex(1), fenders(1), listbas(1), listamsb(1), protbas(1), renumbas(1), rom2cart(1), unmac65(1), unprotbas(1), vxrefbas(1), whichbas(1), xex1to2(1), xexamine(1), xexcat(1), xexsplit(1), xfd2atr(1), xex(5), atascii(7), fauxtari(7).

Any good Atari 8-bit book: De Re Atari, The Atari BASIC Reference Manual, the OS Users' Guide, Mapping the Atari, etc.