.. RST source for cart2xex(1) man page. Convert with:
..   rst2man.py cart2xex.rst > cart2xex.1
.. rst2man.py comes from the SBo development/docutils package.

========
cart2xex
========

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

.. include:: manhdr.rst

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.

.. include:: manftr.rst
