heatshrink_decoder.h File Reference

#include <stddef.h>
#include "heatshrink_common.h"
#include "heatshrink_config.h"

Include dependency graph for heatshrink_decoder.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	heatshrink_decoder

Macros
#define	HEATSHRINK_DECODER_INPUT_BUFFER_SIZE(BUF)   ((BUF)->input_buffer_size)
#define	HEATSHRINK_DECODER_WINDOW_BITS(BUF)   ((BUF)->window_sz2)
#define	HEATSHRINK_DECODER_LOOKAHEAD_BITS(BUF)   ((BUF)->lookahead_sz2)

Enumerations
enum	HSD_sink_res { HSDR_SINK_OK, HSDR_SINK_FULL, HSDR_SINK_ERROR_NULL =-1 }
enum	HSD_poll_res { HSDR_POLL_EMPTY, HSDR_POLL_MORE, HSDR_POLL_ERROR_NULL =-1, HSDR_POLL_ERROR_UNKNOWN =-2 }
enum	HSD_finish_res { HSDR_FINISH_DONE, HSDR_FINISH_MORE, HSDR_FINISH_ERROR_NULL =-1 }

Functions
heatshrink_decoder *	heatshrink_decoder_alloc (uint16_t input_buffer_size, uint8_t expansion_buffer_sz2, uint8_t lookahead_sz2)
void	heatshrink_decoder_free (heatshrink_decoder *hsd)
void	heatshrink_decoder_reset (heatshrink_decoder *hsd)
HSD_sink_res	heatshrink_decoder_sink (heatshrink_decoder *hsd, uint8_t *in_buf, size_t size, size_t *input_size)
HSD_poll_res	heatshrink_decoder_poll (heatshrink_decoder *hsd, uint8_t *out_buf, size_t out_buf_size, size_t *output_size)
HSD_finish_res	heatshrink_decoder_finish (heatshrink_decoder *hsd)

Macro Definition Documentation

HEATSHRINK_DECODER_INPUT_BUFFER_SIZE

#define HEATSHRINK_DECODER_INPUT_BUFFER_SIZE

(

BUF

)

((BUF)->input_buffer_size)

Definition at line 28 of file heatshrink_decoder.h.

Referenced by heatshrink_decoder_reset(), heatshrink_decoder_sink(), st_yield_backref(), and st_yield_literal().

HEATSHRINK_DECODER_LOOKAHEAD_BITS

#define HEATSHRINK_DECODER_LOOKAHEAD_BITS

(

BUF

)

((BUF)->lookahead_sz2)

Definition at line 32 of file heatshrink_decoder.h.

HEATSHRINK_DECODER_WINDOW_BITS

#define HEATSHRINK_DECODER_WINDOW_BITS

(

BUF

)

((BUF)->window_sz2)

Definition at line 30 of file heatshrink_decoder.h.

Referenced by heatshrink_decoder_reset(), st_input_available(), st_yield_backref(), and st_yield_literal().

Enumeration Type Documentation

HSD_finish_res

enum HSD_finish_res

Enumerator
HSDR_FINISH_DONE
HSDR_FINISH_MORE
HSDR_FINISH_ERROR_NULL

Definition at line 21 of file heatshrink_decoder.h.

             {
    HSDR_FINISH_DONE,           /* output is done */
    HSDR_FINISH_MORE,           /* more output remains */
    HSDR_FINISH_ERROR_NULL=-1,  /* NULL arguments */
} HSD_finish_res;

HSD_poll_res

enum HSD_poll_res

Enumerator
HSDR_POLL_EMPTY
HSDR_POLL_MORE
HSDR_POLL_ERROR_NULL
HSDR_POLL_ERROR_UNKNOWN

Definition at line 14 of file heatshrink_decoder.h.

             {
    HSDR_POLL_EMPTY,            /* input exhausted */
    HSDR_POLL_MORE,             /* more data remaining, call again w/ fresh output buffer */
    HSDR_POLL_ERROR_NULL=-1,    /* NULL arguments */
    HSDR_POLL_ERROR_UNKNOWN=-2,
} HSD_poll_res;

