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