123 lines
3.7 KiB
Plaintext
123 lines
3.7 KiB
Plaintext
/*
|
|
* TinyCrunch 1.2
|
|
* Christopher Jam
|
|
* September 2018
|
|
*/
|
|
|
|
About
|
|
=====
|
|
|
|
TinyCrunch is a small, fast LZ codec originally thrown together in a hurry for
|
|
Jam Ball 2. It's since been considerably refined.
|
|
|
|
While the basic design of three byte aligned fixed length token formats remains
|
|
the same, there is now a 100 byte decoder for when space is even tighter, a
|
|
faster decoder (tc_decode_f.s) for use in self extracting files, and optional
|
|
'next block' callbacks for fastload integration. Last but not least, it can
|
|
also now output self extracting .prgs, for any file north of $0200.
|
|
|
|
|
|
Requirements
|
|
============
|
|
|
|
Generating self extracting .prgs only requires python (tested on 2.7 and 3.6)
|
|
|
|
Building the tests, or modifying the boot file used by sfx mode requires ca65.
|
|
|
|
Rebuilding bmp.prg/bmp.bin (the bitmap displayed by the tests) would require Numpy,
|
|
but the .prg and .bin are included in case you have python and ca65 but don't want
|
|
to install any more python libraries to run the example code.
|
|
|
|
|
|
Installation Notes
|
|
==================
|
|
|
|
Wherever you put tc_encode.py, make sure it's accompanied by tc_boot.prg
|
|
|
|
|
|
Usage
|
|
=====
|
|
|
|
python tc_encode.py -h for argument descriptions. Note that you must specify
|
|
precisely one of output start address, output end address, in-place compression,
|
|
self extracting, or raw (headerless) mode.
|
|
|
|
The data files produced by the first three options can be decoded with either
|
|
of the tc_decode*.s routines by calling decode with A and X set to the low and
|
|
high bytes respectively of the address of the data to decrunch.
|
|
|
|
cf SFX notes below for the self extracting option.
|
|
|
|
The fifth option (-r) just reads & writes blocks of binary data with no load address.
|
|
The output file contains no header at all, so it's the caller's responsibility to
|
|
set the source and destination zero page pointers to source address and one less
|
|
than destination address respectively. Cf test/testbin.s for example usage, and
|
|
don't forget to define TC_NO_HEADER when assembling.
|
|
|
|
In this mode the small decruncher is a mere 79 bytes long. Note that in-place
|
|
decompression is not supported in this instance, as the datastream is null terminated
|
|
and there's no header to save the final byte.
|
|
|
|
|
|
SFX notes
|
|
=========
|
|
|
|
Simple sfx example:
|
|
|
|
python tc_encode.py -vx input.prg output.prg
|
|
|
|
Input files can range anywhere from $0200 to $ffff
|
|
|
|
IO area and interrupts are disabled during decrunch, and restored before
|
|
jumping to start address (default $080d)
|
|
|
|
The SFX boot overwrites memory from $00fa to $01ba, and four bytes of stack
|
|
($01f3-$1f6). The rest of low memory is undisturbed.
|
|
|
|
|
|
Test targets
|
|
============
|
|
|
|
make run
|
|
- to test the compact decruncher.
|
|
Uncomment the TC_BLOCK_INTERFACE line in the Makefile to test the block interface too.
|
|
|
|
make frun
|
|
- to test the fast decruncher.
|
|
Uncomment the TC_BLOCK_INTERFACE line in the Makefile to test the block interface too.
|
|
|
|
make runbin
|
|
- to test the headerless compact decruncher.
|
|
|
|
make frunbin
|
|
- to test the headerless fast decruncher.
|
|
|
|
|
|
Change Notes
|
|
============
|
|
|
|
1.1
|
|
- adds raw (headerless) mode, and warns on dissonant file extensions
|
|
|
|
1.1.1
|
|
- ensures test code runs with more versions of cl65 than were originally tested against
|
|
- documents the test targets
|
|
|
|
1.2
|
|
- added small per-token costs to the cost function to (eg) discourage pairs of two byte copies
|
|
wherever a 4 byte copy would provide the same ratio. Improves decrunch speed by 10-20%
|
|
|
|
|
|
Acknowledgements
|
|
================
|
|
|
|
Thanks to Krill for much assistance getting the small decrunch down to 100 bytes,
|
|
as well as general testing and feature requests.
|
|
|
|
Thanks to iAN CooG for beta testing the self extracting file functionality.
|
|
Thanks to groepaz for assistence with cc65 usage.
|
|
|
|
Any remaining bugs are mine.
|
|
|
|
|