diff options
Diffstat (limited to 'cart2xex.rst')
| -rw-r--r-- | cart2xex.rst | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/cart2xex.rst b/cart2xex.rst new file mode 100644 index 0000000..aff6272 --- /dev/null +++ b/cart2xex.rst @@ -0,0 +1,203 @@ +.. 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 modifica‐ + tions. + +-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 |