CART2XEX(1)

NAME
cart2xex - Convert an Atari 8-bit ROM cartridge image to a binary load file

SYNOPSIS

cart2xex [-cdhn] [-i addr] [-r addr] [-p pages] [-t title] infile.rom [outfile.xex]

DESCRIPTION

cart2xex creates an Atari executable (XEX/COM/BIN/etc) file from an 8K or 16K non-bankswitched cartridge ROM dump. The resulting executable will (by default) have a title screen that displays LOADING and the filename while the rest of the file loads.

Input ROM files may be either raw dumps or Atari800 .CAR format.

OPTIONS

-c  Check ROM and print info only; do not create an executable.

-d  Don't include code to make the Atari reboot when RESET is pressed. Generally, there's no advantage to using this option, as the Atari either locks up or reboots anyway when reset.

-h  Print help (usage) message and exit.

-i address
    Sets the init address of the executable. Default is to use the init address in the ROM image, at addresses $BFFE/BFFF. An init address of zero means "no init address"; in this case, the output won't contain an init address at all. Executables created with this option probably won't run without further modifications.

-l address
    Sets the load address of the executable. Default is to use the standard Atari cartridge address ($8000 for a 16K cart, $A000 for 8K). Executables created with this option will not run without further modifications.

-r address
    Sets the run address of the executable. Default is to use the run address in the ROM image, at addresses $BFFA/BFFB. A run address of zero means "no run address"; in this case, the output won't contain a run address at all. Executables created with this option probably won't run without further modifications.

-R  ROM image is a "right cartridge", meant to be used in the right slot on an 800. Sets the load address to $8000, equivalent to -l "$8000". Very few right cartridges were ever made. .CAR images with type 21 (8K right cartridge) will automatically set this option.

-n  Do not prepend the code for the LOADING title screen. Without the title screen, the Atari's display will become corrupted during the loading process, although this doesn't always cause any real problems.

-p pages
    Reserve extra memory below RAMTOP, in 256-byte pages. Maximum value for pages is 16 for a 16K ROM, or 48 for an 8K ROM.

-t title
    Set the title to be displayed during the LOADING screen, up to 20 characters. Default: use the output filename as the title (minus any extension), or leave the title blank if writing to standard output.

NOTES

cart2xex can't handle cartridges that use bankswitching (such as most Atari XEGS-era releases, or OSS super carts such as Basic XL or Action!). Only standard 8K and 16K cartridge images are usable. For raw dumps, this means the input must be exactly 8192 or 16384 bytes. For .CAR images, the image type is read from the CART header; it must be type 1, 2, or 21 (Standard 8K, 16K, or 8K right-slot image, respectively).

infile may be - to read from standard input. outfile may be - to write to standard output. cart2xex 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 .xex, or by appending .xex if there is no extension.

The LOADING screen consists of around 200 bytes of 6502 object code, loaded at $6000. The title (-t argument, or output filename) will be transformed so that it will be displayed in green on a GRAPHICS 2 screen. Any ~ (tilde) or ] (right square bracket) characters will be replaced with spaces, since the tilde doesn't exist in the ATASCII character set, and a green ] would be the Atari clear-screen code (CHR$(125)).

With the -n option (suppress LOADING screen), the Atari's display will get corrupted during the load. This is because the display list and screen RAM in use during the load is located in the RAM where the executable will be loaded, which gets overwritten with code/data. Even without the title screen, cart2xex emits code that sets RAMTOP to point below the cartridge area, so the screen corruption shouldn't cause any problems for most games (since the first thing they do is set up their own graphics display). However, languages such as BASIC don't necessarily re-open the E: device. In fact, the first thing BASIC does is print a READY prompt, which (with -n) causes it to overwrite part of its own code, and lock up (since the screen address points to a location within BASIC).

Not all cartridges will run correctly if loaded into RAM. In particular, many commercial games contain "self-destruct" code which attempts to write to the cartridge's own ROM (either by accident or as a copy-protection measure). This of course fails when running from ROM, but will succeed if running from RAM. Converting such an image into a binload file requires disassembling the code, finding the self-destruct sequence, and removing it (the Atari800 built-in debugger is very handy for this). If you're looking for an example of a self-destructing ROM, try the Parker Brothers version of Frogger, or Atari Pac-Man or Millipede.

Sometimes, the executable won't work properly when loaded from a regular DOS, but will work fine with a game DOS such as Fenders 3-sector loader or HiassofT's MyPicoDOS. This seems to happen because the cart code assumes that portions of memory will be initialized to zero, but with DOS loaded, they actually contain DOS's code and data. The reason they work with bootloaders is that a bootloader is specifically designed to use as little memory as possible. An example of this type of ROM image is Imagic's Atlantis.

The opposite is also possible: sometimes the executable will work fine when loaded from DOS, but will not work when loaded via a bootloader (or the "Load XEX" option in an emulator). This seems to happen for carts that want to boot DOS (example: Atari Artist). This isn't a very serious problem though: normally if a cartridge allows DOS boot, you will want to be using DOS with it (e.g. so you can save and load your drawings in Atari Artist).

Normally, the load/run/init addresses are best left alone. The -l, -i and -r options are included for expert users, who may find them useful for bypassing "self-destruct" copy protection code. cart2xex will print warnings if the user sets the addresses outside the address range of the cartridge ($8000-$CFFF for 16K carts, or $A000-$CFFF for 8K), but will create the executable anyway (always assume the user knows what he's doing). These might also be useful if you want to disassemble the ROM's code with a cartridge-based disassembler (in which case, you probably need -i0 -r0 as well, to create a file that doesn't execute when loaded).

Addresses for -l / -i / -r and the number of pages for -p may be given in decimal, hex prefixed with $ (don't forget to quote it for the shell!), or hex prefixed with 0x. Hex digits may be given in upper or lowercase.

Without the -p option, the title screen routine will still lower RAMTOP (location 106) to make room for the image. Text-mode cartridges such as BASIC or ASM/ED may need some "breathing room" between RAMTOP and the start of the cartridge code, because some versions of the Atari OS contain a bug that causes "clear screen" to clear an extra 64 bytes past RAMTOP. This isn't a problem for real ROM cartridges (since ROM can't be overwritten), but when running from RAM, this will clear the first 64 bytes of "cartridge" code!

Some versions of the Atari OS ROM also contain a bug that causes 800 bytes of memory above RAMTOP to be scrolled, when scrolling the text window in graphics modes. When using a real cartridge, this doesn't hurt anything, but if running from RAM, the code will be scrambled and the Atari will lock up. Reserving 4 pages (-p 4) will avoid this, though of course it will reduce the amount of free memory available to the cartridge.

Without the -d option, the output executable will contain a one-byte segment that loads a value of 1 into location $0244 (equivalent to the BASIC POKE 580,1 command). It's possible that the cartridge's code may reset this location when it runs, so reboot-on-RESET may not be 100% reliable. The -d option is probably only useful for languages like BASIC or ASM/ED.

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.