diff options
Diffstat (limited to 'icecompr/README')
| -rw-r--r-- | icecompr/README | 52 |
1 files changed, 52 insertions, 0 deletions
diff --git a/icecompr/README b/icecompr/README new file mode 100644 index 0000000..5e04bb5 --- /dev/null +++ b/icecompr/README @@ -0,0 +1,52 @@ + +A simple compression algorithm for iCE40 bit-streams +==================================================== + +This directory contains tools for compressing and uncompressing +iCE40 bit-streams. The motivation is to reduce the bandwidth +requirements for bit-stream upload. + +Note that iCE40 FPGAs can not uncompress this compressed bit-streams! +Uncompression must be performed by e.g. a uC on the FPGA board. + +This compression algorithm uses the fact that most bits in an iCE40 +bit-stream are cleared. + +The bit-stream is encoded as the distances between set bits (i.e. +the length of runs of ZERO bits between two ONE bits). This sequence +of integers is stored using a simple prefix code to spend fewer bits +on smaller (more frequent) numbers. + +The algorithm includes an escape-mechanism to mix uncompressed binary +data with compressed bit-streams. This is useful when the bit-stream +contains sections that do not compress well with this algorithm, for +example in BRAM initialization data. + +The compressed bitstream starts with the ASCII string "ICECOMPR", i.e. +the hex values 0x49434543 and 0x4f4d5052 (stored as big-endian numbers). + +After the 8 bytes magic the compressed bitstream is a stream of the +following opcodes that must be interpreted by the decompressor. The +notation ZERO and ONE is used for zero and one bits. The notation foo[N] +is used for an N bit value "foo", transmitted MSB first. + + ONE count[2] + ZERO ONE count[5] + ZERO ZERO ONE count[8] + ZERO ZERO ZERO ZERO ONE count[23] + output count ZERO bits followed by a single ONE bit + + ZERO ZERO ZERO ONE count[6] data[count] + output the count data bits followed by a single ONE bit + + ZERO ZERO ZERO ZERO ZERO count[23] + output count ZERO bits and stop decompressing. (end of file) + +The program "icecompr" (C++11, ISC license) contains an implementation of a +compressor and a decompressor. The decompressor in this program however is +only used for integrity checking the compressed bit-stream. + +The program "iceuncompr" (plain C, public domain) contains an implementation +of a stand-alone decompressor. Simply copy&paste this implementation into +your uC firmware. + |