RAR 5.0 entropy front-end: bit reader, canonical Huffman, block tables. More...

#include <string.h>
#include "ra8_attributes.h"
#include "ra8_rar5.h"
#include "ra8_rar5_internal.h"

Include dependency graph for ra8_rar5_tables.c:

Functions
static uint8_t	internal_fetch_byte (ra8_rar5_state_t *st)
	Pull the next packed byte, refilling the window from the backing reader.
static void	internal_ensure (ra8_rar5_state_t *st, uint32_t n)
	Ensure at least `n` bits are buffered in the accumulator.
static uint32_t	internal_peek (ra8_rar5_state_t *st, uint32_t n)
	Peek the next `n` bits without consuming them.
static void	internal_drop (ra8_rar5_state_t *st, uint32_t n)
	Consume `n` previously-peeked bits.
uint32_t	priv_rar5_get (ra8_rar5_state_t *st, uint32_t n)
	Implementation of priv_rar5_get() – internal_peek then internal_drop of `n` bits.
static void	internal_align (ra8_rar5_state_t *st)
	Discard bits up to the next byte boundary.
static void	internal_tab_limits (ra8_rar5_dtab_t d, const uint32_t count)
	Fill a decode table's per-length upper-limit and start-position arrays.
static void	internal_make_tables (ra8_rar5_dtab_t d, const uint8_t lengths, uint16_t size)
	Build a canonical Huffman decode table from a bit-length vector.
uint32_t	priv_rar5_decode_num (ra8_rar5_state_t st, const ra8_rar5_dtab_t d)
	Implementation of priv_rar5_decode_num() – limit-compare canonical decode.
static uint8_t	internal_checksum (uint32_t flags, uint64_t blocksize)
	Compute the RAR5 block-header checksum byte.
ra8_err_t	priv_rar5_read_block_header (ra8_rar5_state_t st, r5_block_t b)
	Implementation of priv_rar5_read_block_header() – align, flags, size, checksum.
uint32_t	priv_rar5_fill_zeros (uint8_t *out, uint32_t start, uint32_t count, uint32_t max)
	Implementation of priv_rar5_fill_zeros() – bounded zero-length append.
static ra8_err_t	internal_read_bd_lengths (ra8_rar5_state_t st, uint8_t out)
	Read the 20-entry bit-length pre-table (BD) length list.
ra8_err_t	priv_rar5_apply_run (ra8_rar5_state_t st, uint8_t tbl, uint32_t *idx, uint32_t num)
	Implementation of priv_rar5_apply_run() – copy-previous / zero run append.
static ra8_err_t	internal_read_full_table (ra8_rar5_state_t st, uint8_t tbl)
	Decode the combined length table for the four LZ alphabets.
ra8_err_t	priv_rar5_read_tables (ra8_rar5_state_t *st)
	Implementation of priv_rar5_read_tables() – BD pre-table then the four LZ tables.

Detailed Description

RAR 5.0 entropy front-end: bit reader, canonical Huffman, block tables.

Tag: [Ring 4 / Domain] {World: NS}

The lower half of the clean-room RAR 5.0 decompressor (paired with the LZ driver in ra8_rar5.c). Three layers, bottom-up:

Bit reader: internal_fetch_byte / internal_ensure / internal_peek / internal_drop / priv_rar5_get / internal_align pull packed bytes through the archive ra8_rar_read_fn on demand, serving an MSB-first bit stream.
Huffman: internal_make_tables builds a canonical decode table from a bit-length vector; priv_rar5_decode_num reads one symbol.
Container: priv_rar5_read_block_header validates one compressed-block header and priv_rar5_read_tables parses the four LZ decode tables that drive it.

The driver in ra8_rar5.c calls the four ::ra8_rar5_internal.h cross-TU entry points here; nothing in this unit calls back into the driver.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: Version 0.1.0

Definition in file ra8_rar5_tables.c.

Function Documentation

◆ internal_align()

void internal_align ( ra8_rar5_state_t * st )

static

Discard bits up to the next byte boundary.

Drops the sub-byte residue so the following read starts on a whole packed byte, as each RAR5 block header requires.

Parameters

[in,out] st Decoder state (non-NULL).

Returns: Nothing.

