mirror of https://github.com/YosysHQ/icestorm.git
53 lines
2.1 KiB
Plaintext
53 lines
2.1 KiB
Plaintext
|
|
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.
|
|
|