Adam D. Moss, firstname.lastname@example.org / email@example.com
This is a decompressor for data packed with M.F.X.J. Oberhumer's
UCL library (A.K.A. the magic behind UPX), specifically data compressed with UCL's "2B" algorithm.
This decompressor is written for the 8-bit Zilog Z80 CPU and
compatibles, and uses just ~245 bytes of RAM for code and
- The UCL/2B algorithm offers highly competitive compression ratios
on code and data, and excellent decompression speed --
ideal for runtime unpacking of precompressed data.
- This implementation of the decompressor runs and operates in a constant
~245 of RAM, making it ideal for use in low-memory
(ie. embedded) systems.
- Allows overlapping source and destination buffers -- unpack your
- Trivial to use -- set up source and destination pointers, call
L2bunpack and you're done.
More comprehensive usage instructions are in the ucl.asm file itself,
but here is a quick example for you. This snippet takes packed image data
and unpacks it to an address corresponding to the framebuffer on the
Sinclair ZX Spectrum.
ld bc, packed_data
ld de, 16384 ; destination (eg. frame buffer address)
call L2bunpack ; unpack data at 'bc' address to 'de' address
out.sna is a .SNA file of this example poised
before unpacking begins. (Actually it's a slightly less stripped-down
version, but it does the same.)
This Z80 implementation of the unpacker is essentially public domain --
see the source file for details. I'd appreciate a mention if you use
this (and drop me an email to say hi!).
Downloads and Links
The UCL/2B unpacker, Z80 assembly source code: ucl.asm
The UCL/2B packer executable, compiled for a Linux/x86/glibc system: simple.bin
The UCL/2B packer source, written in ANSI C: simple.c
- The packer itself is licensed under the GPL (being based on a
UCL utility; see the UCL distribution if you don't know what the
GPL is). This file needs to be dropped in place of the
simple.c in the 'examples' directory of the UCL distribution
(available via the below link, or here) before building the UCL tree.
- The resulting program, 'simple', takes as a parameter the
filename of the data which needs to be compressed, and writes
the resulting compressed data to a file called COMPR. This is headerless
compressed data suitable for BINCLUDING (or equivilent) from
your assembly code.
- The 'simple' program will also tell you the 'minimal nonoverlap
slop' for your data. This is the minimum number of spare bytes than
must exist between the end of the unpacked destination buffer and
the end of the packed buffer when you want packed and
unpacked buffers to overlap in range.
Here's a link to M.F.X.J. Oberhumer's page of
fun stuff, mostly his ongoing compression work. You can get to the
latest UNIX/C versions of the UCL stuff from there.
In The Wild
Wow, someone has admitted to using UCLZ80 in a real production: You Are Adult by AY Riders. That makes me happy.
v0.99-beta2: 2000-10-25: First public release. I'm still calling it
beta because it hasn't gotten much public 'airing', for now. I was
actually sitting on it for a while hoping to use it for something
world-shattering but haven't found the time yet, so here it is for all
to share (especially those who still develop for the Sinclair ZX
Spectrum and the TI-8x, you great guys and girls!)
I can't promise to work on these, but let me know which are a priority
for you. Additionally, if you wish to contribute work towards the
following then you would be welcome.
- A size-optimized version to complement the existing
speed-optimized version. Anticipate an approximate size of 180 bytes
- A 'no scratch memory' decompressor which operates entirely
out of ROM, touching no memory except for the decompression buffer
- A dumb, slow implementation of the UCL/2B compressor for the Z80,
for completeness (does anyone really need this?)
- A bit-granular (de/)compressor optimized for best ratios on
bitmapped graphic data.
firstname.lastname@example.org / email@example.com / Adam D. Moss
Last modified: Sat Oct 28 14:56:59 BST 2000