.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "CART2XEX" 1 "2024-05-03" "0.2.1" "Urchlay's Atari 8-bit Tools" .SH NAME cart2xex \- Convert an Atari 8-bit ROM cartridge image to a binary load file .\" RST source for cart2xex(1) man page. Convert with: . .\" rst2man.py cart2xex.rst > cart2xex.1 . .\" rst2man.py comes from the SBo development/docutils package. . .SH SYNOPSIS .sp \fBcart2xex\fP [\fI\-cdhn\fP] [\fB\-i\fP \fIaddr\fP] [\fB\-r\fP \fIaddr\fP] [\fB\-p\fP \fIpages\fP] [\fB\-t\fP \fItitle\fP] \fIinfile.rom\fP [\fIoutfile.xex\fP] .SH DESCRIPTION .sp \fBcart2xex\fP 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 \fBLOADING\fP and the filename while the rest of the file loads. .sp Input ROM files may be either raw dumps or Atari800 \fB\&.CAR\fP format. .SH OPTIONS .INDENT 0.0 .TP .B \-c Check ROM and print info only; do not create an executable. .TP .B \-d Don\(aqt include code to make the Atari reboot when RESET is pressed. Generally, there\(aqs no advantage to using this option, as the Atari either locks up or reboots anyway when reset. .TP .B \-h Print help (usage) message and exit. .TP .BI \-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\(aqt contain an init address at all. Executables created with this option probably won\(aqt run without further modifica‐ tions. .TP .BI \-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 \fBwill not run\fP without further modifications. .TP .BI \-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\(aqt contain a run address at all. Executables created with this option probably won\(aqt run without further modifications. .TP .B \-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 \fB\-l "$8000"\fP\&. Very few right cartridges were ever made. \fB\&.CAR\fP images with type 21 (8K right cartridge) will automatically set this option. .TP .B \-n Do not prepend the code for the \fBLOADING\fP title screen. Without the title screen, the Atari\(aqs display will become corrupted during the loading process, although this doesn\(aqt always cause any real problems. .TP .BI \-p \ pages Reserve extra memory below RAMTOP, in 256\-byte pages. Maximum value for \fIpages\fP is 16 for a 16K ROM, or 48 for an 8K ROM. .TP .BI \-t \ title Set the title to be displayed during the \fILOADING\fP 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. .UNINDENT .SH NOTES .sp \fBcart2xex\fP can\(aqt 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 \fB\&.CAR\fP 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). .sp \fIinfile\fP may be \fB\-\fP to read from standard input. \fIoutfile\fP may be \fB\-\fP to write to standard output. \fBcart2xex\fP will refuse to write binary data to a terminal. .sp If \fIoutfile\fP is omitted, but \fIinfile\fP is provided, the output filename will be constructed from \fIinfile\fP by replacing the filename extension with \fI\&.xex\fP, or by appending \fI\&.xex\fP if there is no extension. .sp The \fBLOADING\fP screen consists of around 200 bytes of 6502 object code, loaded at $6000. The title (\fB\-t\fP 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\(aqt exist in the ATASCII character set, and a green ] would be the Atari clear\-screen code (CHR$(125)). .sp With the \fB\-n\fP option (suppress \fBLOADING\fP screen), the Atari\(aqs 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, \fBcart2xex\fP emits code that sets RAMTOP to point below the cartridge area, so the screen corruption shouldn\(aqt 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\(aqt necessarily re\-open the E: device. In fact, the first thing BASIC does is print a READY prompt, which (with \fB\-n\fP) causes it to overwrite part of its own code, and lock up (since the screen address points to a location within BASIC). .sp 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\(aqs 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\(aqre looking for an example of a self\-destructing ROM, try the Parker Brothers version of Frogger, or Atari Pac\-Man or Millipede. .sp Sometimes, the executable won\(aqt work properly when loaded from a regular DOS, but will work fine with a game DOS such as Fenders 3\-sector loader or HiassofT\(aqs 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\(aqs 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\(aqs Atlantis. .sp 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\(aqt 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). .sp Normally, the load/run/init addresses are best left alone. The \fB\-l\fP, \fB\-i\fP and \fB\-r\fP options are included for expert users, who may find them useful for bypassing "self\-destruct" copy protection code. \fBcart2xex\fP 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\(aqs doing). These might also be useful if you want to disassemble the ROM\(aqs code with a cartridge\-based disassembler (in which case, you probably need \fB\-i0 \-r0\fP as well, to create a file that doesn\(aqt execute when loaded). .sp Addresses for \fB\-l\fP / \fB\-i\fP / \fB\-r\fP and the number of pages for \fB\-p\fP may be given in decimal, hex prefixed with \fB$\fP (don\(aqt forget to quote it for the shell!), or hex prefixed with \fB0x\fP\&. Hex digits may be given in upper or lowercase. .sp Without the \fB\-p\fP 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\(aqt a problem for real ROM cartridges (since ROM can\(aqt be overwritten), but when running from RAM, this will clear the first 64 bytes of "cartridge" code! .sp 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\(aqt hurt anything, but if running from RAM, the code will be scrambled and the Atari will lock up. Reserving 4 pages (\fB\-p 4\fP) will avoid this, though of course it will reduce the amount of free memory available to the cartridge. .sp Without the \fB\-d\fP option, the output executable will contain a one\-byte segment that loads a value of 1 into location $0244 (equivalent to the BASIC \fBPOKE 580,1\fP command). It\(aqs possible that the cartridge\(aqs code may reset this location when it runs, so reboot\-on\-RESET may not be 100% reliable. The \fB\-d\fP option is probably only useful for languages like BASIC or ASM/ED. .SH EXIT STATUS .sp Exit status is zero for success, non\-zero for failure. .SH COPYRIGHT .sp WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details. .SH AUTHOR .INDENT 0.0 .IP B. 3 Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&. .UNINDENT .SH SEE ALSO .sp \fBa8eol\fP(1), \fBa8utf8\fP(1), \fBatr2xfd\fP(1), \fBatrsize\fP(1), \fBaxe\fP(1), \fBblob2c\fP(1), \fBblob2xex\fP(1), \fBcart2xex\fP(1), \fBdasm2atasm\fP(1), \fBf2toxex\fP(1), \fBfenders\fP(1), \fBrom2cart\fP(1), \fBunmac65\fP(1), \fBxexamine\fP(1), \fBxexcat\fP(1), \fBxexsplit\fP(1), \fBxfd2atr\fP(1), \fBxex\fP(5), \fBatascii\fP(7). .sp Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC Reference Manual\fP, the \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc. .\" Generated by docutils manpage writer. .