1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
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
|
