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
|
.. RST source for blob2xex(1) man page. Convert with:
.. rst2man.py blob2xex.rst > blob2xex.1
========
blob2xex
========
--------------------------------------------------
Create Atari 8-bit executables from arbitrary data
--------------------------------------------------
.. include:: manhdr.rst
SYNOPSIS
========
blob2xex *outfile* [**-v**] [**-r** *runaddr*] [**-l** *loadaddr* [**-i** *initaddr*] [**-o** *offset*] [**-s** *size*] *infile*] ...
DESCRIPTION
===========
**blob2xex** creates an Atari 8-bit binary load (xex) file from one or
more files of arbitrary data. Each input file will become a separate
segment in the binary load file. A run address can be added with the
**-r** option.
The first input file *requires* a **-l** *loadaddr* option, to set the
load address. Further input files can have their load addresses set
with **-l**, also. If an input file lacks a load address, it will
load at the next address after the previous file's ending address.
Optionally, init addresses can be included, per-segment
(**-i**). Also, using **-o** and **-s**, it's possible to include only
part of the input file. To read from standard input, use **-** for the
*infile*.
*outfile* must be given as the first argument. When multiple
input files are used, the resulting .xex file will have multiple
segments. If *outfile* already exists, it will be *overwritten*
(or *deleted*, in case of error). Use **-** to write to standard
output. **blob2xex** will not write output to a terminal; **-** must
be used with redirection or a pipe.
If *outfile* or any *infile* is a filename that begins with a **-**,
prefix it with "./", otherwise it'll be taken as an option. The GNU
style **--** (end of options) isn't implemented because it doesn't
make sense here. How often do you really use **-** at the start of a
filename, anyway?
Addresses, offsets, and sizes may be given in decimal or hex. Hex
addresses must be prefixed with either **$** or **0x**.
It's impossible to create a segment that would wrap around the Atari's
64KB address space. Once address **$FFFF** is reached, no more data is
read from the input file.
OPTIONS
=======
A space is required between an option and its argument; use e.g. **-l 0x2000**,
not **-l0x2000**.
-l *loadaddr*
Required; set the load address of the next *infile*. The first *infile*
**must** be preceded by a **-l** option; it's optional for the 2nd and
further files.
-r *runaddr*
Optional; set the run address. Default is no run address. Since a
.xex file can only have one run address, there's no point in giving
multiple **-r** options. If you do, the last one will be used. This
option should be first on the command line (right after *outfile*),
or at least must occur before any *infile*.
-i *initaddr*
Optional; set an init address, to be executed after the next segment loads.
Default is no init address.
-o *offset*
Optional; skip this many bytes of the next input file. Default is **0**.
See the **More Complex Example** below.
-s *size*
Optional; read this many bytes of the next input file. Default is the entire file,
or **0xffff** (**65535**) if the file is longer than 64KB. It's not an error
for *size* to be larger than the file (reading will stop at EOF). Also, the
file's data will be truncated at Atari address **$FFFF**, regardless of
*size* or the size of the file.
-v
Verbose output.
-h, --help
Print usage message and exit.
-V, --version
Print version number and exit.
DIAGNOSTICS
===========
Error messages and warnings are printed to standard error, and are
hopefully self-explanatory. Any message containing *fatal* causes
**blob2xex** to exit with nonzero status, without creating the output
file.
Messages containing *warning* are non-fatal, and the output file is
created. There are only a few possible warnings:
start/end address XXXX loads into ROM.
This means your .xex file's start/end addresses will load the
file into ROM (or the unmapped area at **$C000** on a 400/800).
Normally this means the .xex file won't load properly on the
Atari, but feel free to ignore this warning if you know exactly
what you're doing. Example: if your .xex file is intended to
be loaded on an 800 with an Axlon memory upgrade, mapped at
**$C000**, this warning can be ignored.
extra arguments after last input file ignored.
You gave at least one option that would affect the next file,
after the last file on the command line. Such options are ignored,
since there's no file for them to apply to. Probably you made
a typo or forgot the last input file.
EXIT STATUS
===========
Zero for success (the output file was created), even if there were
warnings. Non-zero for failure (the output file wasn't created).
EXAMPLES
========
Simple Example
--------------
You've written an Atari 8-bit program that loads at **$2000**, which
is also the run address. The assembler you used doesn't create Atari
.xex files, so you've got a **program.bin** that's just raw object
code. To turn it into a runnable .xex file, use:
blob2xex program.xex -l '$2000' -r '$2000' program.bin
Notice the use of quotes around the addresses? That's because the
$ character must be quoted, or the shell will try to interpret it
as a variable reference. You could also have typed **\$2000** or
**0x2000**. Or you could have used decimal (**4096**).
More Complex Example
--------------------
Suppose you want to write a program that can run on an Atari 800,
but you want to use the International Character Set font from the
XL/XE machines. Also suppose that you have the XL ROM image as
*atarixl.rom*.
The way to use the XL ICS font on the 800 is to load it somewhere
in memory, on a 1K boundary. Suppose you've decided to load it at
**$8000**.
Any good reference book or other documentation on the Atari XL/XE
computers will tell you the ICS font is located at **$CC00**. The ROM
image starts at **$C000** (the start of XL/XE ROM), so the font is
located at offset **$0C00** within the ROM image. As always for Atari
fonts, it's 1KB, or **$0400** bytes.
So you can create a .xex file of the ROM font with:
blob2xex romfont.xex -l 0x8000 -o 0x0c00 -s 0x0400 atarixl.rom
Since fonts aren't executable programs, there are no run (**-r**) or
init (**-i**) address options.
The resulting *romfont.xex* can be combined with the rest of your
program with **xexcat**\(1).
.. include:: manftr.rst
|