Precondition: st is a bound decoder state.; The residue bits are already buffered (always true after a read).

Postcondition: st->consumed is a multiple of 8.; No packed byte is skipped whole.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 165 of file ra8_rar5_tables.c.

References internal_drop(), k_r5_low3_mask, and RA8_INTERNAL.

Referenced by priv_rar5_read_block_header().

◆ internal_checksum()

uint8_t internal_checksum	(	uint32_t	flags,
		uint64_t	blocksize )

static

Compute the RAR5 block-header checksum byte.

XOR of the seed, the flags, and the three low bytes of the block size – the value the header stores for validation.

Parameters

[in]	flags	Block-flags byte.
[in]	blocksize	Decoded block size.

Returns: The expected checksum byte.

Return values

0	When the XOR of all inputs is zero.

Precondition: flags is the raw block-flags byte.; blocksize is the decoded block size.

Postcondition: No state is modified (pure function).; The result fits one byte.

Note: Thread-safe: pure.

Since: Version 0.1.0

Definition at line 277 of file ra8_rar5_tables.c.

References k_r5_byte_bits, k_r5_byte_mask, k_r5_hdr_chk_seed, and RA8_INTERNAL.

Referenced by priv_rar5_read_block_header().

◆ internal_drop()

void internal_drop	(	ra8_rar5_state_t *	st,
		uint32_t	n )

static

Consume n previously-peeked bits.

Reduces the buffered count and the running consumed-bit total, keeping the accumulator masked to its remaining valid bits.

Parameters

[in,out]	st	Decoder state (non-NULL).
[in]	n	Bits to consume (<= currently buffered).

Returns: Nothing.

Precondition: st is a bound decoder state.; n <= st::nbits.

Postcondition: st->nbits decreased by n and st->consumed increased by n.; st::acc retains only its remaining valid bits.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 134 of file ra8_rar5_tables.c.

References k_r5_acc_bits, and RA8_INTERNAL.

Referenced by internal_align(), priv_rar5_decode_num(), and priv_rar5_get().

◆ internal_ensure()

void internal_ensure	(	ra8_rar5_state_t *	st,
		uint32_t	n )

static

Ensure at least n bits are buffered in the accumulator.

Shifts whole bytes in from internal_fetch_byte until the buffered bit count reaches n; past-end fetches contribute zero bits.

Parameters

[in,out]	st	Decoder state (non-NULL).
[in]	n	Bits required (1..32).

Returns: Nothing.

Precondition: st is a bound decoder state.; n <= 32.

Postcondition: st->nbits >= n.; st::acc holds the buffered bits, oldest at the top.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 89 of file ra8_rar5_tables.c.

References internal_fetch_byte(), k_r5_byte_bits, and RA8_INTERNAL.

Referenced by internal_peek().

◆ internal_fetch_byte()

uint8_t internal_fetch_byte ( ra8_rar5_state_t * st )

static

Pull the next packed byte, refilling the window from the backing reader.

Serves bytes from the ra8_rar5_state_t::refill window, refetching a fresh window through the archive reader when it drains. Past the packed member end it returns 0 and latches ra8_rar5_state_t::overrun.

Parameters

[in,out] st Decoder state (non-NULL).

Returns: The next packed byte, or 0 at/after the member end.

Return values

0	The packed member is exhausted (overrun latched).

Precondition: st was bound with a valid archive reader.; st::base + st::packlen is within the archive.

Postcondition: On success st::refill_pos advanced by one.; At member end st::overrun is true.

Note: Not thread-safe; drives the archive reader.

Since: Version 0.1.0

Definition at line 50 of file ra8_rar5_tables.c.

References k_ra8_rar5_refill_bytes, and RA8_INTERNAL.

Referenced by internal_ensure().

◆ internal_make_tables()

void internal_make_tables	(	ra8_rar5_dtab_t *	d,
		const uint8_t *	lengths,
		uint16_t	size )

static

Build a canonical Huffman decode table from a bit-length vector.

Counts codes per length, computes the prefix limits via internal_tab_limits, then assigns each non-zero-length symbol to its canonical code slot in symbol order. Zero-length symbols are absent from the table.

Parameters

