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
204
205
206
207
208
209
210
211
212
213
214
215
|
.. RST source for rom2cart(1) man page. Convert with:
.. rst2man.py rom2cart.rst > rom2cart.1
.. rst2man.py comes from the SBo development/docutils package.
========
rom2cart
========
----------------------------------------------------------------
Convert a raw ROM image to an Atari800 CART image, or vice versa
----------------------------------------------------------------
.. include:: manhdr.rst
SYNOPSIS
========
**rom2cart** [*-chlnrv*] [-m *machine*] [-t *type*] [-T *forced-type*] [-C *forced-checksum*] [-U *unused-data*] [*infile*] [*outfile*]
**cart2rom** [*infile*] [*outfile*]
DESCRIPTION
===========
**rom2cart** converts between raw ROM dumps and Atari800 **.CAR**
images. Despite the name, conversion can be done in either direction.
**cart2rom** is equivalent to **rom2cart -r**.
Input ROM files may be either raw dumps or Atari800 .CAR format.
Output will be a **.CAR** file, or (with **-r**) a raw dump.
When reading a raw dump, **rom2cart** attempts to determine
the correct image type based on the file size, machine type
(specified via **-m**, or guessed by looking at the ROM
content), and (optional) user-supplied type number or name (**-t**).
If **rom2cart** is unable to narrow the selection down to one
image type, it will "guess" by choosing the lowest-numbered type
that matches the given parameters (unless **-n** is given to prevent
this behavior, in which case it will exit with an error message).
When writing a **.CAR** file, **rom2cart** will calculate the checksum
automatically and store it in the **CART** header (unless **-C** is
used to force the checksum).
OPTIONS
=======
Standard options:
-c
Check ROM and print info only; do not create any output.
-h
Print help (usage) message and exit.
-l
Print a complete list of known image types and exit.
-m machine
Sets the machine type for the image. Valid machine values are
**5200** and **8bit** (may be abbreviated as **5** and **8**). This is used as
a hint by the type-guessing algorithm to narrow down the search.
May be used in combination with **-t**. Without **-t**, only the machine
type and file size are used to guess the image type. This option
has no effect with **-T**.
-n
Do not guess image type, if unable to determine it exactly from the
file size and any supplied **-t**/**-T**/**-m** arguments.
The type-matching is still done, and if only one type matches,
it will be used. This option only has an effect if type-matching
results in two or more possible matches. This option has no effect
with **-T**.
-r
Output a raw image dump, rather than a **.CAR** image. Most useful
when input is a **.CAR** image, but may be used with raw input (in
which case, the output file will be a copy of the input, but it
will only be created if **rom2cart** thinks the input is a valid raw
dump). If output filename not specified, it will be derived from
the input filename, and will end in *.rom*.
-t type
Set the image type. type may be either a valid numeric type or
a name. If a numeric type is given, it must be a valid type, the
file size must be correct for the type, and if given, the machine
type (**-m** option) must match the type. If a name is given, it is used
to search the list of known types; only names that match will be
considered as possible types. This is a case-insensitive substring
match.
-v
Verbose operation. May be given twice, for extra verbosity.
Advanced options:
The "advanced" options are considered advanced because they're capable
of creating a bogus **.CAR** file that Atari800 won't accept. They're also
useful for debugging **rom2cart** or Atari800 itself.
-T type
Force the image type. Unlike **-t**, the *type* given must be numeric,
and is not required to be a known type. When using this option,
the file size is not checked. **-T** is intended to be used for image
types that were not yet in existence when this version of **rom2cart**
was written.
-C sum
Force the checksum field in the output **.CAR** image to *sum*.
Intended for debugging purposes. Atari800 will refuse to load
**.CAR** images with invalid checksums. *sum* is a 32-bit unsigned
value, and may be given in hex (prefixed with $ or 0x) or decimal
(no prefix). This option has no effect if the output is a raw dump
(**-r** option).
-U data
Set the unused bytes (offsets 12-15) in the **CART** header to *data*.
Currently, these bytes are unused by Atari800, but future versions
may define a use for them. Normally, **rom2cart** sets them to all
zeroes. *data* is a 32-bit unsigned value, and may be given in hex
(prefixed with $ or 0x) or decimal (no prefix). This option has no
effect if the output is a raw dump (**-r** option).
-H
Test the code-detection heuristics: examine the first 8K of the ROM and
look for writes to $D2xx (8-bit computer) or $E8xx (5200) to guess the
machine type for the ROM. This option exists only for testing: normally,
the machine type gets guessed by the cartridge option bytes, and the
code-detection is only done if the option byte tests are inconclusive.
NOTES
=====
*infile* may be '-' to read from standard input. *outfile* may be '-' to
write to standard output. **rom2cart** 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
*.car* (or *.rom* if **-r** is given), or by appending *.car* (or *.rom*) if there
is no extension.
**rom2cart** contains an internal database of image types. The current
version uses the list from Atari800 v5.2.0 (types 1-103 and 160). If you
need to create a **.CAR** image of a type not supported in this
version of **rom2cart**, you can use the **-T** option. Alternatively, look
for a newer version of **rom2cart**. If no new version exists, bug the
author until he releases one!
The **-T** option should be used with caution. It disables all the
checks that are normally done, and can be used to create **.CAR** files
with arbitrary types and data sizes (e.g. a 16K image with its
type set to "Standard 8K", or an image whose type isn't recognized
by Atari800 at all). With **-T**, it's up to you to ensure that the image
type and size is correct.
CART FORMAT
===========
The **.CAR** format is fully documented in *cart.txt*, supplied
with the Atari800 source distribution. The following is an abbreviated
description.
A **.CAR** image consists of a 16-byte header followed by the ROM data.
The first 4 bytes contain 'C' 'A' 'R' 'T' in ASCII.
The next 4 bytes contain the cartridge type in MSB (aka *big-endian*)
32-bit integer format.
The next 4 bytes contain cartridge checksum in MSB format (ROM only;
the header is not checksummed).
The next 4 bytes are currently unused (zero).
The rest of the file contains the ROM data, up to 32Mbytes as of
Atari800 5.2.0. The cartridge type determines the amount of data; see
*cart.txt* or the output of **rom2cart -l**.
The latest version of *cart.txt* can be found at:
https://raw.githubusercontent.com/atari800/atari800/master/DOC/cart.txt
HEURISTICS
==========
If none of the **-m**, **-n**, **-T** options are given, the machine type is
guessed according to these rules:
First, examine the option byte (3rd-to-last in the ROM image). If
it's *$FF* or in the range *$50-$59*, assume 5200. If it's *$04*, *$05*, or
*$80*, assume 8-bit computer.
If the option byte doesn't help, and if the ROM is 32K or larger
in size, the cartridge init address (last two bytes of ROM) is
checked. If it falls in the range *$4000-$7FFF*, it must be a 5200 ROM
(because cartridge ROM starts at *$8000* on the 8-bit).
If the ROM is less than 32K, and/or its init address is
>=$8000, rom2cart searches the first 8K of ROM data, looking for
6502 machine code that writes to *$E8xx* (5200 POKEY) or *$D2xx*
(8-bit POKEY). If there are 3 or more "5200 POKEY" writes and zero or
one "8-bit POKEY) writes, assume 5200. If 3 or more "8-bit POKEY"
writes and zero or one "5200 POKEY" writes, assume 8-bit.
If the machine type is still unknown, **rom2cart** will choose
the lowest-numbered cartridge type that matches the ROM size,
regardless of machine type.
EXIT STATUS
===========
Exit status is zero for success, non-zero for failure.
.. include:: manftr.rst
|
