From e2ba8458a5cfdfacfaf103e7ba97d610afa6c970 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Mon, 29 Aug 2022 16:11:13 -0400 Subject: initial commit --- cart2xex.1 | 247 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 cart2xex.1 (limited to 'cart2xex.1') 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. +. -- cgit v1.2.3