Added icecompr

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