HSD_sink_res

enum HSD_sink_res

Enumerator
HSDR_SINK_OK
HSDR_SINK_FULL
HSDR_SINK_ERROR_NULL

Definition at line 8 of file heatshrink_decoder.h.

             {
    HSDR_SINK_OK,               /* data sunk, ready to poll */
    HSDR_SINK_FULL,             /* out of space in internal buffer */
    HSDR_SINK_ERROR_NULL=-1,    /* NULL argument */
} HSD_sink_res;

Function Documentation

heatshrink_decoder_alloc()

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

Definition at line 51 of file heatshrink_decoder.c.

References heatshrink_decoder_reset(), HEATSHRINK_MALLOC, HEATSHRINK_MAX_WINDOW_BITS, HEATSHRINK_MIN_LOOKAHEAD_BITS, HEATSHRINK_MIN_WINDOW_BITS, hsd, heatshrink_decoder::input_buffer_size, LOG, heatshrink_decoder::lookahead_sz2, NULL, and heatshrink_decoder::window_sz2.

Referenced by compress_and_expand_and_check(), data_with_simple_repetition_should_match_with_absurdly_tiny_buffers(), data_without_duplication_should_match_with_absurdly_tiny_buffers(), decode(), decoder_alloc_should_reject_excessively_small_window(), decoder_alloc_should_reject_zero_byte_input_buffer(), decoder_finish_should_note_when_done(), decoder_finish_should_reject_null_input(), decoder_poll_should_expand_short_literal(), decoder_poll_should_expand_short_literal_and_backref(), decoder_poll_should_expand_short_literal_and_backref_when_fed_input_byte_by_byte(), decoder_poll_should_expand_short_self_overlapping_backref(), decoder_poll_should_reject_null_output_buffer(), decoder_poll_should_reject_null_output_size_pointer(), decoder_poll_should_return_empty_if_empty(), decoder_poll_should_suspend_if_out_of_space_in_output_buffer_during_backref_expansion(), decoder_poll_should_suspend_if_out_of_space_in_output_buffer_during_literal_expansion(), decoder_should_not_get_stuck_with_finish_yielding_MORE_but_0_bytes_output_from_poll(), decoder_sink_should_reject_excessively_large_input(), decoder_sink_should_reject_null_count_pointer(), decoder_sink_should_reject_null_input_pointer(), decoder_sink_should_sink_data_when_preconditions_hold(), and espFsOpen().

                                                                    {
    if ((window_sz2 < HEATSHRINK_MIN_WINDOW_BITS) ||
        (window_sz2 > HEATSHRINK_MAX_WINDOW_BITS) ||
        (input_buffer_size == 0) ||
        (lookahead_sz2 < HEATSHRINK_MIN_LOOKAHEAD_BITS) ||
        (lookahead_sz2 > window_sz2)) {
        return NULL;
    }
    size_t buffers_sz = (1 << window_sz2) + input_buffer_size;
    size_t sz = sizeof(heatshrink_decoder) + buffers_sz;
    heatshrink_decoder *hsd = HEATSHRINK_MALLOC(sz);
    if (hsd == NULL) { return NULL; }
    hsd->input_buffer_size = input_buffer_size;
    hsd->window_sz2 = window_sz2;
    hsd->lookahead_sz2 = lookahead_sz2;
    heatshrink_decoder_reset(hsd);
    LOG("-- allocated decoder with buffer size of %zu (%zu + %u + %u)\n",
        sz, sizeof(heatshrink_decoder), (1 << window_sz2), input_buffer_size);
    return hsd;
}

Here is the call graph for this function:

Here is the caller graph for this function:

heatshrink_decoder_finish()

HSD_finish_res heatshrink_decoder_finish

(

heatshrink_decoder *

hsd

)

Definition at line 354 of file heatshrink_decoder.c.