[out]	d	Table to populate (non-NULL).
[in]	lengths	Per-symbol bit lengths (`size` entries).
[in]	size	Alphabet size (<= k_ra8_rar5_nc).

Returns: Nothing.

Precondition: lengths holds size readable bytes.; size <= k_ra8_rar5_nc.

Postcondition: d->max == size and populated slots hold their symbols.; Every slot index read by priv_rar5_decode_num is initialised.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 217 of file ra8_rar5_tables.c.

References internal_tab_limits(), k_r5_maxbits, k_r5_nibble_mask, ra8_rar5_dtab_t::max, memset(), ra8_rar5_dtab_t::num, and ra8_rar5_dtab_t::pos.

Referenced by priv_rar5_read_tables().

◆ internal_peek()

uint32_t internal_peek	(	ra8_rar5_state_t *	st,
		uint32_t	n )

static

Peek the next n bits without consuming them.

Ensures the bits are buffered, then returns the top n bits of the accumulator as a right-aligned value.

Parameters

[in,out]	st	Decoder state (non-NULL).
[in]	n	Bits to read (1..32).

Returns: The next n bits, oldest bit most significant.

Return values

0	When the next `n` bits are all zero (or all padding).

Precondition: st is a bound decoder state.; 1 <= n <= 32.

Postcondition: st::consumed is unchanged (a pure peek).; At least n bits remain buffered.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 113 of file ra8_rar5_tables.c.

References internal_ensure(), and RA8_INTERNAL.

Referenced by priv_rar5_decode_num(), and priv_rar5_get().

◆ internal_read_bd_lengths()

ra8_err_t internal_read_bd_lengths	(	ra8_rar5_state_t *	st,
		uint8_t *	out )

static

Read the 20-entry bit-length pre-table (BD) length list.

Each entry is a 4-bit length; the value 15 escapes to a following 4-bit field that is either a literal length-15 code (0) or a zero run (n+2).

Parameters

[in,out]	st	Decoder state (non-NULL).
[out]	out	Receives k_ra8_rar5_bc bit lengths (non-NULL).

Returns: ra8_err_t status.

Return values

k_ra8_ok The 20 lengths were read.

Precondition: st is a bound decoder state.; out holds k_ra8_rar5_bc writable bytes.

Postcondition: out[0 .. k_ra8_rar5_bc) are populated.; st->consumed advanced past the length list.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 335 of file ra8_rar5_tables.c.

References k_r5_len_escape, k_r5_zeros_extra, k_ra8_ok, k_ra8_rar5_bc, priv_rar5_fill_zeros(), priv_rar5_get(), and RA8_INTERNAL.

Referenced by priv_rar5_read_tables().

◆ internal_read_full_table()

ra8_err_t internal_read_full_table	(	ra8_rar5_state_t *	st,
		uint8_t *	tbl )

static

Decode the combined length table for the four LZ alphabets.

Reads k_ra8_rar5_huff_total bit lengths through the BD table: codes 0-15 are literal lengths, 16-19 are copy-previous / zero runs.

Parameters

[in,out]	st	Decoder state (non-NULL, ra8_rar5_state_t::bd built).
[out]	tbl	Receives the combined length table (non-NULL).

Returns: ra8_err_t status.

Return values

k_ra8_ok	The full table was decoded.
k_ra8_err_validation_failed	A run code without a previous entry.

Precondition: st::bd was built by internal_make_tables.; tbl holds k_ra8_rar5_huff_total writable bytes.

Postcondition: tbl[0 .. k_ra8_rar5_huff_total) are populated.; st->consumed advanced past the table.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 400 of file ra8_rar5_tables.c.

References k_ra8_ok, k_ra8_rar5_huff_total, priv_rar5_apply_run(), priv_rar5_decode_num(), and RA8_INTERNAL.

Referenced by priv_rar5_read_tables().

◆ internal_tab_limits()

void internal_tab_limits	(	ra8_rar5_dtab_t *	d,
		const uint32_t *	count )

static

Fill a decode table's per-length upper-limit and start-position arrays.

Turns a per-bit-length code count into the left-aligned upper-limit code (ra8_rar5_dtab_t::len) and the first-symbol index (ra8_rar5_dtab_t::pos) for each length, the canonical-Huffman prefix.

Parameters