initial commit

1 files changed, 247 insertions, 0 deletions

diff --git a/cart2xex.1 b/cart2xex.1
new file mode 100644
index 0000000..862982a
--- /dev/null
+++ b/cart2xex.1
@@ -0,0 +1,247 @@
+.\" 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 "2022-08-27" "0.2.0" "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),
+\fBcart2xex\fP(1),
+\fBdasm2atasm\fP(1),
+\fBfenders\fP(1),
+\fBrom2cart\fP(1),
+\fBunmac65\fP(1),
+\fBxexcat\fP(1),
+\fBxexsplit\fP(1),
+\fBxfd2atr\fP(1).
+.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.
+.