References HSDR_FINISH_DONE, HSDR_FINISH_ERROR_NULL, HSDR_FINISH_MORE, HSDS_BACKREF_COUNT_LSB, HSDS_BACKREF_COUNT_MSB, HSDS_BACKREF_INDEX_LSB, HSDS_BACKREF_INDEX_MSB, HSDS_EMPTY, HSDS_YIELD_LITERAL, heatshrink_decoder::input_size, NULL, and heatshrink_decoder::state.

Referenced by compress_and_expand_and_check(), decode(), decoder_finish_should_note_when_done(), decoder_finish_should_reject_null_input(), decoder_poll_should_expand_short_literal_and_backref_when_fed_input_byte_by_byte(), decoder_should_not_get_stuck_with_finish_yielding_MORE_but_0_bytes_output_from_poll(), decoder_sink_read(), and espFsRead().

                                                                  {
    if (hsd == NULL) { return HSDR_FINISH_ERROR_NULL; }
    switch (hsd->state) {
    case HSDS_EMPTY:
        return HSDR_FINISH_DONE;

    /* If we want to finish with no input, but are in these states, it's
     * because the 0-bit padding to the last byte looks like a backref
     * marker bit followed by all 0s for index and count bits. */
    case HSDS_BACKREF_INDEX_LSB:
    case HSDS_BACKREF_INDEX_MSB:
    case HSDS_BACKREF_COUNT_LSB:
    case HSDS_BACKREF_COUNT_MSB:
        return hsd->input_size == 0 ? HSDR_FINISH_DONE : HSDR_FINISH_MORE;

    /* If the output stream is padded with 0xFFs (possibly due to being in
     * flash memory), also explicitly check the input size rather than
     * uselessly returning MORE but yielding 0 bytes when polling. */
    case HSDS_YIELD_LITERAL:
        return hsd->input_size == 0 ? HSDR_FINISH_DONE : HSDR_FINISH_MORE;

    default:
        return HSDR_FINISH_MORE;
    }
}

Here is the caller graph for this function:

heatshrink_decoder_free()

void heatshrink_decoder_free

(

heatshrink_decoder *

hsd

)

Definition at line 74 of file heatshrink_decoder.c.

References HEATSHRINK_FREE, heatshrink_decoder::input_buffer_size, and heatshrink_decoder::window_sz2.

Referenced by compress_and_expand_and_check(), data_with_simple_repetition_should_match_with_absurdly_tiny_buffers(), data_without_duplication_should_match_with_absurdly_tiny_buffers(), decode(), decoder_finish_should_note_when_done(), decoder_finish_should_reject_null_input(), decoder_poll_should_expand_short_literal(), decoder_poll_should_expand_short_literal_and_backref(), decoder_poll_should_expand_short_literal_and_backref_when_fed_input_byte_by_byte(), decoder_poll_should_expand_short_self_overlapping_backref(), decoder_poll_should_reject_null_output_buffer(), decoder_poll_should_reject_null_output_size_pointer(), decoder_poll_should_return_empty_if_empty(), decoder_poll_should_suspend_if_out_of_space_in_output_buffer_during_backref_expansion(), decoder_poll_should_suspend_if_out_of_space_in_output_buffer_during_literal_expansion(), decoder_should_not_get_stuck_with_finish_yielding_MORE_but_0_bytes_output_from_poll(), decoder_sink_should_reject_excessively_large_input(), decoder_sink_should_reject_null_count_pointer(), decoder_sink_should_reject_null_input_pointer(), decoder_sink_should_sink_data_when_preconditions_hold(), and espFsClose().

                                                      {
    size_t buffers_sz = (1 << hsd->window_sz2) + hsd->input_buffer_size;
    size_t sz = sizeof(heatshrink_decoder) + buffers_sz;
    HEATSHRINK_FREE(hsd, sz);
    (void)sz;   /* may not be used by free */
}

Here is the caller graph for this function:

heatshrink_decoder_poll()

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

Definition at line 143 of file heatshrink_decoder.c.

