// This file is in AsciiDoc format. It is the source for README.html. :Compact-Option:
+xebin+ is a small command-line utility for manipulating atari binary (executable) files. It can list contents of binary file, merge several files into a single loadable file, or pack file in a way similar to Piotr Fusik's FlashPack.
+xebin+ is written in http://www.digitalmars.com/d/2.0/[D programming language] and tested under Linux and, occasionally, Windows. However, it should be possible to build and run it on any platform, for which D compiler is available. It is designed to be easily embeddable in build scripts.
Both binary releases for Windows and sources for all platforms are available at http://github.com/epi/xebin[github].
To build +xebin+ from sources, you need http://www.digitalmars.com/d/download.html[DMD 2.076] or newer.
Go to console window, and type:
After successful build, you can move file +xebin.exe+ or +xebin+ to a directory within your +PATH+.
A general syntax is:
You can place options wherever you wish in the command line, as well as join single-letter options together, if they do not require parameters.
For all specific commands below you can skip input files specification. In such case, +xebin+ will read from standard input.
Similarly, +xebin+ writes its output to standard output, but you can (and usually you should) specify an output file name with +-o+ or +--output+ option. When using +-v+ or +--verbose+ option, additional output is always written to +stdout+.
You can see the list of available commands and options by typing:
Listing binary file contents
----------------------------
$ xebin l[ist] [input_files]
----------------------------
Example output:
-------------------------------------
D:\proj\tipview>xebin l tv10.xex
0. 8C00-903C (043D)
1. 91DD-A3B7 (11DB)
2. Run 91FD
-------------------------------------
With +-v+ contents of packed blocks are shown, e.g.:
-------------------------------------
D:\proj\fail\vrgb\xebin l vrgb10.xex
0. 4000-470E (070F) (FlashPack 1.0)
0. 3000-39A0 (09A1)
1. 3C21-3C48 (0028)
2. 3CC1-3CF1 (0031)
3. Run 3000
1. Init 4000
-------------------------------------
Merging two or more filesBlocks from all files are concatenated in the order they appear in the list of input files.
Reduntant +FFFF+ headers are dropped.
+-v+ displays layout of resulting file.
Extracting block from binary file
----------------------------
$ xebin e[xtract] [-n=pos] [-r] [-o=fn] [-v] [input_files]
----------------------------
Default option is to extract first block of first input file, including its binary header.
Option +-n=pos+ or +--position=pos+ allows extracting other blocks.
Block numbering is continuous across all input files and starts from 0.
Only one block is extracted at a time.
Option +-r+ or +--raw+ strips header from extracted block.
+-v+ displays info about extracted block.
Disassembling binary fileGenerated output is compatible with http://atariarea.krap.pl/x-asm/[xasm], except for the "unofficial" 6502 opcodes. Opcode names and argument syntax are taken from http://atari800.sourceforge.net/[Atari 800] emulator. No labels are created -- absolute addresses are printed for all variables, jumps, etc.
Compressing binary file
----------------------------
$ xebin p[ack] [-a=ad] [-s] [-o=fn] [-v] [input_files]
----------------------------
The command compresses a binary file using FlashPack algorithm. For each group of
blocks between Init and Run blocks, it creates a single packed block with its own
depacker. Init and Run blocks are copied unchanged.
+xebin+ tries to determine address of packed block so it won't collide with
unpacked blocks. You can override its guess, or just give it a hand when it fails
to do so, by using +-a=ad+ or +--address=ad+ option. Address may be supplied
in decimal or hexadecimal (with +0x+ or +$+ prefix) notation. Address prefixed
with +-+ is treated as address of the last byte of packed block.
+-s+ or +--disable-os+ will cause the interrupts and OS ROM be disabled during depacking.
Apart from an unnoticeable speed-up, it allows for placing unpacked blocks in areas
of RAM normally hidden under OS ROM.
+-v+ displays layout of resulting file and some statistics.
Unpacking binary file+xebin+ can also unpack FlashPack-compressed files. It handles files created by Piotr Fusik's FlashPack 1.0 or 2.1, or +xebin+ itself.
+-v+ displays layout of resulting file.
xebin 1.1.0 (2011-04-20)::
Fixed bug in auto address setting for packed data. Command line options and parameters work according to description. Added support for hexadecimal addresses. Added simple disassembler. Added option to extract block from binary file. Added option to list contents of compressed blocks. +xebin pack -v+ shows some statistics. Build process simplified by incorporating xasm in xebin.
xebin 1.0.0 (2011-01-13)::
Initial release.
It is impossible to set different addresses for multiple input files in pack option, as well as different settings for OS ROM and interrupts.
Issues with +xebin+ should be reported via http://github.com/epi/xebin/issues[this tracker].
Piotr Fusik:: Original FlashPack program, depacker routines, testing.
Adrian Matoga:: Programming.
Poetic License:
This work 'as-is' we provide. No warranty express or implied. We've done our best, to debug and test. Liability for damages denied.