Heatshrink decoder

Decoder state diagram:

digraph { graph [label="Decoder state machine", labelloc="t"] Start [style="invis", shape="point"] tag_bit yield_literal backref_index_msb backref_index_lsb backref_count_msb backref_count_lsb yield_backref done [peripheries=2] tag_bit->tag_bit [label="sink()", color="blue", weight=10] Start->tag_bit tag_bit->yield_literal [label="pop 1-bit"] tag_bit->backref_index_msb [label="pop 0-bit", weight=10] tag_bit->backref_index_lsb [label="pop 0-bit, index <8 bits", weight=10] yield_literal->yield_literal [label="sink()", color="blue"] yield_literal->yield_literal [label="poll()", color="red"] yield_literal->tag_bit [label="poll(), done", color="red"] backref_index_msb->backref_index_msb [label="sink()", color="blue"] backref_index_msb->backref_index_lsb [label="pop index, upper bits", weight=10] backref_index_msb->done [label="finish()", color="blue"] backref_index_lsb->backref_index_lsb [label="sink()", color="blue"] backref_index_lsb->backref_count_msb [label="pop index, lower bits", weight=10] backref_index_lsb->backref_count_lsb [label="pop index, count <=8 bits", weight=10] backref_index_lsb->done [label="finish()", color="blue"] backref_count_msb->backref_count_msb [label="sink()", color="blue"] backref_count_msb->backref_count_lsb [label="pop count, upper bits", weight=10] backref_count_msb->done [label="finish()", color="blue"] backref_count_lsb->backref_count_lsb [label="sink()", color="blue"] backref_count_lsb->yield_backref [label="pop count, lower bits", weight=10] backref_count_lsb->done [label="finish()", color="blue"] yield_backref->yield_backref [label="sink()", color="blue"] yield_backref->yield_backref [label="poll()", color="red"] yield_backref->tag_bit [label="poll(), done", color="red", weight=10] tag_bit->done [label="finish()", color="blue"] }

Heatshrink Decoder API.

This header file defines the API for the Heatshrink decoder library.

Defines

HEATSHRINK_DECODER_INPUT_BUFFER_SIZE(BUF)
HEATSHRINK_DECODER_WINDOW_BITS(BUF)
HEATSHRINK_DECODER_LOOKAHEAD_BITS(BUF)

Enums

enum HSD_sink_res

Sink result codes.

These are the possible return values for the heatshrink_decoder_sink function.

Values:

enumerator HSDR_SINK_OK

Data sunk successfully, ready to poll.

enumerator HSDR_SINK_FULL

Out of space in the internal buffer.

enumerator HSDR_SINK_ERROR_NULL

NULL argument error.

enum HSD_poll_res

Poll result codes.

These are the possible return values for the heatshrink_decoder_poll function.

Values:

enumerator HSDR_POLL_EMPTY

Input exhausted.

enumerator HSDR_POLL_MORE

More data remaining, call again with a fresh output buffer.

enumerator HSDR_POLL_ERROR_NULL

NULL argument error.

enumerator HSDR_POLL_ERROR_UNKNOWN

Unknown error.

enum HSD_finish_res

Finish result codes.

These are the possible return values for the heatshrink_decoder_finish function.

Values:

enumerator HSDR_FINISH_DONE

Output is done.

enumerator HSDR_FINISH_MORE

More output remains.

enumerator HSDR_FINISH_ERROR_NULL

NULL argument error.

Functions

heatshrink_decoder *heatshrink_decoder_alloc(uint16_t input_buffer_size, uint8_t expansion_buffer_sz2, uint8_t lookahead_sz2)

Allocate a Heatshrink decoder.

Allocate a decoder with an input buffer of INPUT_BUFFER_SIZE bytes, an expansion buffer size of 2^WINDOW_SZ2, and a lookahead size of 2^LOOKAHEAD_SZ2.

Note

Only for dynamic allocation mode

Parameters:

  • input_buffer_size – Size of the input buffer.

  • expansion_buffer_sz2 – Size of the expansion buffer (window size).

  • lookahead_sz2 – Lookahead size.

Returns:

Pointer to the allocated decoder, or NULL on error.

void heatshrink_decoder_free(heatshrink_decoder *hsd)

Free a Heatshrink decoder.

Free the memory associated with a decoder.

Note

Only for dynamic allocation mode

Parameters:

hsd – Pointer to the decoder to be freed.

void heatshrink_decoder_reset(heatshrink_decoder *hsd)

Reset a Heatshrink decoder.

Reset a decoder to its initial state.

Parameters:

hsd – Pointer to the decoder to be reset.

HSD_sink_res heatshrink_decoder_sink(heatshrink_decoder *hsd, uint8_t *in_buf, size_t size, size_t *input_size)

Sink data into the decoder.

Sink at most SIZE bytes from IN_BUF into the decoder. The INPUT_SIZE is set to indicate how many bytes were actually sunk (in case a buffer was filled).

Parameters:

  • hsd – Pointer to the decoder.

  • in_buf – Pointer to the input buffer.

  • size – Size of the input data.

  • input_size – Pointer to the variable indicating the number of bytes actually sunk.

Returns:

HSD_sink_res value indicating the result of the operation.

HSD_poll_res heatshrink_decoder_poll(heatshrink_decoder *hsd, uint8_t *out_buf, size_t out_buf_size, size_t *output_size)

Poll for output from the decoder.

Poll for output from the decoder, copying at most OUT_BUF_SIZE bytes into OUT_BUF (setting OUTPUT_SIZE to the actual amount copied).

Parameters:

  • hsd – Pointer to the decoder.

  • out_buf – Pointer to the output buffer.

  • out_buf_size – Size of the output buffer.

  • output_size – Pointer to the variable indicating the number of bytes actually output.

Returns:

HSD_poll_res value indicating the result of the operation.

HSD_finish_res heatshrink_decoder_finish(heatshrink_decoder *hsd)

Notify the decoder that the input stream is finished.

Notify the decoder that the input stream is finished. If the return value is HSDR_FINISH_MORE, there is still more output, so call heatshrink_decoder_poll and repeat.

Parameters:

hsd – Pointer to the decoder.

Returns:

HSD_finish_res value indicating the result of the operation.

struct heatshrink_decoder
#include <heatshrink_decoder.h>

Heatshrink decoder structure.

This structure represents a Heatshrink decoder. It contains various fields necessary for the decoding process.

Public Members

uint16_t input_size

Bytes in the input buffer.

uint16_t input_index

Offset to the next unprocessed input byte.

uint16_t output_count

How many bytes to output.

uint16_t output_index

Index for bytes to output.

uint16_t head_index

Head of the window buffer.

uint8_t state

Current state machine node.

uint8_t current_byte

Current byte of input.

uint8_t bit_index

Current bit index.

uint8_t window_sz2

Window buffer bits.

uint8_t lookahead_sz2

Lookahead bits.

uint16_t input_buffer_size

Input buffer size.

uint8_t buffers[]