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