References output_info::buf, output_info::buf_size, HSDR_POLL_EMPTY, HSDR_POLL_ERROR_NULL, HSDR_POLL_ERROR_UNKNOWN, HSDR_POLL_MORE, HSDS_BACKREF_COUNT_LSB, HSDS_BACKREF_COUNT_MSB, HSDS_BACKREF_INDEX_LSB, HSDS_BACKREF_INDEX_MSB, HSDS_CHECK_FOR_MORE_INPUT, HSDS_EMPTY, HSDS_INPUT_AVAILABLE, HSDS_YIELD_BACKREF, HSDS_YIELD_LITERAL, heatshrink_decoder::input_size, LOG, NULL, output_info::output_size, st_backref_count_lsb(), st_backref_count_msb(), st_backref_index_lsb(), st_backref_index_msb(), st_check_for_input(), st_input_available(), st_yield_backref(), st_yield_literal(), and heatshrink_decoder::state.

Referenced by compress_and_expand_and_check(), data_with_simple_repetition_should_match_with_absurdly_tiny_buffers(), data_without_duplication_should_match_with_absurdly_tiny_buffers(), decoder_finish_should_note_when_done(), decoder_poll_should_expand_short_literal(), decoder_poll_should_expand_short_literal_and_backref(), decoder_poll_should_expand_short_literal_and_backref_when_fed_input_byte_by_byte(), decoder_poll_should_expand_short_self_overlapping_backref(), decoder_poll_should_reject_null_hsd(), decoder_poll_should_reject_null_output_buffer(), decoder_poll_should_reject_null_output_size_pointer(), decoder_poll_should_return_empty_if_empty(), decoder_poll_should_suspend_if_out_of_space_in_output_buffer_during_backref_expansion(), decoder_poll_should_suspend_if_out_of_space_in_output_buffer_during_literal_expansion(), decoder_should_not_get_stuck_with_finish_yielding_MORE_but_0_bytes_output_from_poll(), decoder_sink_read(), and espFsRead().

                                                                    {
    if ((hsd == NULL) || (out_buf == NULL) || (output_size == NULL)) {
        return HSDR_POLL_ERROR_NULL;
    }
    *output_size = 0;

    output_info oi;
    oi.buf = out_buf;
    oi.buf_size = out_buf_size;
    oi.output_size = output_size;

    while (1) {
        LOG("-- poll, state is %d (%s), input_size %d\n",
            hsd->state, state_names[hsd->state], hsd->input_size);
        uint8_t in_state = hsd->state;
        switch (in_state) {
        case HSDS_EMPTY:
            return HSDR_POLL_EMPTY;
        case HSDS_INPUT_AVAILABLE:
            hsd->state = st_input_available(hsd);
            break;
        case HSDS_YIELD_LITERAL:
            hsd->state = st_yield_literal(hsd, &oi);
            break;
        case HSDS_BACKREF_INDEX_MSB:
            hsd->state = st_backref_index_msb(hsd);
            break;
        case HSDS_BACKREF_INDEX_LSB:
            hsd->state = st_backref_index_lsb(hsd);
            break;
        case HSDS_BACKREF_COUNT_MSB:
            hsd->state = st_backref_count_msb(hsd);
            break;
        case HSDS_BACKREF_COUNT_LSB:
            hsd->state = st_backref_count_lsb(hsd);
            break;
        case HSDS_YIELD_BACKREF:
            hsd->state = st_yield_backref(hsd, &oi);
            break;
        case HSDS_CHECK_FOR_MORE_INPUT:
            hsd->state = st_check_for_input(hsd);
            break;
        default:
            return HSDR_POLL_ERROR_UNKNOWN;
        }
        
        /* If the current state cannot advance, check if input or output
         * buffer are exhausted. */
        if (hsd->state == in_state) {
            if (*output_size == out_buf_size) { return HSDR_POLL_MORE; }
            return HSDR_POLL_EMPTY;
        }
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

heatshrink_decoder_reset()

void heatshrink_decoder_reset

(

heatshrink_decoder *

hsd

)

Definition at line 82 of file heatshrink_decoder.c.

References heatshrink_decoder::bit_accumulator, heatshrink_decoder::bit_index, heatshrink_decoder::buffers, heatshrink_decoder::current_byte, heatshrink_decoder::head_index, HEATSHRINK_DECODER_INPUT_BUFFER_SIZE, HEATSHRINK_DECODER_WINDOW_BITS, HSDS_EMPTY, heatshrink_decoder::input_index, heatshrink_decoder::input_size, memset, heatshrink_decoder::output_count, heatshrink_decoder::output_index, and heatshrink_decoder::state.

Referenced by compress_and_expand_and_check(), decoder_should_not_get_stuck_with_finish_yielding_MORE_but_0_bytes_output_from_poll(), and heatshrink_decoder_alloc().

                                                       {
    size_t buf_sz = 1 << HEATSHRINK_DECODER_WINDOW_BITS(hsd);
    size_t input_sz = HEATSHRINK_DECODER_INPUT_BUFFER_SIZE(hsd);
    memset(hsd->buffers, 0, buf_sz + input_sz);
    hsd->state = HSDS_EMPTY;
    hsd->input_size = 0;
    hsd->input_index = 0;
    hsd->bit_index = 0x00;
    hsd->current_byte = 0x00;
    hsd->output_count = 0;
    hsd->output_index = 0;
    hsd->head_index = 0;
    hsd->bit_accumulator = 0x00000000;
}

Here is the caller graph for this function:

heatshrink_decoder_sink()

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

Definition at line 98 of file heatshrink_decoder.c.

References heatshrink_decoder::buffers, HEATSHRINK_DECODER_INPUT_BUFFER_SIZE, HSDR_SINK_ERROR_NULL, HSDR_SINK_FULL, HSDR_SINK_OK, HSDS_EMPTY, HSDS_INPUT_AVAILABLE, heatshrink_decoder::input_index, heatshrink_decoder::input_size, LOG, memcpy, NULL, and heatshrink_decoder::state.

Referenced by compress_and_expand_and_check(), data_with_simple_repetition_should_match_with_absurdly_tiny_buffers(), data_without_duplication_should_match_with_absurdly_tiny_buffers(), decoder_finish_should_note_when_done(), decoder_poll_should_expand_short_literal(), decoder_poll_should_expand_short_literal_and_backref(), decoder_poll_should_expand_short_literal_and_backref_when_fed_input_byte_by_byte(), decoder_poll_should_expand_short_self_overlapping_backref(), decoder_poll_should_suspend_if_out_of_space_in_output_buffer_during_backref_expansion(), decoder_poll_should_suspend_if_out_of_space_in_output_buffer_during_literal_expansion(), decoder_should_not_get_stuck_with_finish_yielding_MORE_but_0_bytes_output_from_poll(), decoder_sink_read(), decoder_sink_should_reject_excessively_large_input(), decoder_sink_should_reject_null_count_pointer(), decoder_sink_should_reject_null_hsd_pointer(), decoder_sink_should_reject_null_input_pointer(), decoder_sink_should_sink_data_when_preconditions_hold(), and espFsRead().

                                                          {
    if ((hsd == NULL) || (in_buf == NULL) || (input_size == NULL)) {
        return HSDR_SINK_ERROR_NULL;
    }

    size_t rem = HEATSHRINK_DECODER_INPUT_BUFFER_SIZE(hsd) - hsd->input_size;
    if (rem == 0) {
        *input_size = 0;
        return HSDR_SINK_FULL;
    }

    size = rem < size ? rem : size;
    LOG("-- sinking %zd bytes\n", size);
    /* copy into input buffer (at head of buffers) */
    memcpy(&hsd->buffers[hsd->input_size], in_buf, size);
    hsd->input_size += size;
    if (hsd->state == HSDS_EMPTY) {
        hsd->state = HSDS_INPUT_AVAILABLE;
        hsd->input_index = 0;
    }
    *input_size = size;
    return HSDR_SINK_OK;
}

Here is the caller graph for this function: