UCLZ80

Adam D. Moss, adam@gimp.org / adam@foxbox.org

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

So what?

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 data 'in-place'!
Trivial to use -- set up source and destination pointers, call L2bunpack and you're done.

Usage

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.

        INCLUDE "ucl.asm"
packed_data:
        BINCLUDE "hellokitty.data"
testharness:
        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.)

License

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 v0.99-beta2

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.

History

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

To Do

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.

back

adam@gimp.org / adam@foxbox.org / Adam D. Moss
Last modified: Sat Oct 28 14:56:59 BST 2000