path: root/cart2xex.1

.\" 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-06-25" "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 modifications.
.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),
\fBcxrefbas\fP(1),
\fBdasm2atasm\fP(1),
\fBdumpbas\fP(1),
\fBf2toxex\fP(1),
\fBfenders\fP(1),
\fBlistbas\fP(1),
\fBprotbas\fP(1),
\fBrenumbas\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBunprotbas\fP(1),
\fBvxrefbas\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.
.