BLOB2XEX(1)

NAME
blob2xex - Create Atari 8-bit executables from arbitrary data

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).

COPYRIGHT

WTFPL. See http://www.wtfpl.net/txt/copying/ for details.

AUTHOR

B.  Watson <urchlay@slackware.uk>; Urchlay on irc.libera.chat ##atari.

SEE ALSO

a8cat(1), a8eol(1), a8xd(1), atr2xfd(1), atrsize(1), axe(1), bas2aplus(1), blob2c(1), blob2xex(1), cart2xex(1), cxrefbas(1), dasm2atasm(1), diffbas(1), dumpbas(1), f2toxex(1), fenders(1), listbas(1), listamsb(1), protbas(1), renumbas(1), rom2cart(1), unmac65(1), unprotbas(1), vxrefbas(1), whichbas(1), xex1to2(1), xexamine(1), xexcat(1), xexsplit(1), xfd2atr(1), xex(5), atascii(7), fauxtari(7).

Any good Atari 8-bit book: De Re Atari, The Atari BASIC Reference Manual, the OS Users' Guide, Mapping the Atari, etc.