Internal definitions, constants, SIMD helpers, and utility functions. More...

#include "zxc_deps.h"
#include "../../include/zxc_buffer.h"
#include "../../include/zxc_constants.h"
#include "../../include/zxc_error.h"
#include "../../include/zxc_seekable.h"
#include "rapidhash.h"
#include <stdatomic.h>

Data Structures
struct	zxc_pivco_tree_t
	A PivCo code tree: its canonical shape, by depth. More...

struct	zxc_dict_huf_state_t
	Frame-constant dictionary Huffman state, prebuilt once at attach. More...

struct	zxc_huf_pm_item_t
	Boundary package-merge work item. More...

struct	zxc_huf_pm_frame_t
	Trace-back stack frame for the package-merge code-length recovery. More...

struct	zxc_huf_pm_leaf_t
	A live symbol and its weight, the package-merge sort key. More...

struct	zxc_huf_nudge_ws_t
	Workspace of zxc_huf_nudge_code_lengths: tables and DP planes, once a 10 KiB frame and a per-block allocation. More...

struct	zxc_lz77_params_t
	Search parameters for LZ77 compression levels. More...

struct	zxc_gnr_header_t
	Header specific to General (LZ-based) compression blocks. More...

struct	zxc_cctx_t
	Compression / decompression context. More...

struct	zxc_block_header_t
	On-disk header structure for a ZXC block (8 bytes, little-endian). More...

struct	zxc_scan_src_s

struct	zxc_container_info_t
	What zxc_scan_container learns about a container. More...

struct	zxc_footer_layout_t
	Where a frame's footer lies, from what precedes it. More...

Macros
#define	ZXC_HUF_MIN_LITERALS 139
	Absolute floor (in literals) below which a Huffman candidate is never evaluated.

#define	ZXC_OPTS_DICT_SIZE(o) (((o) && (o)->dict) ? (o)->dict_size : (size_t)0)
	Dictionary length from a (possibly NULL) options struct.

#define	ZXC_OPTS_DICT_HUF(o) (((o) && (o)->dict && (o)->dict_size > 0) ? (const uint8_t*)(o)->dict_huf : NULL)
	Shared literal Huffman table, gated on `dict` the same way.

#define	ZXC_OPTS_LEVEL(o, dflt) zxc_level_clamp(((o) && (o)->level > 0) ? (o)->level : (dflt))
	Compression level, 0 meaning the default, clamped to the highest level the encoder implements.

#define	ZXC_OPTS_BLOCK_SIZE(o, dflt) (((o) && (o)->block_size > 0) ? (o)->block_size : (dflt))
	Block size, 0 meaning the default.

#define	ZXC_HUF_PM_LEVEL_BOUND (2 * ZXC_HUF_NUM_SYMBOLS)
	Per-level item bound: at most leaves + paired packages from the previous level.

#define	ZXC_HUF_BUILD_SCRATCH_SIZE
	Worst-case scratch size (bytes) for zxc_huf_build_code_lengths.

#define	ZXC_HUF_NUDGE_DP_M 64
	Slot-ledger DP bound, coarse symbols per plane axis; the nudge groups symbols to stay under it.

#define	ZXC_HUF_NUDGE_SCRATCH_OFF ZXC_ALIGN_CL(ZXC_HUF_BUILD_SCRATCH_SIZE)
	Offset of the zxc_huf_nudge_ws_t inside a nudge scratch.

#define	ZXC_HUF_NUDGE_SCRATCH_SIZE (ZXC_HUF_NUDGE_SCRATCH_OFF + sizeof(zxc_huf_nudge_ws_t))
	Scratch size (bytes) for zxc_huf_nudge_code_lengths: builder's, then workspace.

#define	ZXC_PIVCO_SCRATCH_PAD 32
	Extra scratch slack required past `n` by the PivCo decoder.

Atomic Qualifier
Provides a portable atomic / volatile qualifier. `ZXC_ATOMIC` expands to `_Atomic`, or to `volatile` where the compiler leaves out the optional C11 atomics (`__STDC_NO_ATOMICS__`, as MSVC does).
#define	ZXC_ATOMIC _Atomic

#define	ZXC_USE_C11_ATOMICS 1

Compiler Abstractions
Portable wrappers for branch hints, prefetch, memory ops, alignment, and forced inlining.
#define	LIKELY(x) (x)

#define	UNLIKELY(x) (x)

#define	RESTRICT

#define	ZXC_PREFETCH_READ(ptr)

#define	ZXC_MEMCPY(dst, src, n) memcpy(dst, src, n)

#define	ZXC_MEMSET(dst, val, n) memset(dst, val, n)

#define	ZXC_ALWAYS_INLINE inline
	Forces a function to be inlined (fallback for non-GCC/Clang/MSVC compilers).

#define	ZXC_NOINLINE
	Prevents inlining (best-effort no-op fallback for unknown compilers).

#define	ZXC_COLD

#define	ZXC_ALIGN(x) _Alignas(x)
	Specifies memory alignment using C11 _Alignas.

Endianness Detection
Compile-time detection of host byte order. Defines exactly one of `ZXC_LITTLE_ENDIAN` or `ZXC_BIG_ENDIAN`.
GLO Token Constants
4-bit literal length / 4-bit match length / 16-bit offset.
#define	ZXC_TOKEN_LIT_BITS 4
	Bits for Literal Length in a GLO token.

#define	ZXC_TOKEN_ML_BITS 4
	Bits for Match Length in a GLO token.

#define	ZXC_TOKEN_LL_MASK ((1U << ZXC_TOKEN_LIT_BITS) - 1)
	Mask to extract Literal Length from a GLO token.

#define	ZXC_TOKEN_ML_MASK ((1U << ZXC_TOKEN_ML_BITS) - 1)
	Mask to extract Match Length from a GLO token.

GHI Sequence Constants
8-bit literal length / 8-bit match length / 16-bit offset.
#define	ZXC_SEQ_LL_BITS 8
	Bits for Literal Length in a GHI sequence.

#define	ZXC_SEQ_ML_BITS 8
	Bits for Match Length in a GHI sequence.

#define	ZXC_SEQ_OFF_BITS 16
	Bits for Offset in a GHI sequence.

#define	ZXC_SEQ_LL_MASK ((1U << ZXC_SEQ_LL_BITS) - 1)
	Mask to extract Literal Length from a GHI sequence.

#define	ZXC_SEQ_ML_MASK ((1U << ZXC_SEQ_ML_BITS) - 1)
	Mask to extract Match Length from a GHI sequence.

#define	ZXC_SEQ_OFF_MASK ((1U << ZXC_SEQ_OFF_BITS) - 1)
	Mask to extract Offset from a GHI sequence.

Literal Stream Encoding
#define	ZXC_LIT_RLE_FLAG 0x80U
	Flag bit indicating an RLE run in the literal stream (0x80).

#define	ZXC_LIT_LEN_MASK (ZXC_LIT_RLE_FLAG - 1)
	Mask to extract the run/literal length (lower 7 bits).

Optimal Parser Tuning (level >= 6)
Static prices and complexity guards used by the level-6 optimal LZ77 parser DP.
#define	ZXC_OPT_MATCH_COST_BASE ((uint32_t)(3U * CHAR_BIT))
	Static price (bits) of a match token before varint extras: 1 byte token + 2 byte offset.

#define	ZXC_OPT_LONG_MATCH_SKIP ((size_t)256)
	Threshold above which `find_best_match` is skipped at intra-match positions, keeping the parser O(N) on highly repetitive data.

#define	ZXC_OPT_LIT_SAMPLE_MIN 1024
	Minimum literal count for the sample-based Huffman cost estimator used by the optimal parser.

Hash multipliers
Odd constants that mix bits in the LZ match hash, the header checksums (Sec 7.1) and the archive digest (Sec 7.3). The header-hash and digest values are fixed by the on-disk format; changing them is a version bump.
#define	ZXC_HASH_GOLDEN64 0x9E3779B97F4A7C15ULL
	Golden-ratio prime: header hashes and the digest spread.

#define	ZXC_HASH_XORSHIFT64 0x2545F4914F6CDD1DULL
	Vigna's xorshift* multiplier: the 5-byte LZ hash and the digest fold.

#define	ZXC_HASH_MULT32 0x2D35182DU
	Marsaglia 32-bit multiplier: the 4-byte LZ and dictionary hash.

#define	ZXC_HASH_MULT64 0xD2D84A61D2D84A61ULL
	Second multiplier of the 16-byte header hash (zxc_hash16).

Huffman Codec Constants
Length-limited canonical Huffman codec for GLO literal sections (level >= 6) and level-7 token sections, in the PivCo layout. On-disk section payload layout (FORMAT.md section 5.2.1): `ZXC_HUF_TABLE_SIZE` bytes: `ZXC_HUF_NUM_SYMBOLS` code lengths packed two per byte (4 bits each). The same packed table is used as the per-block lengths header (enc_lit=2) and as the shared table carried by a .zxd dictionary (enc_lit=3, header omitted) – hence the public constant. Node runs: for every emitting node of the canonical code tree in BFS order, its branch bits (or packed D-bit residuals for flat subtree roots), LSB-first, each run padded to a byte boundary. All run sizes are derived (root count + popcounts), never stored.
#define	ZXC_HUF_MAX_CODE_LEN_ULTRA 11
	Maximum Huffman code length, in bits: the ceiling the decoder's on-wire validation accepts (and the level-7 encoder cap).

#define	ZXC_HUF_MAX_CODE_LEN_DENSITY 8
	Encoder code-length cap for levels up to ZXC_LEVEL_DENSITY (below ZXC_LEVEL_ULTRA): shallow 8-bit trees decode fastest (fewer merge levels, denser flat subtrees) – this cap is the de-facto speed governor of level 6.

#define	ZXC_HUF_NUM_SYMBOLS 256
	Alphabet size: one entry per possible byte value.

#define	ZXC_PIVCO_MAX_NODES (2 * ZXC_HUF_NUM_SYMBOLS - 1)
	Upper bound on PivCo tree nodes (full binary tree over the alphabet).

#define	ZXC_PIVCO_NODE_SLOTS (ZXC_PIVCO_MAX_NODES + 1)
	Node-indexed array size: every node, plus a slot for the lone-symbol root's missing child.

#define	ZXC_PIVCO_UNPACK_FLAT_SIMD_MAX 6
	Deepest flat subtree zxc_pivco_unpack_flat unpacks with a SIMD kernel (its D == 2..6 cases); deeper flat roots take the scalar bit-reader.

#define	ZXC_PIVCO_COVERED 0xFFU
	`flat_d` of a node inside a flat root: no run, no children.

#define	ZXC_RLE_MARGIN_SHIFT 5
	RLE margin shift: source of the legacy below-ULTRA premium used by zxc_ss_prem_rle_q8 (256 >> shift reproduces the historical RLE-vs-RAW margin exactly).

#define	ZXC_HUF_MARGIN_SHIFT 5
	Huffman margin shift: source of the legacy below-ULTRA premium used by zxc_ss_prem_huf_q8 (the frozen ZXC_HUF_MIN_LITERALS floor was also historically derived from it).

Encoder-side joint flat/length nudge (PivCo decode-speed shaping)
Package-merge minimizes section bits alone, but the PivCo decoder's cost also depends on the SHAPE of the code-length histogram: the reconstruction pass loop runs `max_depth + 1` times, and every maximal complete subtree (all leaves exactly D levels below its root) collapses D merge levels into a single unpack. zxc_huf_nudge_code_lengths reshapes freshly built lengths toward power-of-two class counts and shallower caps, adopting a candidate only when its modeled decode win clears the guard below at a bounded ratio cost. Wire-compatible by construction: adjusted lengths stay canonical, Kraft-exact and within the level cap. Idea from pivco-huffman issue #20 (dougallj).
#define	ZXC_HUF_NUDGE_LAMBDA_Q8 26
	Exchange rate (Q8 bits per modeled level-touch) in the candidate cost `J = 256bits + lambdatouches`; 26 ~= 0.10 bit per touch.

#define	ZXC_HUF_NUDGE_BITS_PERMIL 1015
	Adoption guard, ratio side (permil): adopt only while ‘bits’ * 1000 <= bits0 * ZXC_HUF_NUDGE_BITS_PERMIL` (<= +1.5%).

#define	ZXC_HUF_NUDGE_MERGE_Q8 230
	Adoption guard, speed side (Q8): adopt only while ‘touches’ * 256 <= touches0 * ZXC_HUF_NUDGE_MERGE_Q8` (<= ~0.90x).

#define	ZXC_HUF_NUDGE_DEEP_FLAT_PENALTY 24
	Extra level-touches charged per occurrence under a flat root deeper than ZXC_PIVCO_UNPACK_FLAT_SIMD_MAX (scalar bit-reader unpack path).

#define	ZXC_HUF_NUDGE_LEVEL_COST 64
	Fixed per-pass overhead (occurrence-equivalents) charged per merge level, modeling the pass-loop and node-dispatch cost so shallower trees also win on small sections.

Typedefs
typedef struct zxc_scan_src_s	zxc_scan_src_t

Enumerations
enum	zxc_block_type_t { ZXC_BLOCK_RAW = 0 , ZXC_BLOCK_GLO = 1 , ZXC_BLOCK_GHI = 2 , ZXC_BLOCK_SEK = 254 , ZXC_BLOCK_EOF = 255 }
	Block types, i.e. More...

enum	zxc_section_encoding_t { ZXC_SECTION_ENCODING_RAW = 0 , ZXC_SECTION_ENCODING_RLE = 1 , ZXC_SECTION_ENCODING_HUFFMAN = 2 , ZXC_SECTION_ENCODING_HUFFMAN_DICT = 3 }
	Specifies the encoding methods used for internal data sections. More...

Functions
static int	zxc_level_clamp (const int level)
	Clamps a resolved compression level to the supported ceiling.

static int	zxc_huf_enc_max_code_len (const int level)
	Encoder Huffman code-length cap for a compression `level:` levels below ZXC_LEVEL_ULTRA use ZXC_HUF_MAX_CODE_LEN_DENSITY, ZXC_LEVEL_ULTRA uses the full ZXC_HUF_MAX_CODE_LEN_ULTRA ceiling (denser codes, slower decode).

static void	zxc_opt_dp_sizes (const size_t chunk_size, size_t sz_dp, size_t sz_pl, size_t sz_po, size_t sz_bm)
	The four DP partitions the optimal parser carves out of opt_scratch.

static zxc_lz77_params_t	zxc_get_lz77_params (const int level)
	Retrieves LZ77 compression parameters based on the specified compression level.

static uint16_t	zxc_le16 (const void *p)
	Reads a little-endian 16-bit value from a possibly unaligned address.

static uint32_t	zxc_le32 (const void *p)
	Reads a little-endian 32-bit value from a possibly unaligned address.

static int	zxc_block_is_short_dist_bound (const uint8_t *const blk, const size_t size)
	Reports whether a block leans on back-references shorter than ZXC_LZ_MINDIST.

static uint64_t	zxc_le64 (const void *p)
	Reads a little-endian 64-bit value from a possibly unaligned address.

static void	zxc_store_le16 (void *p, const uint16_t v)
	Writes a 16-bit value little-endian to a possibly unaligned address.

static void	zxc_store_le32 (void *p, const uint32_t v)
	Writes a 32-bit value little-endian to a possibly unaligned address.

static void	zxc_store_le64 (void *p, const uint64_t v)
	Writes a 64-bit value little-endian to a possibly unaligned address.

static uint8_t	zxc_hash8 (const uint8_t *p)
	Computes the 1-byte checksum for block headers.

static uint16_t	zxc_hash16 (const uint8_t *p)
	Computes the 2-byte checksum for file and dictionary headers.

static void	zxc_file_header_sign (uint8_t *h)
	Writes the file header checksum (bytes 14-15) over the other 14 bytes.

static void	zxc_copy16 (void dst, const void src)
	Copies exactly 16 bytes as one vector move where the ISA has one.

static void	zxc_copy32 (void dst, const void src)
	Copies 32 bytes from source to destination using SIMD when available.

static int	zxc_ctz32 (const uint32_t x)
	Counts trailing zeros, returning 32 for a zero input.

static int	zxc_ctz64 (const uint64_t x)
	Counts trailing zeros, returning 64 for a zero input.

static uint64_t	zxc_seek_block_count (const uint64_t total_decomp, const size_t block_size)
	Blocks in `total_decomp` bytes of `block_size:` the seek table's entry count, which the SEK header's field (table size modulo 2^32) cannot give.

static uint32_t	zxc_checksum (const void *input, const size_t len, const uint64_t seed, const uint8_t hash_method)
	Calculates a 32-bit hash for a given input buffer.

static uint64_t	zxc_digest_combine (const uint64_t acc, const uint32_t block_checksum)
	Folds a data block's 32-bit checksum into the running archive digest.

int	zxc_write_glo_header_and_desc (uint8_t dst, const size_t rem, const zxc_gnr_header_t gh, const uint32_t lit_comp, const uint32_t tok_comp)
	Writes a GLO sub-header followed by its section descriptors.

int	zxc_read_glo_header_and_desc (const uint8_t src, const size_t len, zxc_gnr_header_t gh, uint32_t lit_comp, uint32_t tok_comp)
	Reads a GLO sub-header and its section descriptors from a source buffer.

int	zxc_write_ghi_header (uint8_t dst, const size_t rem, const zxc_gnr_header_t gh)
	Writes a GHI sub-header.

int	zxc_read_ghi_header (const uint8_t src, const size_t len, zxc_gnr_header_t gh)
	Reads a GHI sub-header from a buffer.

int	zxc_huf_build_code_lengths (const uint32_t freq, uint8_t code_len, void *scratch, int max_code_len)
	Build length-limited canonical Huffman code lengths from a frequency table.

int	zxc_huf_nudge_code_lengths (const uint32_t freq, uint8_t code_len, void *scratch, size_t scratch_cap, int max_code_len)
	Optionally reshape freshly built code lengths for faster PivCo decode.

void	zxc_huf_nudge_cost (const uint8_t code_len, const uint32_t freq, uint64_t bits, uint64_t touches)
	Modeled (bits, level-touches) decode cost of one code-length vector.

void	zxc_huf_pack_lengths (const uint8_t code_len, uint8_t out)
	Pack per-symbol code lengths into the 128-byte (4-bit nibble) header.

int	zxc_huf_unpack_lengths (const uint8_t in, uint8_t code_len)
	Unpack and structurally validate a 128-byte packed lengths header.

size_t	zxc_huf_calc_size (const uint32_t freq, const uint8_t code_len, int with_header)
	Exact encoded size (bytes) of a PivCo section for this histogram and code lengths; includes the 128-byte lengths header when `with_header`.

int	zxc_huf_encode_section (const uint8_t literals, size_t n_literals, const uint32_t freq, const uint8_t code_len, uint8_t dst, size_t dst_cap)
	Encode a PivCo literal section (128-byte lengths header + payload).

int	zxc_huf_dict_tree_build (const uint8_t packed_lengths, zxc_pivco_tree_t tree, uint32_t codes, uint8_t code_len)
	Unpack a dict table's packed lengths and prebuild its tree, codes and code lengths, once per frame.

size_t	zxc_huf_calc_size_dict (const uint32_t freq, const uint8_t code_len, const zxc_pivco_tree_t *tree)
	zxc_huf_calc_size for a dict section: prebuilt `tree`, no header.

int	zxc_huf_encode_section_dict (const uint8_t literals, size_t n_literals, const uint32_t freq, const uint8_t code_len, const zxc_pivco_tree_t tree, const uint32_t codes, uint8_t dst, size_t dst_cap)
	Encode a PivCo section against a prebuilt dict tree/codes (no header).

int	zxc_huf_decode_section (const uint8_t payload, size_t payload_size, uint8_t dst, size_t n, uint8_t *scratch)
	Decode a PivCo literal section into `dst` (exactly `n` bytes).

int	zxc_huf_decode_section_dict (const uint8_t payload, size_t payload_size, uint8_t dst, size_t n, const zxc_pivco_tree_t tree, uint8_t scratch)
	Decode a PivCo dict section against a prebuilt dict `tree`.

int	zxc_cctx_init (zxc_cctx_t *ctx, const size_t chunk_size, const int mode, const int level, const int checksum_enabled, const size_t dict_size)
	Initialises a ZXC compression / decompression context in place.

int	zxc_cctx_attach_dict_huf (zxc_cctx_t ctx, const uint8_t lengths)
	Attach the shared dictionary literal table to an initialised context.

size_t	zxc_cctx_compute_workspace_size (const size_t chunk_size, const int mode, const int level, const size_t dict_size)
	Returns the byte count that zxc_cctx_init would allocate for the given parameters.

int	zxc_cctx_init_in_workspace (zxc_cctx_t ctx, void workspace, const size_t workspace_size, const size_t chunk_size, const int mode, const int level, const int checksum_enabled, const size_t dict_size, const int defer_entropy_scratch)
	Initialises a compression / decompression context inside a caller-supplied workspace.

int	zxc_cctx_alloc_entropy_scratch (zxc_cctx_t *ctx)
	Lazily allocates the decode-side entropy scratch (tok_buffer + pivco_scratch) for a heap context initialised with deferral.

void	zxc_cctx_free (zxc_cctx_t *ctx)
	Releases the internal buffers owned by a context.

int	zxc_decompress_chunk_wrapper (const zxc_cctx_t ctx, const uint8_t src, const size_t src_sz, uint8_t *dst, const size_t dst_cap, const uint64_t block_index)
	Decompresses one chunk through the runtime ISA dispatch.

int	zxc_decompress_chunk_wrapper_dict (const zxc_cctx_t ctx, const uint8_t src, const size_t src_sz, uint8_t *dst, const size_t dst_cap, const uint64_t block_index)
	Public dictionary chunk decoder.

int	zxc_decompress_chunk_wrapper_safe (const zxc_cctx_t ctx, const uint8_t src, const size_t src_sz, uint8_t *dst, const size_t dst_cap, const uint64_t block_index)
	Exact-capacity variant for the safe block API; dispatch table only.

int	zxc_compress_chunk_wrapper (zxc_cctx_t ctx, const uint8_t src, const size_t src_sz, uint8_t *dst, const size_t dst_cap, const uint64_t block_index)
	Compresses one chunk through the runtime ISA dispatch.

int64_t	zxc_compress_block_at (zxc_cctx cctx, const void src, size_t src_size, void dst, size_t dst_capacity, const zxc_compress_opts_t opts, uint64_t block_index)
	zxc_compress_block, its checksum seeded with `block_index` (public entry: 0).

int	zxc_write_file_header (uint8_t *dst, const size_t dst_capacity, const size_t chunk_size, const int has_checksum, const uint32_t dict_id, const int has_seek)
	Writes the standard ZXC file header into `dst`.

int	zxc_read_file_header (const uint8_t src, const size_t src_size, size_t out_block_size, int out_has_checksum, uint32_t out_dict_id, int *out_has_seek)
	Validates and reads the ZXC file header from `src`.

static int	zxc_short_input_verdict (const uint8_t *p, const size_t n)
	The verdict on `n` bytes too short for a frame: the header speaks first, then ZXC_ERROR_SRC_TOO_SMALL.

static zxc_scan_src_t	zxc_scan_src_mem (const uint8_t *data, const size_t size)
	A scan source over `size` bytes of memory at `data`.

int	zxc_container_next (const zxc_scan_src_t *src, uint64_t pos)
	Tells whether a frame starts at `pos`.

int	zxc_scan_frame (const zxc_scan_src_t src, uint64_t end, uint64_t start, zxc_frame_info_t info, size_t footer_len)
	Measures the frame ending at `end` without decoding: its footer's compressed size gives where it starts.

int	zxc_scan_whole_frame (const zxc_scan_src_t src, zxc_frame_info_t info, size_t *footer_len)
	The frame that must span all of `src:` zxc_get_frame_info() and its FILE* twin.

int	zxc_scan_container (const zxc_scan_src_t src, size_t req_chunk, zxc_container_info_t info)
	Measures a whole container without decoding: frames from the last back to the first through zxc_scan_frame.

int	zxc_write_block_header (uint8_t dst, const size_t dst_capacity, const zxc_block_header_t bh)
	Encodes a block header into `dst`.

int	zxc_read_block_header (const uint8_t src, const size_t src_size, zxc_block_header_t bh)
	Reads and parses a ZXC block header from `src`.

static int	zxc_footer_dsize_plausible (const uint64_t dsize, const size_t chunk_size, const uint64_t comp_size)
	Whether a footer's decompressed size is reachable for this archive.

int	zxc_seek_table_header (uint8_t *dst, size_t dst_capacity, uint64_t num_blocks)
	Writes a seek table's block header for `num_blocks` entries.

int	zxc_check_eof_header (const uint8_t *hdr)
	Checks an EOF block header against its one valid form: type 255, every other field zero, and its header checksum.

int	zxc_check_seek_header (const uint8_t hdr, size_t avail, uint64_t total_out, size_t block_size, uint64_t sek_bytes)
	Checks the SEK block header the file header announced, on the `avail` bytes present.

void	zxc_seekable_attach_owned_ctx (zxc_seekable s, void ctx)
	Hands ownership of a heap-allocated reader context to a seekable handle.

size_t	zxc_seek_write_group (uint8_t dst, uint64_t anchor, const uint32_t *sizes, uint32_t cnt)
	Writes one group (`anchor`, then `cnt` sizes) into `dst`, which holds ZXC_SEEK_GROUP_BYTES, and advances `anchor` past its blocks.

Block Size Helpers
Runtime helpers for variable block sizes.
static uint32_t	zxc_log2_u32 (const uint32_t v)
	Integer log-base-2 for a 32-bit value.

static size_t	zxc_block_size_ceil (const size_t v)
	Branchless bit_ceil: smallest power of two >= v, clamped to ZXC_BLOCK_SIZE_MIN.

static int	zxc_validate_block_size (const size_t bs)
	Validates a block size.

File Format Constants
Header fields, block sizes, and related constants. The magic words are public, in zxc_constants.h.
#define	ZXC_FILE_FORMAT_VERSION 9
	Current on-disk file format version.

#define	ZXC_PAD_SIZE 32
	Safety padding appended to buffers to tolerate overruns.

#define	ZXC_BLOCK_LIT_SLACK 32
	Readable bytes a GLO/GHI payload guarantees after its literal section.

#define	ZXC_DECOMPRESS_TAIL_PAD (ZXC_PAD_SIZE * 66)
	Tail padding required on the decompression destination buffer.

#define	ZXC_CACHE_LINE_SIZE 64
	Assumed CPU cache line size for alignment.

#define	ZXC_ALIGNMENT_MASK ((size_t)ZXC_CACHE_LINE_SIZE - 1)
	Bitmask for cache-line alignment checks.

#define	ZXC_ALIGN_CL(x) (((x) + ZXC_ALIGNMENT_MASK) & ~(size_t)ZXC_ALIGNMENT_MASK)
	Round `x` up to the next cache-line boundary.

#define	ZXC_BITMAP_WORDS(n_bits) (((n_bits) + 63) / 64)
	Number of `uint64_t` words needed to hold a bitmap of `n_bits`.

#define	ZXC_FILE_FLAG_HAS_CHECKSUM 0x80U
	Bit flag in the Flags byte indicating checksum presence (bit 7).

#define	ZXC_FILE_FLAG_HAS_DICTIONARY 0x40U
	Bit flag in the Flags byte indicating a dictionary is required (bit 6).

#define	ZXC_FILE_FLAG_HAS_SEEK_TABLE 0x20U
	Bit flag in the Flags byte: a SEK block sits between the EOF block and the footer (bit 5).

#define	ZXC_FILE_CHECKSUM_ALGO_MASK 0x0FU
	Mask for the checksum algorithm id (bits 0-3).

#define	ZXC_DICT_VERSION 2
	Current dictionary file format version.

#define	ZXC_DICT_KGRAM_LEN ZXC_LZ_MIN_MATCH_LEN
	K-gram length scanned by the dictionary trainer.

#define	ZXC_DICT_HASH_BITS 16
	Address bits for the dictionary trainer's k-gram frequency table.

#define	ZXC_DICT_MAX_SEGMENTS (1U << 16)
	Maximum number of candidate segments the dictionary trainer keeps.

#define	ZXC_DICT_SAMPLE_TARGET (1U << 19)
	Target number of sampled k-gram positions for the trainer's frequency estimate.

#define	ZXC_DICT_HASH_SIZE (1U << ZXC_DICT_HASH_BITS)
	Number of buckets in the dictionary trainer's frequency table.

#define	ZXC_DICT_HUF_TRAIN_BLOCK 4096U
	Training block size for the shared-table literal statistics.

#define	ZXC_DICT_HUF_SAMPLE_BUDGET (8U << 20)
	Cap on the corpus bytes compressed by the literal-table trainer: the histogram converges early, so past it slices are strided evenly instead.

#define	ZXC_BLOCK_HEADER_SIZE 8
	Block header size: Type(1)+Flags(1)+Reserved(1)+Checksum(1)+CompSize(4).

#define	ZXC_BLOCK_CHECKSUM_SIZE 4
	Size of the per-block checksum field in bytes.

#define	ZXC_GLO_HEADER_BINARY_SIZE 12
	Binary size of a GLO block sub-header.

#define	ZXC_GHI_HEADER_BINARY_SIZE 12
	Binary size of a GHI block sub-header.

#define	ZXC_GLO_DESC_MAX_SIZE (2 * sizeof(uint32_t))
	Widest GLO section descriptors: the literal and token section sizes.

#define	ZXC_BLOCK_FORMAT_OVERHEAD 68
	Worst-case format overhead inside a single block beyond the outer 8-byte block header and the optional 4-byte checksum.

#define	ZXC_CHECKSUM_RAPIDHASH 0
	Checksum algorithm id for RapidHash (default, sole implementation).

static int	zxc_magic_prefix_ok (const uint8_t *p, const size_t n)
	Whether the first `n` bytes (up to 4) at `p` agree with the magic word, so a frame may start there: the check a reader makes as bytes arrive.

Seekable Format Constants
Seek table block appended between EOF block and footer. Optional: a `ZXC_BLOCK_SEK` block of groups, each a u64 anchor (its first block's offset) then one u32 on-disk size per block. Readers derive the block count from the footer and read groups on access; the header's size field holds the table size modulo 2^32.
#define	ZXC_SEEK_GROUP 64U
	Blocks per group.

#define	ZXC_SEEK_ANCHOR_SIZE 8U
	Group anchor: offset of its first block, u64.

#define	ZXC_SEEK_SIZE_ENTRY 4U
	One block's on-disk size, u32.

#define	ZXC_SEEK_GROUP_BYTES (ZXC_SEEK_ANCHOR_SIZE + ZXC_SEEK_GROUP * ZXC_SEEK_SIZE_ENTRY)
	Full group: anchor + ZXC_SEEK_GROUP sizes.

static uint64_t	zxc_seek_group_count (const uint64_t nblocks)
	Groups holding `nblocks` blocks; the last one may be partial.

static uint32_t	zxc_seek_group_len (const uint64_t nblocks, const uint64_t g)
	Blocks in group `g` of `nblocks:` ZXC_SEEK_GROUP, fewer for the last.

static uint64_t	zxc_seek_table_bytes (const uint64_t nblocks)
	Byte size of the groups for `nblocks` blocks, in 64 bits.

static uint32_t	zxc_seek_size_field (const uint64_t table_bytes)
	SEK header size field: `table_bytes` with its high half folded onto the low one.

LZ77 Constants
Hash table geometry, sliding window, and match parameters. The hash table uses a split layout with 15-bit addressing (32 768 buckets): `hash_table[]`: uint32_t, stores `(epoch << offset_bits) \| position` (128 KB). `hash_tags[]`: uint8_t, stores an 8-bit tag for fast rejection (32 KB). Total: 160 KB. The tag table fits in L1 cache, enabling a "filter-first" access pattern that avoids cold loads into hash_table on the ~60-75% of lookups where the tag mismatches. The 64 KB sliding window allows `chain_table` to use `uint16_t`.
#define	ZXC_LZ_HASH_BITS 15
	Address bits for the LZ77 hash table (2^15 = 32 768 buckets).

#define	ZXC_LZ_HASH_SIZE (1U << ZXC_LZ_HASH_BITS)
	Maximum number of entries in the hash table.

#define	ZXC_LZ_WINDOW_SIZE (1U << 16)
	Sliding window size (64 KB).

#define	ZXC_LZ_WINDOW_MASK (ZXC_LZ_WINDOW_SIZE - 1U)
	Mask for ring-buffer indexing into chain_table (power-of-two window).

#define	ZXC_LZ_MIN_MATCH_LEN 5
	Minimum match length for an LZ77 match.

#define	ZXC_MAX_VARINT_VALUE ((uint32_t)(ZXC_BLOCK_SIZE_MAX - 1U))
	Maximum legitimate value a varint can decode to.

#define	ZXC_GLO_MAX_INLINE_OUT_PER_SEQ ((ZXC_TOKEN_LL_MASK - 1U) + ZXC_GLO_MAX_INLINE_ML) /* 33 */
	Maximum decoded output of one sequence with inline ll/ml, used by the 4x bounds checks to reserve the rest of a batch.

#define	ZXC_GLO_INLINE_ML_CODE (ZXC_TOKEN_ML_MASK - 1U) /* 14 */
	Longest match length code (length minus ZXC_LZ_MIN_MATCH_LEN) a GLO token carries inline; the code above it escapes to a varint.

#define	ZXC_GLO_MAX_INLINE_ML (ZXC_GLO_INLINE_ML_CODE + ZXC_LZ_MIN_MATCH_LEN) /* 19 */
	Longest match a GLO sequence carries without a varint extension.

#define	ZXC_GHI_MAX_INLINE_OUT_PER_SEQ ((ZXC_SEQ_LL_MASK - 1U) + (ZXC_SEQ_ML_MASK - 1U) + ZXC_LZ_MIN_MATCH_LEN) /* 513 */

#define	ZXC_LZ_OFFSET_BIAS 1
	Base bias added to encoded offsets (stored = actual - bias).

#define	ZXC_LZ_MAX_DIST (ZXC_LZ_WINDOW_SIZE - 1)
	Maximum allowed offset distance.

#define	ZXC_LZ_MINDIST 32
	Match distance floor the encoder holds to at levels 1 to 5, sized to the decoder's widest match-copy arm so the overlap kernel stays off the decode path.

#define	ZXC_LZ_MINDIST_PROBE_PER_KB 1024
	Probe sampling: one position per KB, clamped.

#define	ZXC_LZ_MINDIST_PROBE_MIN 16

#define	ZXC_LZ_MINDIST_PROBE_MAX 64

#define	ZXC_LZ_MINDIST_MAX_SHORT_PCT 20
	Short-distance hit rate, in percent, above which a block keeps its short match distances.

#define	ZXC_LZ_SEARCH_MARGIN (sizeof(uint64_t))
	Bytes at the block end where match search stops (left as literals).

static uint32_t	zxc_read_varint (const uint8_t *ptr, const uint8_t end)
	Reads a Prefix Varint encoded integer.

Space-speed section selection
Section encodings are selected at EVERY level by pricing each candidate with a Lagrangian cost `J = compressed_size + decode_tax` and taking the minimum (Kraken-style `J = R + lambdaD` with a linear per-byte decode-time model). The tax charges the DECODE time a candidate adds over the RAW copy path, expressed in bytes: `tax = (n_decoded_bytes PREM) >> 8`. Only the premium is per-level: Below DENSITY, the premiums reproduce the historical fixed margins EXACTLY (8 = 3.125% = the old `>> 5` margins), keeping the sub-DENSITY levels (1-5) output byte-stable. At DENSITY and above the physical premiums apply: `PREM_HUF = 4` (1.56% – the entropy decoder costs ~0.5 ns/B over a raw copy, so ~1 byte of size buys ~30 ns of decode; validated on silesia: ~0.8 pt of ratio for ~3% decode vs the legacy margin) and `PREM_RLE = 1` (0.39%: RLE decodes at near copy speed, only a token tax to break ties toward RAW).
#define	ZXC_SS_TAX(n, prem_q8) (((size_t)(n) * (size_t)(prem_q8)) >> 8)
	Decode tax of a candidate: `n` decoded bytes at premium `prem` (Q8).

static int	zxc_ss_prem_rle_q8 (const int level)
	Per-level RLE-vs-RAW decode premium (Q8) for the space-speed selector.

static int	zxc_ss_prem_huf_q8 (const int level)
	Per-level Huffman/PivCo-vs-RAW decode premium (Q8) for the space-speed selector.

Per-block match splitting (zxc_glo_split_block), a level-table policy
Escaped matches up to split_max (a length code; 14 is the inline reach) go out as inline pieces at the same offset, so the decoder skips its ML escape. Two gates: the block's escape branch must look mispredicted, then only the escapes of mispredicted contexts split; a predictable one would only add sequences. A split_max at or below the inline reach (levels 1, 2, 6, 7 in the level table) turns the pass off.
#define	ZXC_GLO_SPLIT_CTX_BITS 8
	Longest escape history a context keys on; small blocks shorten it (down to 2 bits) towards 16 samples per context.

#define	ZXC_GLO_SPLIT_MIN_MISPREDICT_PCT 80
	Mispredict rate, in percent of a block's escapes, from which the block is split.

typedef uint32_t	zxc_glo_split_hist_t[4][2][1U<< 8]
	zxc_glo_split_analyze's escape histograms: four rotating lanes of [escape][context] counts, carved from the compression workspace.

File footer
`[digest(8), with checksums] \| original_size \| compressed_size \| L` (FORMAT.md Sec 8). Sizes on the fewest little-endian bytes (1 to 8); L = (nd - 1) \| (nf - 1) << 4 gives their lengths, so the footer parses back from the end without the header. A sequential reader computes the one valid footer and compares.
#define	ZXC_FOOTER_MAX_SIZE_WITH_DIGEST (ZXC_FILE_DIGEST_SIZE + ZXC_FILE_FOOTER_MAX_SIZE)
	Most bytes a footer spans: the digest and the two longest sizes.

#define	ZXC_FRAME_MIN_SIZE (ZXC_FILE_HEADER_SIZE + ZXC_BLOCK_HEADER_SIZE + ZXC_FILE_FOOTER_MIN_SIZE)
	Smallest frame: header, the EOF block and the shortest footer.

static size_t	zxc_uint_bytes (const uint64_t v)
	Fewest little-endian bytes, 1 to 8, that hold `v`.

static zxc_footer_layout_t	zxc_footer_layout (const uint64_t prefix, const uint64_t src_size, const int checksum_enabled)
	The footer of a frame whose first `prefix` bytes precede it.

int	zxc_write_file_footer (uint8_t *dst, const size_t dst_capacity, const uint64_t prefix, const uint64_t src_size, const uint64_t digest, const int checksum_enabled)
	Writes the footer of a frame whose first `prefix` bytes precede it.

int	zxc_check_file_footer (const uint8_t footer, size_t avail, const zxc_footer_layout_t l, uint64_t src_size, uint64_t *digest)
	Checks the footer a sequential reader reaches against `l`, the one the frame implies, on the `avail` bytes it has.

int	zxc_parse_file_footer (const uint8_t end, size_t avail, uint64_t src_size, uint64_t compressed_size, size_t sizes_len)
	Parses the sizes back from the end of a frame.

static size_t	zxc_frame_tail_len (const uint64_t total)
	Bytes zxc_read_frame_info() takes from the end of `total` bytes (at least ZXC_FRAME_MIN_SIZE): all of them past the header and EOF block, up to ZXC_FOOTER_MAX_SIZE_WITH_DIGEST.

int	zxc_read_frame_info (const uint8_t header, const uint8_t tail, size_t tail_len, uint64_t total, zxc_frame_info_t info, size_t footer_len)
	Validates a frame from its header and the end of its bytes: the one check behind zxc_get_frame_info(), its FILE* twin and the size queries.

static void	zxc_frame_info_copy (zxc_frame_info_t info, const size_t info_size, const zxc_frame_info_t got)
	Copies the fields of `got` that fit the caller's `info_size` bytes.

Detailed Description

Internal definitions, constants, SIMD helpers, and utility functions.

This header is not part of the public API. It is shared across the library's translation units and contains:

Platform detection and SIMD intrinsic includes.
Compiler-abstraction macros (LIKELY, PREFETCH, MEMCPY, ALIGN, ...).
Endianness detection and byte-swap helpers.
File-format constants (magic word, header sizes, block sizes, ...).
Inline helpers for hashing, endian-safe loads/stores, bit manipulation, aligned allocation, and bitstream reading.
Internal function prototypes for chunk-level compression/decompression.

Warning: Do not include this header from user code; use the public headers zxc_buffer.h or zxc_stream.h instead.

Definition in file zxc_internal.h.

Macro Definition Documentation

◆ ZXC_FOOTER_MAX_SIZE_WITH_DIGEST

#define ZXC_FOOTER_MAX_SIZE_WITH_DIGEST (ZXC_FILE_DIGEST_SIZE + ZXC_FILE_FOOTER_MAX_SIZE)

Most bytes a footer spans: the digest and the two longest sizes.

Definition at line 2382 of file zxc_internal.h.

◆ ZXC_FRAME_MIN_SIZE

#define ZXC_FRAME_MIN_SIZE (ZXC_FILE_HEADER_SIZE + ZXC_BLOCK_HEADER_SIZE + ZXC_FILE_FOOTER_MIN_SIZE)

Smallest frame: header, the EOF block and the shortest footer.

Definition at line 2385 of file zxc_internal.h.

◆ ZXC_GLO_SPLIT_CTX_BITS

#define ZXC_GLO_SPLIT_CTX_BITS 8

Longest escape history a context keys on; small blocks shorten it (down to 2 bits) towards 16 samples per context.

Sizes the histograms.

Definition at line 950 of file zxc_internal.h.

◆ ZXC_GLO_SPLIT_MIN_MISPREDICT_PCT

#define ZXC_GLO_SPLIT_MIN_MISPREDICT_PCT 80

Mispredict rate, in percent of a block's escapes, from which the block is split.

Definition at line 953 of file zxc_internal.h.

◆ ZXC_HUF_BUILD_SCRATCH_SIZE

#define ZXC_HUF_BUILD_SCRATCH_SIZE

Value:

    ((size_t)ZXC_HUF_MAX_CODE_LEN_ULTRA * (size_t)ZXC_HUF_PM_LEVEL_BOUND * \
         sizeof(zxc_huf_pm_item_t) +                                       \
     8U + (size_t)ZXC_HUF_MAX_CODE_LEN_ULTRA * sizeof(int) + 8U +          \
     (size_t)ZXC_HUF_MAX_CODE_LEN_ULTRA * (size_t)ZXC_HUF_PM_LEVEL_BOUND * \
         sizeof(zxc_huf_pm_frame_t))

Worst-case scratch size (bytes) for zxc_huf_build_code_lengths.

Carved by the function into items / counts / stack regions; sized for the worst-case alphabet (n = ZXC_HUF_NUM_SYMBOLS). Includes a small alignment slack between regions.

Definition at line 1002 of file zxc_internal.h.

◆ ZXC_HUF_NUDGE_DP_M

#define ZXC_HUF_NUDGE_DP_M 64

Slot-ledger DP bound, coarse symbols per plane axis; the nudge groups symbols to stay under it.

Definition at line 1011 of file zxc_internal.h.

◆ ZXC_HUF_NUDGE_SCRATCH_OFF

#define ZXC_HUF_NUDGE_SCRATCH_OFF ZXC_ALIGN_CL(ZXC_HUF_BUILD_SCRATCH_SIZE)

Offset of the zxc_huf_nudge_ws_t inside a nudge scratch.

Definition at line 1031 of file zxc_internal.h.

◆ ZXC_HUF_NUDGE_SCRATCH_SIZE

#define ZXC_HUF_NUDGE_SCRATCH_SIZE (ZXC_HUF_NUDGE_SCRATCH_OFF + sizeof(zxc_huf_nudge_ws_t))

Scratch size (bytes) for zxc_huf_nudge_code_lengths: builder's, then workspace.

Definition at line 1033 of file zxc_internal.h.

◆ ZXC_HUF_PM_LEVEL_BOUND

#define ZXC_HUF_PM_LEVEL_BOUND (2 * ZXC_HUF_NUM_SYMBOLS)

Per-level item bound: at most leaves + paired packages from the previous level.

Definition at line 996 of file zxc_internal.h.

◆ ZXC_OPTS_BLOCK_SIZE

#define ZXC_OPTS_BLOCK_SIZE	(	o,
		dflt
	)	(((o) && (o)->block_size > 0) ? (o)->block_size : (dflt))

Block size, 0 meaning the default.

Definition at line 938 of file zxc_internal.h.

◆ ZXC_OPTS_DICT_HUF

#define ZXC_OPTS_DICT_HUF ( o ) (((o) && (o)->dict && (o)->dict_size > 0) ? (const uint8_t*)(o)->dict_huf : NULL)

Shared literal Huffman table, gated on dict the same way.

Definition at line 932 of file zxc_internal.h.

◆ ZXC_OPTS_DICT_SIZE

#define ZXC_OPTS_DICT_SIZE ( o ) (((o) && (o)->dict) ? (o)->dict_size : (size_t)0)

Dictionary length from a (possibly NULL) options struct.

Gated on dict itself: no dictionary pointer means no dictionary, whatever the sibling fields hold. Macros rather than functions because the compression and decompression option structs carry these fields without sharing a type.

Definition at line 930 of file zxc_internal.h.

◆ ZXC_OPTS_LEVEL

#define ZXC_OPTS_LEVEL	(	o,
		dflt
	)	zxc_level_clamp(((o) && (o)->level > 0) ? (o)->level : (dflt))

Compression level, 0 meaning the default, clamped to the highest level the encoder implements.

Definition at line 936 of file zxc_internal.h.

◆ ZXC_PIVCO_SCRATCH_PAD

#define ZXC_PIVCO_SCRATCH_PAD 32

Extra scratch slack required past n by the PivCo decoder.

Definition at line 1821 of file zxc_internal.h.

Typedef Documentation

◆ zxc_glo_split_hist_t

typedef uint32_t zxc_glo_split_hist_t[4][2][1U<< 8]

zxc_glo_split_analyze's escape histograms: four rotating lanes of [escape][context] counts, carved from the compression workspace.

Definition at line 956 of file zxc_internal.h.

Enumeration Type Documentation

◆ zxc_block_type_t

enum zxc_block_type_t

Block types, i.e.

which encoder produced a block's payload.

ZXC_BLOCK_RAW (0): stored as-is. Used when the data is incompressible or when compressing it would make the block bigger.
ZXC_BLOCK_GLO (1): the general path, LZ77 plus bitpacked sequences, levels 3 and up. Carries 0, 4 or 8 bytes of section descriptors depending on which streams need an explicit compressed size.
ZXC_BLOCK_GHI (2): the speed path, levels 1 and 2. Fixed 4-byte sequence records and always-RAW literals make every section size derivable from the header, so it carries no descriptor at all.
ZXC_BLOCK_SEK (254): seek table, groups of 64 blocks (u64 anchor, u32 sizes). Sits between the EOF block and the file footer.
ZXC_BLOCK_EOF (255): end-of-file marker.

Definition at line 1198 of file zxc_internal.h.

◆ zxc_section_encoding_t

enum zxc_section_encoding_t

Specifies the encoding methods used for internal data sections.

These modes determine how specific components (like literals, match lengths, or offsets) are stored within a block.

ZXC_SECTION_ENCODING_RAW: Data is stored uncompressed.
ZXC_SECTION_ENCODING_RLE: Run-Length Encoding.
ZXC_SECTION_ENCODING_HUFFMAN: canonical Huffman in the PivCo layout (level-ordered branch runs, max 11-bit codes – FORMAT.md section 5.2.1). Valid for the literal stream (enc_lit, level >= 6) and the token stream (enc_tok, level 7) of GLO blocks.
ZXC_SECTION_ENCODING_HUFFMAN_DICT: same payload as HUFFMAN but the 128-byte code-lengths header is omitted: codes come from the shared table carried by the dictionary (.zxd). Only valid for enc_lit of GLO blocks in dictionary-compressed archives; requires the same dictionary (content + table, bound by dict_id) at decode time.

Definition at line 1224 of file zxc_internal.h.

Function Documentation

◆ zxc_block_is_short_dist_bound()

static int zxc_block_is_short_dist_bound	(	const uint8_t *const	blk,
		const size_t	size
	)

inlinestatic

Reports whether a block leans on back-references shorter than ZXC_LZ_MINDIST.

Asks one question per sampled position: is there a 4-byte repeat inside the distance the floor would forbid? Blocks that answer yes often – periodic runs, JSON keys, XML tags – lose size and decode time under it.

Parameters

[in]	blk	Block payload, past any dictionary prefix.
[in]	size	Payload size in bytes.

Returns: 1 when the block must keep its short distances, 0 when the floor is safe.

Definition at line 1320 of file zxc_internal.h.

References zxc_le32(), ZXC_LZ_MINDIST, ZXC_LZ_MINDIST_MAX_SHORT_PCT, and ZXC_LZ_MINDIST_PROBE_PER_KB.

Referenced by zxc_encode_block_ghi(), and zxc_encode_block_glo().

◆ zxc_block_size_ceil()

static size_t zxc_block_size_ceil ( const size_t v )

inlinestatic

Branchless bit_ceil: smallest power of two >= v, clamped to ZXC_BLOCK_SIZE_MIN.

Parameters

[in] v Input size (must be > 0).

Returns: Smallest power of two >= v, clamped up to ZXC_BLOCK_SIZE_MIN.

Definition at line 1073 of file zxc_internal.h.

References ZXC_BLOCK_SIZE_MIN.

Referenced by zxc_compress(), zxc_compress_block_at(), zxc_compress_cctx(), zxc_decompress_block(), zxc_decompress_block_safe(), zxc_estimate_cctx_size(), zxc_stream_worker(), and zxc_train_dict_huf().

◆ zxc_cctx_alloc_entropy_scratch()

int zxc_cctx_alloc_entropy_scratch ( zxc_cctx_t * ctx )

Lazily allocates the decode-side entropy scratch (tok_buffer + pivco_scratch) for a heap context initialised with deferral.

No-op when the scratch is already present (static workspaces pre-carve it; subsequent entropy blocks reuse the first allocation). The block is owned by the context (entropy_block) and released by zxc_cctx_free.

Returns: ZXC_OK, or ZXC_ERROR_MEMORY on allocation failure.

Lazily allocates the decode-side entropy scratch (tok_buffer + pivco_scratch) for a heap context initialised with deferral.

Public contract at the declaration in zxc_internal.h. One aligned block carries [tok_buffer | pivco_scratch], sized by zxc_dctx_entropy_sizes (the same source the full-provision layout uses), owned by the context and released by zxc_cctx_free.

Definition at line 373 of file zxc_common.c.

References zxc_cctx_t::entropy_block, zxc_cctx_t::pivco_scratch, zxc_cctx_t::pivco_scratch_cap, zxc_cctx_t::tok_buffer, zxc_cctx_t::tok_buffer_cap, zxc_cctx_t::work_buf_cap, ZXC_ALIGN_CL, ZXC_ALIGNED_MALLOC, ZXC_CACHE_LINE_SIZE, zxc_dctx_entropy_sizes(), ZXC_DECOMPRESS_TAIL_PAD, ZXC_ERROR_MEMORY, and ZXC_OK.

◆ zxc_cctx_attach_dict_huf()

int zxc_cctx_attach_dict_huf	(	zxc_cctx_t *	ctx,
		const uint8_t *	lengths
	)

Attach the shared dictionary literal table to an initialised context.

Validates the 128-byte packed code-lengths header and builds the PivCo tree and codes once into the context, for every block to reuse. lengths need only be valid during this call (everything is copied into the context workspace). A NULL lengths is a no-op.

Returns: ZXC_OK on success, ZXC_ERROR_CORRUPT_DATA if the lengths header is structurally invalid (bad nibble, Kraft inequality).

Attach the shared dictionary literal table to an initialised context.

Validates the 128-byte packed code-lengths header and builds the dictionary's PivCo tree, canonical codes and code lengths ONCE into the context (tree-at-attach); per-block encode/estimate/decode reuse them. lengths need only be valid during this call (the tree is a copy). A NULL lengths is a no-op.

Parameters

[in,out]	ctx	Initialised context to attach the table to.
[in]	lengths	128-byte packed code lengths, or NULL for a no-op.

Returns: ZXC_OK on success, ZXC_ERROR_CORRUPT_DATA if lengths is structurally invalid (bad nibble, Kraft inequality).

Definition at line 453 of file zxc_common.c.

References ZXC_ERROR_NULL_INPUT, zxc_huf_dict_tree_build(), ZXC_HUF_TABLE_SIZE, and ZXC_OK.

Referenced by zxc_compress(), zxc_ctx_sync_dict_huf(), zxc_seek_use_dict(), and zxc_stream_worker().

◆ zxc_cctx_compute_workspace_size()

size_t zxc_cctx_compute_workspace_size	(	const size_t	chunk_size,
		const int	mode,
		const int	level,
		const size_t	dict_size
	)

Returns the byte count that zxc_cctx_init would allocate for the given parameters.

Used by the static-cctx public API to size a caller-supplied workspace before calling zxc_cctx_init_in_workspace.

Parameters

[in]	chunk_size	Block size in bytes (must satisfy zxc_validate_block_size).
[in]	mode	1 = compression, 0 = decompression.
[in]	level	Compression level (only consulted when `mode` == 1).
[in]	dict_size	Dictionary prefill size; when > 0 the figure includes the [dict \| data] concat buffer.

Returns: Size in bytes, or 0 if the parameters are invalid.

Returns the byte count that zxc_cctx_init would allocate for the given parameters.

Public contract documented at the declaration in zxc_internal.h. Thin wrapper that returns compute_cctx_layout(...).total, or 0 when chunk_size is 0.

Definition at line 245 of file zxc_common.c.

References compute_cctx_layout().

Referenced by zxc_estimate_cctx_size(), zxc_init_static_cctx(), zxc_init_static_dctx(), zxc_static_cctx_workspace_size(), and zxc_static_dctx_workspace_size().

◆ zxc_cctx_free()

void zxc_cctx_free ( zxc_cctx_t * ctx )

Releases the internal buffers owned by a context.

Does NOT free ctx itself - the caller owns the struct storage. The context may safely be re-initialised with zxc_cctx_init() afterwards.

Parameters

[in,out] ctx Context whose buffers should be released.

Releases the internal buffers owned by a context.

After this call every pointer inside ctx is NULL and the context may be safely re-initialised with zxc_cctx_init().

Definition at line 400 of file zxc_common.c.

References zxc_cctx_t::buf_extras, zxc_cctx_t::buf_offsets, zxc_cctx_t::buf_sequences, zxc_cctx_t::buf_split, zxc_cctx_t::buf_split_hist, zxc_cctx_t::buf_tokens, zxc_cctx_t::chain_table, zxc_cctx_t::dict_buffer, zxc_cctx_t::dict_buffer_cap, zxc_cctx_t::dict_huf, zxc_cctx_t::dict_huf_tree_ok, zxc_cctx_t::dict_size, zxc_cctx_t::entropy_block, zxc_cctx_t::epoch, zxc_cctx_t::hash_table, zxc_cctx_t::hash_tags, zxc_cctx_t::lit_buffer, zxc_cctx_t::lit_buffer_cap, zxc_cctx_t::lit_freq_acc, zxc_cctx_t::literals, zxc_cctx_t::memory_block, zxc_cctx_t::opt_scratch, zxc_cctx_t::opt_scratch_cap, zxc_cctx_t::pivco_scratch, zxc_cctx_t::pivco_scratch_cap, zxc_cctx_t::tok_buffer, zxc_cctx_t::tok_buffer_cap, zxc_cctx_t::work_buf, zxc_cctx_t::work_buf_cap, and ZXC_ALIGNED_FREE.

Referenced by ds_free_buffers(), zxc_compress(), zxc_compress_block_at(), zxc_compress_cctx(), zxc_dctx_carve(), zxc_dctx_prepare(), zxc_free_cctx(), zxc_free_dctx(), zxc_seek_mt_worker(), zxc_seekable_free(), zxc_seekable_set_dict(), zxc_stream_worker(), and zxc_train_dict_huf().

◆ zxc_cctx_init()

int zxc_cctx_init	(	zxc_cctx_t *	ctx,
		const size_t	chunk_size,
		const int	mode,
		const int	level,
		const int	checksum_enabled,
		const size_t	dict_size
	)

Initialises a ZXC compression / decompression context in place.

Allocates the internal buffers (hash table, sequence buffers, scratch) sized for chunk_size and the requested mode.

Parameters

[out]	ctx	Context to initialise.
[in]	chunk_size	Block size driving buffer sizing.
[in]	mode	1 for compression, 0 for decompression.
[in]	level	Compression level (ignored when `mode` == 0).
[in]	checksum_enabled	Non-zero to enable checksum computation.
[in]	dict_size	Dictionary prefill size; when > 0 an extra [dict \| data] concat buffer is carved into the workspace and `ctx->dict_buffer` is set.

Returns: ZXC_OK on success, or a negative zxc_error_t code (notably ZXC_ERROR_MEMORY on allocation failure).

Initialises a ZXC compression / decompression context in place.

Thin wrapper around zxc_cctx_init_in_workspace(): sizes the buffer via zxc_cctx_compute_workspace_size, allocates it, then partitions it. The pointer is stored in ctx->memory_block so zxc_cctx_free can release it. The static-cctx public API (see zxc_buffer.h) bypasses this wrapper and partitions a caller-supplied workspace directly.

Definition at line 339 of file zxc_common.c.

References compute_cctx_layout(), ZXC_ALIGNED_FREE, ZXC_ALIGNED_MALLOC, ZXC_CACHE_LINE_SIZE, zxc_cctx_init_in_workspace(), ZXC_ERROR_MEMORY, ZXC_ERROR_NULL_INPUT, and ZXC_OK.

Referenced by ds_handle_need_file_header(), zxc_compress(), zxc_compress_block_at(), zxc_compress_cctx(), zxc_create_cctx(), zxc_dctx_carve(), zxc_dctx_prepare(), zxc_seek_mt_worker(), zxc_seekable_decompress_range(), zxc_stream_worker(), and zxc_train_dict_huf().

◆ zxc_cctx_init_in_workspace()

int zxc_cctx_init_in_workspace	(	zxc_cctx_t *	ctx,
		void *	workspace,
		const size_t	workspace_size,
		const size_t	chunk_size,
		const int	mode,
		const int	level,
		const int	checksum_enabled,
		const size_t	dict_size,
		const int	defer_entropy_scratch
	)

Initialises a compression / decompression context inside a caller-supplied workspace.

Identical to zxc_cctx_init except that the persistent buffer is carved out of workspace instead of being ZXC_ALIGNED_MALLOC'd internally. workspace must be cache-line aligned and at least as large as zxc_cctx_compute_workspace_size for the same parameters.

The caller owns workspace and must keep it alive for the lifetime of ctx. zxc_cctx_free becomes a no-op for contexts initialised this way (the workspace is not freed by the library).

Parameters

[out]	ctx	Context to initialise (zeroed on entry).
[in]	workspace	Caller-allocated, cache-line-aligned buffer.
[in]	workspace_size	Capacity of `workspace` in bytes.
[in]	chunk_size	Block size in bytes.
[in]	mode	1 = compression, 0 = decompression.
[in]	level	Compression level (ignored when `mode` == 0).
[in]	checksum_enabled	Non-zero to enable checksum computation.
[in]	dict_size	Dictionary prefill size; when > 0 the workspace must include the [dict \| data] concat buffer and `ctx->dict_buffer` is set into it.
[in]	defer_entropy_scratch	Non-zero (heap decode contexts only) to leave the tok/PivCo decode scratch out of the partition; it is then lazily allocated by zxc_cctx_alloc_entropy_scratch on the first entropy section. Static workspaces must pass 0 (no-allocation contract).

Returns: ZXC_OK on success, ZXC_ERROR_DST_TOO_SMALL if the workspace is too small, or another negative zxc_error_t.

Initialises a compression / decompression context inside a caller-supplied workspace.

Public contract (alignment, lifetime, return codes) documented at the declaration in zxc_internal.h. Computes the layout via compute_cctx_layout, rejects an undersized workspace, then carves the sub-buffers out of it. ctx->memory_block stays NULL so zxc_cctx_free leaves the caller-owned workspace untouched.

Definition at line 260 of file zxc_common.c.

References compute_cctx_layout(), ZXC_DECOMPRESS_TAIL_PAD, ZXC_ERROR_DST_TOO_SMALL, ZXC_ERROR_NULL_INPUT, zxc_log2_u32(), ZXC_OK, and ZXC_PAD_SIZE.

Referenced by zxc_cctx_init(), zxc_init_static_cctx(), and zxc_init_static_dctx().

◆ zxc_check_eof_header()

int zxc_check_eof_header ( const uint8_t * hdr )

Checks an EOF block header against its one valid form: type 255, every other field zero, and its header checksum.

Parameters

[in] hdr The 8 header bytes, already read as an EOF block.

Returns: ZXC_OK or ZXC_ERROR_BAD_HEADER.

Definition at line 748 of file zxc_common.c.

References zxc_block_header_t::block_type, ZXC_BLOCK_HEADER_SIZE, ZXC_ERROR_BAD_HEADER, ZXC_OK, and zxc_write_block_header().

Referenced by ds_handle_need_block_header(), zxc_dctx_decode_frame(), zxc_seek_load_spans(), zxc_seekable_parse(), and zxc_stream_read_blocks().

◆ zxc_check_file_footer()

int zxc_check_file_footer	(	const uint8_t *	footer,
		const size_t	avail,
		const zxc_footer_layout_t *	l,
		const uint64_t	src_size,
		uint64_t *	digest
	)

Checks the footer a sequential reader reaches against l, the one the frame implies, on the avail bytes it has.

Compares only the bytes present: a mismatch is corruption, a matching but short prefix a truncation.

Parameters

[in]	footer	The footer bytes read so far.
[in]	avail	How many there are.
[in]	l	The layout the frame implies.
[in]	src_size	The decompressed size the footer must store.
[out]	digest	The stored digest, 0 without checksums; may be NULL.

Returns: ZXC_OK, ZXC_ERROR_CORRUPT_DATA or ZXC_ERROR_SRC_TOO_SMALL.

Checks the footer a sequential reader reaches against l, the one the frame implies, on the avail bytes it has.

Compares the bytes present, digest aside, with the footer it would write: one encoding per frame.

Definition at line 847 of file zxc_common.c.

References zxc_footer_layout_t::len, zxc_footer_layout_t::skip, zxc_encode_footer(), ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_SRC_TOO_SMALL, ZXC_FOOTER_MAX_SIZE_WITH_DIGEST, zxc_le64(), and ZXC_OK.

Referenced by zxc_dctx_decode_frame(), zxc_dstream_decompress(), and zxc_stream_finish_decompress().

◆ zxc_check_seek_header()

int zxc_check_seek_header	(	const uint8_t *	hdr,
		size_t	avail,
		uint64_t	total_out,
		size_t	block_size,
		uint64_t *	sek_bytes
	)

Checks the SEK block header the file header announced, on the avail bytes present.

A frame admits one header, the one zxc_seek_table_header() writes (reserved bytes zero), compared like the footer. A short footer never matches its start, so a flag set without a table reads as corrupt, not truncated.

Parameters

[in]	hdr	Bytes after the EOF block.
[in]	avail	How many of them are present.
[in]	total_out	Bytes the frame decoded to.
[in]	block_size	Block size from the file header.
[out]	sek_bytes	Table length in 64 bits (the field only holds its fold); may be NULL.

Returns: ZXC_OK, ZXC_ERROR_CORRUPT_DATA or ZXC_ERROR_SRC_TOO_SMALL.

Definition at line 757 of file zxc_common.c.

References ZXC_BLOCK_HEADER_SIZE, ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_SRC_TOO_SMALL, ZXC_OK, zxc_seek_block_count(), zxc_seek_table_bytes(), and zxc_seek_table_header().

Referenced by zxc_dctx_decode_frame(), zxc_dstream_decompress(), zxc_seek_load_spans(), zxc_seekable_parse(), and zxc_stream_finish_decompress().

◆ zxc_checksum()

static uint32_t zxc_checksum	(	const void *	input,
		const size_t	len,
		const uint64_t	seed,
		const uint8_t	hash_method
	)

inlinestatic

Calculates a 32-bit hash for a given input buffer.

Pass seed 0 for a standalone checksum. A non-zero seed derives one checksum from another: the first 64-bit hash is folded to 32 bits, and that fold is all the seed carries. So zxc_checksum(b, bn, zxc_checksum(a, an, 0, m), m) is a two-stage value over the pair (a, b), not the checksum of a || b; the two differ. Use it to bind two buffers under one id, never to hash a split buffer incrementally.

Parameters

[in]	input	Pointer to the data buffer.
[in]	len	Length of the data in bytes.
[in]	seed	0, a previous 32-bit checksum (zero-extended), or a block index.
[in]	hash_method	Checksum algorithm identifier (e.g., ZXC_CHECKSUM_RAPIDHASH).

Returns: The calculated 32-bit hash value.

Definition at line 1613 of file zxc_internal.h.

Referenced by zxc_compress_chunk_wrapper(), and zxc_dict_id().

◆ zxc_compress_block_at()

int64_t zxc_compress_block_at	(	zxc_cctx *	cctx,
		const void *	src,
		size_t	src_size,
		void *	dst,
		size_t	dst_capacity,
		const zxc_compress_opts_t *	opts,
		uint64_t	block_index
	)

zxc_compress_block, its checksum seeded with block_index (public entry: 0).

Definition at line 1674 of file zxc_dispatch.c.

References zxc_compress_opts_t::checksum_enabled, zxc_compress_opts_t::dict, zxc_block_size_ceil(), ZXC_BLOCK_SIZE_MAX, zxc_cctx_free(), zxc_cctx_init(), zxc_compress_chunk_wrapper(), zxc_ctx_sync_dict_huf(), ZXC_DICT_SIZE_MAX, ZXC_ERROR_BAD_BLOCK_SIZE, ZXC_ERROR_BAD_LEVEL, ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_DICT_TOO_LARGE, ZXC_ERROR_DICT_UNSUPPORTED, ZXC_ERROR_MEMORY, ZXC_ERROR_NULL_INPUT, ZXC_LEVEL_DENSITY, ZXC_OK, ZXC_OPTS_BLOCK_SIZE, ZXC_OPTS_DICT_HUF, ZXC_OPTS_DICT_SIZE, and ZXC_OPTS_LEVEL.

Referenced by cs_compress_block_from(), and zxc_compress_block().

◆ zxc_compress_chunk_wrapper()

int zxc_compress_chunk_wrapper	(	zxc_cctx_t *	ctx,
		const uint8_t *	src,
		const size_t	src_sz,
		uint8_t *	dst,
		const size_t	dst_cap,
		const uint64_t	block_index
	)

Compresses one chunk through the runtime ISA dispatch.

Counterpart of zxc_decompress_chunk_wrapper(): same lazily-resolved variant pointer, same one-time CPU detection on the first call.

Parameters

[in,out]	ctx	Compression context: configuration and working buffers.
[in]	src	Raw data to compress.
[in]	src_sz	Size of `src` in bytes.
[out]	dst	Destination buffer.
[in]	dst_cap	Capacity of `dst`.
[in]	block_index	Frame position of the block: checksum seed, 0 for the block API.

Returns: Bytes written (> 0), or a negative zxc_error_t.

Compresses one chunk through the runtime ISA dispatch.

Selects the GHI encoder at level <= 2, otherwise GLO; falls back to a RAW block when the coded form would not shrink the data. When ctx->dict_size is > 0, chunk is the [dict | block] concat and only the block tail counts toward the expansion check. Appends the checksum when enabled, seeded with block_index.

Compresses one chunk through the runtime ISA dispatch.

Definition at line 2217 of file zxc_compress.c.

References ZXC_BLOCK_CHECKSUM_SIZE, ZXC_BLOCK_HEADER_SIZE, zxc_checksum(), ZXC_CHECKSUM_RAPIDHASH, zxc_encode_block_ghi(), zxc_encode_block_glo(), zxc_encode_block_raw(), ZXC_ERROR_DST_TOO_SMALL, ZXC_ERROR_OVERFLOW, ZXC_OK, zxc_store_le32(), and zxc_variants().

Referenced by zxc_compress(), zxc_compress_block_at(), zxc_compress_cctx(), zxc_stream_process(), and zxc_train_dict_huf().

◆ zxc_container_next()

int zxc_container_next	(	const zxc_scan_src_t *	src,
		uint64_t	pos
	)

Tells whether a frame starts at pos.

A wrong magic word is ZXC_ERROR_BAD_MAGIC at offset 0, as for a single frame, and ZXC_ERROR_CORRUPT_DATA after one.

Parameters

[in]	src	Container source.
[in]	pos	Offset just past the previous frame, 0 for the first.

Returns: 1 on a frame, 0 at the end of the input, or a negative zxc_error_t.

Definition at line 558 of file zxc_common.c.

References ZXC_ERROR_BAD_MAGIC, ZXC_ERROR_CORRUPT_DATA, zxc_magic_prefix_ok(), ZXC_OK, and zxc_scan_read().

Referenced by zxc_dctx_decode_container().

◆ zxc_copy16()

static void zxc_copy16	(	void *	dst,
		const void *	src
	)

inlinestatic

Copies exactly 16 bytes as one vector move where the ISA has one.

SSE2 on x86, NEON on ARM, memcpy elsewhere. Fixed width: the caller must have 16 readable and 16 writable bytes.

Parameters

[out]	dst	Pointer to the destination memory block.
[in]	src	Pointer to the source memory block.

Definition at line 1481 of file zxc_internal.h.

Referenced by zxc_decode_copy_overlap_run32().

◆ zxc_copy32()

static void zxc_copy32	(	void *	dst,
		const void *	src
	)

inlinestatic

Copies 32 bytes from source to destination using SIMD when available.

Uses AVX2 on x86, NEON on ARM64/ARM32, or two 16-byte copies as fallback.

Parameters

[out]	dst	Pointer to the destination memory block.
[in]	src	Pointer to the source memory block.

Definition at line 1500 of file zxc_internal.h.

Referenced by zxc_decode_copy_match_short(), zxc_flush_literals(), and zxc_wild_copy32().

◆ zxc_ctz32()

static int zxc_ctz32 ( const uint32_t x )

inlinestatic

Counts trailing zeros, returning 32 for a zero input.

The zero case is the reason for the guard: both __builtin_ctz and _BitScanForward leave the result undefined there.

Parameters

[in] x Value to scan.

Returns: Trailing zero count, in [0, 32].

Definition at line 1528 of file zxc_internal.h.

Referenced by zxc_encode_block_glo(), zxc_lz77_find_best_match(), zxc_seek_block_count(), and zxc_seek_block_of_offset().

◆ zxc_ctz64()

static int zxc_ctz64 ( const uint64_t x )

inlinestatic

Counts trailing zeros, returning 64 for a zero input.

The zero case is the reason for the guard: both __builtin_ctzll and _BitScanForward64 leave the result undefined there.

Parameters

[in] x Value to scan.

Returns: Trailing zero count, in [0, 64].

Definition at line 1554 of file zxc_internal.h.

Referenced by zxc_encode_block_glo(), zxc_lz77_find_best_match(), zxc_lz77_optimal_parse_glo(), and zxc_match_reaches().

◆ zxc_decompress_chunk_wrapper()

int zxc_decompress_chunk_wrapper	(	const zxc_cctx_t *	ctx,
		const uint8_t *	src,
		const size_t	src_sz,
		uint8_t *	dst,
		const size_t	dst_cap,
		const uint64_t	block_index
	)

Decompresses one chunk through the runtime ISA dispatch.

Un-suffixed entry point: it loads the resolved variant pointer (_default, _avx2, _avx512, ...), running the one-time CPU detection on the first call, and routes to the dict variant when the context carries a dictionary.

Parameters

[in]	ctx	Context holding the decode state and dictionary, if any.
[in]	src	Compressed chunk.
[in]	src_sz	Size of `src` in bytes.
[out]	dst	Destination buffer.
[in]	dst_cap	Capacity of `dst`.
[in]	block_index	Frame position of the block: checksum seed, 0 for the block API.

Returns: Bytes decoded (> 0), or a negative zxc_error_t.

Decompresses one chunk through the runtime ISA dispatch.

Inlines the plain GLO/GHI decoders via zxc_decompress_chunk_wrapper_body with has_dict=0, so it carries no dict code and matches the dict-free build.

Decompresses one chunk through the runtime ISA dispatch.

Definition at line 1654 of file zxc_decompress.c.

References zxc_variants().

Referenced by zxc_dctx_decode_frame(), zxc_decode_bounce(), zxc_decompress_block(), zxc_dstream_decompress(), zxc_seek_mt_worker(), zxc_seekable_decompress_range(), zxc_static_decompress_block(), and zxc_stream_process().

◆ zxc_decompress_chunk_wrapper_dict()

int zxc_decompress_chunk_wrapper_dict	(	const zxc_cctx_t *	ctx,
		const uint8_t *	src,
		const size_t	src_sz,
		uint8_t *	dst,
		const size_t	dst_cap,
		const uint64_t	block_index
	)

Public dictionary chunk decoder.

Routes through zxc_decompress_chunk_wrapper_body with has_dict=1, which calls the NOINLINE _dict decoders (slower: dict back-refs read the prepended dictionary). Used only when ctx->dict_size != 0.

Parameters

[in,out]	ctx	Decompression context (dict prefix in its buffer).
[in]	src	Compressed block bytes.
[in]	src_sz	Size of `src` in bytes.
[out]	dst	Destination buffer for the decoded block.
[in]	dst_cap	Capacity of `dst` in bytes.
[in]	block_index	Frame position of the block: the checksum seed.

Returns: Bytes written on success, or a negative zxc_error_t.

Definition at line 1676 of file zxc_decompress.c.

◆ zxc_decompress_chunk_wrapper_safe()

int zxc_decompress_chunk_wrapper_safe	(	const zxc_cctx_t *	ctx,
		const uint8_t *	src,
		const size_t	src_sz,
		uint8_t *	dst,
		const size_t	dst_cap,
		const uint64_t	block_index
	)

Exact-capacity variant for the safe block API; dispatch table only.

Routes through zxc_decompress_chunk_wrapper_body with safe=1, which calls the NOINLINE _safe decoders (no bounce buffer, no tail padding); RAW blocks are copied directly. Dict inputs are not handled here (the caller routes them to the bounce-capable path).

Parameters

[in,out]	ctx	Decompression context.
[in]	src	Compressed block bytes.
[in]	src_sz	Size of `src` in bytes.
[out]	dst	Destination buffer (capacity == exact decoded size).
[in]	dst_cap	Capacity of `dst` in bytes.
[in]	block_index	Frame position of the block: the checksum seed.

Returns: Bytes written on success, or a negative zxc_error_t.

Definition at line 1699 of file zxc_decompress.c.

◆ zxc_digest_combine()

static uint64_t zxc_digest_combine	(	const uint64_t	acc,
		const uint32_t	block_checksum
	)

inlinestatic

Folds a data block's 32-bit checksum into the running archive digest.

The digest, stored after the source size in the file footer when checksums are on, is this fold over every block in stream order: an ordered 64-bit identity of the archive that a reordered or altered block changes. Verified on a full decode, never on a range read. Seed 0 for the first block.

The checksum is spread across 64 bits, XORed into the accumulator, then mum-folded (64x64 multiply, XOR of the two 128-bit halves). The result is a 64-bit digest that is sensitive to the order and content of all blocks.

Definition at line 1633 of file zxc_internal.h.

References ZXC_HASH_GOLDEN64, and ZXC_HASH_XORSHIFT64.

Referenced by cs_compress_block_from(), zxc_async_writer(), zxc_compress(), zxc_compress_cctx(), zxc_dctx_decode_frame(), zxc_dstream_decompress(), and zxc_stream_read_blocks().

◆ zxc_file_header_sign()

static void zxc_file_header_sign ( uint8_t * h )

inlinestatic

Writes the file header checksum (bytes 14-15) over the other 14 bytes.

Parameters

[in,out] h The 16-byte file header.

Definition at line 1467 of file zxc_internal.h.

References zxc_hash16(), and zxc_store_le16().

Referenced by zxc_write_file_header().

◆ zxc_footer_dsize_plausible()

static int zxc_footer_dsize_plausible	(	const uint64_t	dsize,
		const size_t	chunk_size,
		const uint64_t	comp_size
	)

inlinestatic

Whether a footer's decompressed size is reachable for this archive.

The footer is untrusted and its size becomes the caller's allocation, so it is capped by what the archive could physically hold: every block costs at least ZXC_BLOCK_HEADER_SIZE compressed bytes and decodes to at most one block size. The cap also keeps zxc_inplace_margin's block count from overflowing. Every reader that sizes anything from the footer goes through it.

Parameters

[in]	dsize	Decompressed size read from the footer.
[in]	chunk_size	Block size from the file header; never 0 after a ZXC_OK from zxc_read_file_header.
[in]	comp_size	Size of the whole archive in bytes.

Returns: 1 when dsize is reachable, 0 for a forged footer.

Definition at line 2432 of file zxc_internal.h.

References ZXC_BLOCK_HEADER_SIZE, and zxc_seek_block_count().

Referenced by zxc_read_frame_info().

◆ zxc_footer_layout()

static zxc_footer_layout_t zxc_footer_layout	(	const uint64_t	prefix,
		const uint64_t	src_size,
		const int	checksum_enabled
	)

inlinestatic

The footer of a frame whose first prefix bytes precede it.

compressed_size counts its own bytes: nf is the fewest that hold the total, a unique choice both ends derive.

Definition at line 2323 of file zxc_internal.h.

References zxc_footer_layout_t::compressed_size, zxc_footer_layout_t::len, zxc_footer_layout_t::nd, zxc_footer_layout_t::nf, zxc_footer_layout_t::skip, ZXC_FILE_DIGEST_SIZE, and zxc_uint_bytes().

Referenced by ds_handle_need_block_header(), zxc_dctx_decode_frame(), zxc_dstream_decompress(), zxc_stream_finish_decompress(), and zxc_write_file_footer().

◆ zxc_frame_info_copy()

static void zxc_frame_info_copy	(	zxc_frame_info_t *	info,
		const size_t	info_size,
		const zxc_frame_info_t *	got
	)

inlinestatic

Copies the fields of got that fit the caller's info_size bytes.

Definition at line 2411 of file zxc_internal.h.

Referenced by zxc_get_frame_info(), zxc_get_last_frame_info(), zxc_stream_get_frame_info(), and zxc_stream_get_last_frame_info().

◆ zxc_frame_tail_len()

static size_t zxc_frame_tail_len ( const uint64_t total )

inlinestatic

Bytes zxc_read_frame_info() takes from the end of total bytes (at least ZXC_FRAME_MIN_SIZE): all of them past the header and EOF block, up to ZXC_FOOTER_MAX_SIZE_WITH_DIGEST.

Definition at line 2390 of file zxc_internal.h.

References ZXC_BLOCK_HEADER_SIZE, ZXC_FILE_HEADER_SIZE, and ZXC_FOOTER_MAX_SIZE_WITH_DIGEST.

Referenced by zxc_scan_frame().

◆ zxc_get_lz77_params()

static zxc_lz77_params_t zxc_get_lz77_params ( const int level )

inlinestatic

Retrieves LZ77 compression parameters based on the specified compression level.

This inline function returns the appropriate LZ77 parameters configuration for the given compression level.

Parameters

[in] level Compression level; out-of-range values clamp to level 1.

Returns: The tuning tuple for that level.

Definition at line 1163 of file zxc_internal.h.

References ZXC_LEVEL_FASTEST, ZXC_LEVEL_ULTRA, and ZXC_LZ_MINDIST.

Referenced by zxc_encode_block_ghi(), zxc_encode_block_glo(), and zxc_lz77_optimal_parse_glo().

◆ zxc_hash16()

static uint16_t zxc_hash16 ( const uint8_t * p )

inlinestatic

Computes the 2-byte checksum for file and dictionary headers.

Two multiplies in a chain: the first half is mixed, the second is added and mixed again. Every bit flip shifts the result by a fixed amount, and the constants are such that no 1- or 2-bit error leaves the top halfword unchanged (proven by the test suite). Summing two products instead let one bit per half cancel. Order matters: ZXC_HASH_MULT64 inside, ZXC_HASH_GOLDEN64 outside; swapped, 38 bit pairs can cancel.

Parameters

[in] p The 16 header bytes; bytes 14..15 must already be zero.

Returns: The checksum halfword.

Definition at line 1456 of file zxc_internal.h.

References ZXC_HASH_GOLDEN64, ZXC_HASH_MULT64, and zxc_le64().

Referenced by zxc_dict_load(), zxc_dict_save(), zxc_file_header_sign(), and zxc_read_file_header().

◆ zxc_hash8()

static uint8_t zxc_hash8 ( const uint8_t * p )

inlinestatic

Computes the 1-byte checksum for block headers.

Multiply, then fold from the top. Flipping bit i moves the product by exactly +/- (ZXC_HASH_GOLDEN64 << i), and no shift of that constant leaves 0x00 or 0xFF in the top byte, so the carry cannot absorb it: every single-bit error is caught, not merely likely to be. Folding from the top is required - a product's low bits depend only on the input's low bits.

Parameters

[in] p The 8 header bytes to hash.

Returns: The checksum byte.

Definition at line 1437 of file zxc_internal.h.

References ZXC_HASH_GOLDEN64, and zxc_le64().

Referenced by zxc_read_block_header(), and zxc_write_block_header().

◆ zxc_huf_build_code_lengths()

int zxc_huf_build_code_lengths	(	const uint32_t *	freq,
		uint8_t *	code_len,
		void *	scratch,
		const int	max_code_len
	)

Build length-limited canonical Huffman code lengths from a frequency table.

Uses the boundary package-merge algorithm capped at ZXC_HUF_MAX_CODE_LEN_ULTRA. Symbols with freq[i] == 0 get code_len[i] == 0; others receive a value in [1, ZXC_HUF_MAX_CODE_LEN_ULTRA].

Parameters

[in]	freq	Frequency table of length `ZXC_HUF_NUM_SYMBOLS`.
[out]	code_len	Output code-length array of length `ZXC_HUF_NUM_SYMBOLS`.
[in]	scratch	Optional caller-owned scratch buffer of at least ZXC_HUF_BUILD_SCRATCH_SIZE bytes. If `NULL`, the function allocates its own working memory and frees it before returning.
[in]	max_code_len	Code-length ceiling in `[1, ZXC_HUF_MAX_CODE_LEN_ULTRA]`; package-merge is run for this many levels (see zxc_huf_enc_max_code_len for the per-level value).

Returns: ZXC_OK on success, negative zxc_error_t code on failure.

Build length-limited canonical Huffman code lengths from a frequency table.

Un-suffixed entry forwarding to zxc_huf_build_code_lengths_default; full contract in zxc_internal.h.

Build length-limited canonical Huffman code lengths from a frequency table.

Runs the boundary package-merge algorithm capped at ZXC_HUF_MAX_CODE_LEN_ULTRA. Symbols with freq[i] == 0 get code_len[i] == 0; every other symbol receives a length in [1, ZXC_HUF_MAX_CODE_LEN_ULTRA]. The single-present-symbol case is handled as a degenerate code of length 1.

Definition at line 490 of file zxc_dispatch.c.

References zxc_huf_pm_frame_t::idx, zxc_huf_pm_item_t::left, zxc_huf_pm_frame_t::lvl, pm_leaves_sort(), zxc_huf_pm_item_t::right, zxc_huf_pm_item_t::sym, zxc_huf_pm_leaf_t::sym, zxc_huf_pm_leaf_t::w, ZXC_CALLOC, ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_MEMORY, ZXC_FREE, ZXC_HUF_MAX_CODE_LEN_ULTRA, ZXC_HUF_NUM_SYMBOLS, ZXC_HUF_PM_LEVEL_BOUND, ZXC_MALLOC, and ZXC_OK.

Referenced by zxc_encode_block_glo(), zxc_huf_nudge_code_lengths(), zxc_opt_estimate_lit_bits(), and zxc_train_dict_huf().

◆ zxc_huf_calc_size()

size_t zxc_huf_calc_size	(	const uint32_t *	freq,
		const uint8_t *	code_len,
		const int	with_header
	)

Exact encoded size (bytes) of a PivCo section for this histogram and code lengths; includes the 128-byte lengths header when with_header.

Definition at line 496 of file zxc_dispatch.c.

References zxc_huf_calc_size_dict(), ZXC_HUF_TABLE_SIZE, and zxc_pivco_tree_build().

Referenced by zxc_encode_block_glo().

◆ zxc_huf_calc_size_dict()

size_t zxc_huf_calc_size_dict	(	const uint32_t *	freq,
		const uint8_t *	code_len,
		const zxc_pivco_tree_t *	tree
	)

zxc_huf_calc_size for a dict section: prebuilt tree, no header.

Definition at line 527 of file zxc_dispatch.c.

References ZXC_HUF_NUM_SYMBOLS, zxc_pivco_counts(), zxc_pivco_layout(), and ZXC_PIVCO_NODE_SLOTS.

Referenced by zxc_encode_block_glo(), and zxc_huf_calc_size().

◆ zxc_huf_decode_section()

int zxc_huf_decode_section	(	const uint8_t *	payload,
		const size_t	payload_size,
		uint8_t *	dst,
		const size_t	n,
		uint8_t *	scratch
	)

Decode a PivCo literal section into dst (exactly n bytes).

dst needs ZXC_PAD_SIZE slack, scratch at least n + ZXC_PIVCO_SCRATCH_PAD.

Decode a PivCo literal section into dst (exactly n bytes).

Unpacks and validates the 128-byte code-length header, then runs the bottom-up merge decoder.

Parameters

[in]	payload	Section bytes (header + node runs).
[in]	payload_size	Section size in bytes.
[out]	dst	Receives the `n` decoded symbols; needs ZXC_PAD_SIZE bytes of write slack past `n`.
[in]	n	Expected symbol count.
[in]	scratch	Level ping-pong buffer with at least n + ZXC_PIVCO_SCRATCH_PAD bytes.

Returns: ZXC_OK or ZXC_ERROR_CORRUPT_DATA.

Definition at line 507 of file zxc_dispatch.c.

References ZXC_ERROR_CORRUPT_DATA, ZXC_HUF_NUM_SYMBOLS, ZXC_HUF_TABLE_SIZE, zxc_huf_unpack_lengths(), ZXC_OK, zxc_pivco_decode_core(), and zxc_pivco_tree_build().

◆ zxc_huf_decode_section_dict()

int zxc_huf_decode_section_dict	(	const uint8_t *	payload,
		const size_t	payload_size,
		uint8_t *	dst,
		const size_t	n,
		const zxc_pivco_tree_t *	tree,
		uint8_t *	scratch
	)

Decode a PivCo dict section against a prebuilt dict tree.

Same as zxc_huf_decode_section, but against the dictionary's PivCo tree, prebuilt ONCE at attach time by zxc_huf_dict_tree_build (wire value enc_lit = 3): no per-block unpack or tree rebuild.

Definition at line 521 of file zxc_dispatch.c.

References zxc_pivco_decode_core().

◆ zxc_huf_dict_tree_build()

int zxc_huf_dict_tree_build	(	const uint8_t *	packed_lengths,
		zxc_pivco_tree_t *	tree,
		uint32_t *	codes,
		uint8_t *	code_len
	)

Unpack a dict table's packed lengths and prebuild its tree, codes and code lengths, once per frame.

Unpacks the packed lengths and builds the tree and codes once, for every block to reuse.

Definition at line 1343 of file zxc_huffman.c.

References ZXC_ERROR_CORRUPT_DATA, zxc_huf_unpack_lengths(), ZXC_OK, zxc_pivco_codes(), and zxc_pivco_tree_build().

Referenced by zxc_cctx_attach_dict_huf().

◆ zxc_huf_enc_max_code_len()

static int zxc_huf_enc_max_code_len ( const int level )

inlinestatic

Encoder Huffman code-length cap for a compression level: levels below ZXC_LEVEL_ULTRA use ZXC_HUF_MAX_CODE_LEN_DENSITY, ZXC_LEVEL_ULTRA uses the full ZXC_HUF_MAX_CODE_LEN_ULTRA ceiling (denser codes, slower decode).

Applies to both literal and token Huffman; the decoder always supports the ceiling, so lower-level streams decode unchanged.

Definition at line 965 of file zxc_internal.h.

References ZXC_HUF_MAX_CODE_LEN_DENSITY, ZXC_HUF_MAX_CODE_LEN_ULTRA, and ZXC_LEVEL_ULTRA.

Referenced by zxc_encode_block_glo().

◆ zxc_huf_encode_section()

int zxc_huf_encode_section	(	const uint8_t *	literals,
		const size_t	n_literals,
		const uint32_t *	freq,
		const uint8_t *	code_len,
		uint8_t *	dst,
		const size_t	dst_cap
	)

Encode a PivCo literal section (128-byte lengths header + payload).

Emits the 128-byte packed code-length header followed by the per-node branch runs. The caller supplies the histogram and code lengths it already built for the selection step.

Parameters

[in]	literals	Symbols to encode (n_literals bytes).
[in]	n_literals	Symbol count (> 0).
[in]	freq	Symbol histogram of `literals`.
[in]	code_len	Per-symbol code lengths (every symbol with freq != 0 must have a code).
[out]	dst	Destination buffer.
[in]	dst_cap	Destination capacity in bytes.

Returns: Encoded size in bytes, or a negative ZXC_ERROR_* value (ZXC_ERROR_DST_TOO_SMALL, ZXC_ERROR_CORRUPT_DATA).

Definition at line 501 of file zxc_dispatch.c.

References ZXC_ERROR_CORRUPT_DATA, ZXC_HUF_NUM_SYMBOLS, zxc_pivco_codes(), zxc_pivco_encode_core(), and zxc_pivco_tree_build().

Referenced by zxc_encode_block_glo().

◆ zxc_huf_encode_section_dict()

int zxc_huf_encode_section_dict	(	const uint8_t *	literals,
		const size_t	n_literals,
		const uint32_t *	freq,
		const uint8_t *	code_len,
		const zxc_pivco_tree_t *	tree,
		const uint32_t *	codes,
		uint8_t *	dst,
		const size_t	dst_cap
	)

Encode a PivCo section against a prebuilt dict tree/codes (no header).

Same payload as zxc_huf_encode_section with the 128-byte lengths header omitted: code_len / tree / codes come from the dictionary's shared literal table, prebuilt ONCE at attach by zxc_huf_dict_tree_build (wire value enc_lit = 3).

Definition at line 512 of file zxc_dispatch.c.

References zxc_pivco_encode_core().

Referenced by zxc_encode_block_glo().

◆ zxc_huf_nudge_code_lengths()

int zxc_huf_nudge_code_lengths	(	const uint32_t *	freq,
		uint8_t *	code_len,
		void *	scratch,
		size_t	scratch_cap,
		int	max_code_len
	)

Optionally reshape freshly built code lengths for faster PivCo decode.

Explores a small set of Kraft-exact alternatives to code_len (a greedy slot-ledger walk toward power-of-two class counts, package-merge rebuilds at reduced depth caps, and the slot-ledger dynamic program at a coarse granularity picked from the alphabet size) and prices each against the modeled decode cost of zxc_pivco_decode_core. The cheapest candidate that clears the adoption guard (<= +ZXC_HUF_NUDGE_BITS_PERMIL ratio cost AND <= ZXC_HUF_NUDGE_MERGE_Q8 modeled level-touches) replaces code_len; otherwise the array is left byte-for-byte untouched, so a rejected nudge emits an archive identical to the unadjusted encoder. Coarse-DP candidates may pad the tree with zero-frequency "ghost" leaves on unused byte values; the wire carries them as empty runs.

Encoder policy only: any adopted output is canonical, Kraft-exact and capped at max_code_len, so the wire format and every deployed decoder are unaffected. Compiled once in the primary variant (ISA-independent decision code), guaranteeing cross-ISA identical archives. Cost is a few hundred microseconds per table at most (DP plane sizes are capped by the coarse granularity), which the ULTRA-only and trainer call sites absorb.

Parameters

[in]	freq	Frequency table of length `ZXC_HUF_NUM_SYMBOLS`.
[in,out]	code_len	Lengths from zxc_huf_build_code_lengths.
[in]	scratch	Optional: the rebuilds' region, plus the workspace when `scratch_cap` reaches ZXC_HUF_NUDGE_SCRATCH_SIZE (else the workspace is allocated for the call).
[in]	scratch_cap	Bytes at `scratch`.
[in]	max_code_len	Cap the caller built with (level cap).

Returns: 1 if code_len was adjusted, 0 if kept.

Definition at line 790 of file zxc_huffman.c.

References zxc_huf_nudge_ws_t::cand, zxc_huf_nudge_ws_t::leaves, zxc_huf_nudge_ws_t::pf, zxc_huf_nudge_ws_t::pf_rank, zxc_huf_nudge_ws_t::pfg, pm_leaves_sort(), zxc_huf_pm_leaf_t::sym, zxc_huf_nudge_ws_t::sym_order, zxc_huf_pm_leaf_t::w, ZXC_FREE, zxc_huf_build_code_lengths(), ZXC_HUF_MAX_CODE_LEN_ULTRA, zxc_huf_nudge_assign(), ZXC_HUF_NUDGE_BITS_PERMIL, zxc_huf_nudge_classes(), ZXC_HUF_NUDGE_DP_M, zxc_huf_nudge_dp_solve(), zxc_huf_nudge_eval(), zxc_huf_nudge_j(), ZXC_HUF_NUDGE_MERGE_Q8, zxc_huf_nudge_pf_canonical(), ZXC_HUF_NUDGE_SCRATCH_OFF, ZXC_HUF_NUDGE_SCRATCH_SIZE, zxc_huf_nudge_walk(), ZXC_HUF_NUM_SYMBOLS, ZXC_MALLOC, and ZXC_OK.

Referenced by zxc_encode_block_glo(), and zxc_train_dict_huf().

◆ zxc_huf_nudge_cost()

void zxc_huf_nudge_cost	(	const uint8_t *	code_len,
		const uint32_t *	freq,
		uint64_t *	bits,
		uint64_t *	touches
	)

Modeled (bits, level-touches) decode cost of one code-length vector.

Introspection hook for the nudge's cost model (exact, canonical-order frequency weighting); the unit tests cross-check it against the real tree built by the decoder. code_len must be structurally valid.

Definition at line 778 of file zxc_huffman.c.

References ZXC_HUF_MAX_CODE_LEN_ULTRA, zxc_huf_nudge_classes(), zxc_huf_nudge_eval(), zxc_huf_nudge_pf_canonical(), and ZXC_HUF_NUM_SYMBOLS.

◆ zxc_huf_pack_lengths()

void zxc_huf_pack_lengths	(	const uint8_t *	code_len,
		uint8_t *	out
	)

Pack per-symbol code lengths into the 128-byte (4-bit nibble) header.

Nibble order follows the byte: code_len[2*i] low, code_len[2*i + 1] high. Lengths above 15 are silently truncated, so the caller must have capped at ZXC_HUF_MAX_CODE_LEN_ULTRA (<= 15) first.

Parameters

[in]	code_len	Per-symbol lengths, `ZXC_HUF_NUM_SYMBOLS` entries.
[out]	out	`ZXC_HUF_TABLE_SIZE` bytes of packed header.

Pack per-symbol code lengths into the 128-byte (4-bit nibble) header.

Un-suffixed entry forwarding to zxc_huf_pack_lengths_default; full contract in zxc_internal.h.

Definition at line 538 of file zxc_dispatch.c.

References ZXC_HUF_NUM_SYMBOLS.

Referenced by zxc_pivco_encode_core(), and zxc_train_dict_huf().

◆ zxc_huf_unpack_lengths()

int zxc_huf_unpack_lengths	(	const uint8_t *	in,
		uint8_t *	code_len
	)

Unpack and structurally validate a 128-byte packed lengths header.

Inverts zxc_huf_pack_lengths and checks the two structural invariants: no length above ZXC_HUF_MAX_CODE_LEN_ULTRA, and at least one symbol present. Kraft consistency is not checked here; the tree build does that later.

Parameters

[in]	in	128-byte packed header.
[out]	code_len	Per-symbol lengths, `ZXC_HUF_NUM_SYMBOLS` entries.

Returns: ZXC_OK, or ZXC_ERROR_CORRUPT_DATA if a length is too large or the table is empty.

Unpack and structurally validate a 128-byte packed lengths header.

Un-suffixed entry forwarding to zxc_huf_unpack_lengths_default; full contract in zxc_internal.h.

Definition at line 548 of file zxc_dispatch.c.

References ZXC_ERROR_CORRUPT_DATA, ZXC_HUF_MAX_CODE_LEN_ULTRA, ZXC_HUF_NUM_SYMBOLS, and ZXC_OK.

Referenced by zxc_huf_decode_section(), and zxc_huf_dict_tree_build().

◆ zxc_le16()

static uint16_t zxc_le16 ( const void * p )

inlinestatic

Reads a little-endian 16-bit value from a possibly unaligned address.

MEMORY & ENDIANNESS HELPERS

Functions to handle unaligned memory access and Little Endian conversion.

The memcpy is what makes the unaligned read defined; compilers fold it into a single load. Byte-swapped on big-endian hosts, so the wire stays LE.

Parameters

[in] p Address to read from.

Returns: The value, in host order.

Definition at line 1279 of file zxc_internal.h.

Referenced by zxc_dict_huf(), zxc_dict_load(), and zxc_read_file_header().

◆ zxc_le32()

static uint32_t zxc_le32 ( const void * p )

inlinestatic

Reads a little-endian 32-bit value from a possibly unaligned address.

The memcpy is what makes the unaligned read defined; compilers fold it into a single load. Byte-swapped on big-endian hosts, so the wire stays LE.

Parameters

[in] p Address to read from.

Returns: The value, in host order.

Definition at line 1298 of file zxc_internal.h.

Referenced by cs_compress_block_from(), zxc_async_writer(), zxc_block_is_short_dist_bound(), zxc_compress(), zxc_compress_cctx(), zxc_dctx_decode_frame(), zxc_dict_get_id(), zxc_dict_hash(), zxc_dict_huf(), zxc_dict_load(), zxc_dstream_decompress(), zxc_get_dict_id(), zxc_lazy_probe(), zxc_lz77_find_best_match(), zxc_pivco_unpack_flat(), zxc_read_block_header(), zxc_read_file_header(), zxc_read_glo_header_and_desc(), zxc_read_gnr_header(), zxc_seek_load_spans(), zxc_stream_decompress(), zxc_stream_read_blocks(), and zxc_write_seek_table_from_blocks().

◆ zxc_le64()

static uint64_t zxc_le64 ( const void * p )

inlinestatic

Reads a little-endian 64-bit value from a possibly unaligned address.

The memcpy is what makes the unaligned read defined; compilers fold it into a single load. Byte-swapped on big-endian hosts, so the wire stays LE.

Parameters

[in] p Address to read from.

Returns: The value, in host order.

Definition at line 1361 of file zxc_internal.h.

Referenced by zxc_check_file_footer(), zxc_dstream_decompress(), zxc_encode_block_ghi(), zxc_encode_block_glo(), zxc_hash16(), zxc_hash8(), zxc_lazy_probe(), zxc_lz77_find_best_match(), zxc_lz_seed_dict(), zxc_match_reaches(), zxc_pivco_unpack_flat(), zxc_read_frame_info(), and zxc_seek_load_spans().

◆ zxc_level_clamp()

static int zxc_level_clamp ( const int level )

inlinestatic

Clamps a resolved compression level to the supported ceiling.

   Out-of-range levels above ::ZXC_LEVEL_ULTRA are silently clamped
   (never rejected) at every compress entry point, so `level = 99`
   behaves as ULTRA across the buffer, context, block and stream APIs
   and every language binding inherits the same policy. Levels <= 0
   select the caller's default before this is applied.

Definition at line 921 of file zxc_internal.h.

References ZXC_LEVEL_ULTRA.

◆ zxc_log2_u32()

static uint32_t zxc_log2_u32 ( const uint32_t v )

inlinestatic

Integer log-base-2 for a 32-bit value.

Parameters

v	Must be a power of two (returns 0 for zero).

Returns: Floor of log2(v).

Definition at line 1059 of file zxc_internal.h.

Referenced by compute_cctx_layout(), pm_leaves_sort(), zxc_cctx_init_in_workspace(), zxc_huf_nudge_dp_run_j(), zxc_huf_nudge_eval(), zxc_huf_nudge_walk(), and zxc_write_file_header().

◆ zxc_opt_dp_sizes()

static void zxc_opt_dp_sizes	(	const size_t	chunk_size,
		size_t *	sz_dp,
		size_t *	sz_pl,
		size_t *	sz_po,
		size_t *	sz_bm
	)

inlinestatic

The four DP partitions the optimal parser carves out of opt_scratch.

One definition shared by compute_cctx_layout(), which reserves the region, and zxc_lz77_optimal_parse_glo(), which carves it: the two cannot drift.

Definition at line 1041 of file zxc_internal.h.

References ZXC_ALIGN_CL, and ZXC_BITMAP_WORDS.

Referenced by compute_cctx_layout(), and zxc_lz77_optimal_parse_glo().

◆ zxc_parse_file_footer()

int zxc_parse_file_footer	(	const uint8_t *	end,
		const size_t	avail,
		uint64_t *	src_size,
		uint64_t *	compressed_size,
		size_t *	sizes_len
	)

Parses the sizes back from the end of a frame.

Parameters

[in]	end	One past the frame's last byte.
[in]	avail	Bytes readable before `end`.
[out]	src_size	Stored original size.
[out]	compressed_size	Stored compressed size of the frame.
[out]	sizes_len	Bytes of the two sizes and L; the digest, when the header announces one, precedes them.

Returns: ZXC_OK, ZXC_ERROR_SRC_TOO_SMALL, or ZXC_ERROR_CORRUPT_DATA for a malformed lengths byte or a non-minimal length.

Parses the sizes back from the end of a frame.

Bits 3 and 7 of L are reserved; a length longer than its value needs is refused.

Definition at line 865 of file zxc_common.c.

References ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_SRC_TOO_SMALL, ZXC_FILE_FOOTER_MIN_SIZE, zxc_load_le_n(), ZXC_OK, and zxc_uint_bytes().

Referenced by zxc_read_frame_info(), and zxc_scan_frame().

◆ zxc_read_block_header()

int zxc_read_block_header	(	const uint8_t *	src,
		const size_t	src_size,
		zxc_block_header_t *	bh
	)

Reads and parses a ZXC block header from src.

Extracts the block type, flags, reserved fields, and compressed size from the first ZXC_BLOCK_HEADER_SIZE bytes of src. Multi-byte fields are decoded as little-endian.

Parameters

[in]	src	Source buffer holding the encoded block header.
[in]	src_size	Size of `src` in bytes.
[out]	bh	Block header structure populated with the parsed data.

Returns: ZXC_OK on success, or ZXC_ERROR_SRC_TOO_SMALL if src is smaller than ZXC_BLOCK_HEADER_SIZE.

Reads and parses a ZXC block header from src.

Validates the 8-bit checksum embedded in the header.

Definition at line 703 of file zxc_common.c.

References ZXC_BLOCK_HEADER_SIZE, ZXC_ERROR_BAD_HEADER, ZXC_ERROR_SRC_TOO_SMALL, zxc_hash8(), zxc_le32(), and ZXC_OK.

Referenced by ds_handle_need_block_header(), zxc_dctx_decode_frame(), zxc_seek_read_block(), zxc_stream_decode_job(), and zxc_stream_read_blocks().

◆ zxc_read_file_header()

int zxc_read_file_header	(	const uint8_t *	src,
		const size_t	src_size,
		size_t *	out_block_size,
		int *	out_has_checksum,
		uint32_t *	out_dict_id,
		int *	out_has_seek
	)

Validates and reads the ZXC file header from src.

Checks that the source buffer is large enough to contain a ZXC file header and that the magic word and version number match the expected format.

Parameters

[in]	src	Pointer to the source buffer.
[in]	src_size	Size of the source buffer in bytes.
[out]	out_block_size	Optional pointer that receives the recommended block size. May be `NULL`.
[out]	out_has_checksum	Optional pointer that receives the checksum flag. May be `NULL`.
[out]	out_dict_id	Optional pointer that receives the dictionary ID (0 if none). May be `NULL`.
[out]	out_has_seek	Optional pointer that receives the seek-table flag. May be `NULL`.

Returns: ZXC_OK on success, or a negative error code (e.g. ZXC_ERROR_SRC_TOO_SMALL, ZXC_ERROR_BAD_MAGIC, ZXC_ERROR_BAD_VERSION).

Validates and reads the ZXC file header from src.

Checks the magic word, format version, and 16-bit checksum.

Definition at line 516 of file zxc_common.c.

References ZXC_BLOCK_SIZE_MAX_LOG2, ZXC_CHECKSUM_RAPIDHASH, ZXC_ERROR_BAD_BLOCK_SIZE, ZXC_ERROR_BAD_HEADER, ZXC_ERROR_BAD_MAGIC, ZXC_ERROR_BAD_VERSION, ZXC_ERROR_SRC_TOO_SMALL, ZXC_FILE_CHECKSUM_ALGO_MASK, ZXC_FILE_FLAG_HAS_CHECKSUM, ZXC_FILE_FLAG_HAS_DICTIONARY, ZXC_FILE_FLAG_HAS_SEEK_TABLE, ZXC_FILE_FORMAT_VERSION, ZXC_FILE_HEADER_SIZE, zxc_hash16(), zxc_le16(), zxc_le32(), ZXC_MAGIC_WORD, and ZXC_OK.

Referenced by ds_handle_need_file_header(), zxc_dctx_decode_frame(), zxc_read_frame_info(), zxc_scan_container(), zxc_short_input_verdict(), and zxc_stream_read_frame_header().

◆ zxc_read_frame_info()

int zxc_read_frame_info	(	const uint8_t *	header,
		const uint8_t *	tail,
		const size_t	tail_len,
		const uint64_t	total,
		zxc_frame_info_t *	info,
		size_t *	footer_len
	)

Validates a frame from its header and the end of its bytes: the one check behind zxc_get_frame_info(), its FILE* twin and the size queries.

Parameters

[in]	header	The first ZXC_FILE_HEADER_SIZE bytes.
[in]	tail	The last `tail_len` bytes of the input.
[in]	tail_len	zxc_frame_tail_len of `total`.
[in]	total	Bytes of the whole input.
[out]	info	Filled on success.
[out]	footer_len	Footer bytes, digest included; may be NULL.

Returns: ZXC_OK, or a negative zxc_error_t.

Validates a frame from its header and the end of its bytes: the one check behind zxc_get_frame_info(), its FILE* twin and the size queries.

Header first, as every decoder does; then the footer, whose frame must span total bytes and whose size the blocks could hold.

Definition at line 648 of file zxc_common.c.

References zxc_frame_info_t::block_size, zxc_frame_info_t::compressed_size, zxc_frame_info_t::decompressed_size, zxc_frame_info_t::dict_id, zxc_frame_info_t::digest, zxc_frame_info_t::format_version, zxc_frame_info_t::has_checksum, zxc_frame_info_t::has_seek_table, ZXC_ERROR_CORRUPT_DATA, ZXC_FILE_DIGEST_SIZE, ZXC_FILE_HEADER_SIZE, zxc_footer_dsize_plausible(), zxc_le64(), ZXC_OK, zxc_parse_file_footer(), and zxc_read_file_header().

Referenced by zxc_scan_frame().

◆ zxc_read_ghi_header()

int zxc_read_ghi_header	(	const uint8_t *	src,
		const size_t	len,
		zxc_gnr_header_t *	gh
	)

Reads a GHI sub-header from a buffer.

Parameters

[in]	src	Pointer to the source buffer containing the record data.
[in]	len	Length of the source buffer in bytes.
[out]	gh	Pointer to a zxc_gnr_header_t structure to store the parsed header.

Returns: ZXC_OK on success, or a negative zxc_error_t code on failure.

Reads a GHI sub-header from a buffer.

Definition at line 1008 of file zxc_common.c.

References ZXC_ERROR_SRC_TOO_SMALL, ZXC_GHI_HEADER_BINARY_SIZE, ZXC_OK, and zxc_read_gnr_header().

◆ zxc_read_glo_header_and_desc()

int zxc_read_glo_header_and_desc	(	const uint8_t *	src,
		const size_t	len,
		zxc_gnr_header_t *	gh,
		uint32_t *	lit_comp,
		uint32_t *	tok_comp
	)

Reads a GLO sub-header and its section descriptors from a source buffer.

Sizes absent from the descriptors are reconstructed from the header, so both outputs are always populated.

Parameters

[in]	src	Pointer to the source buffer.
[in]	len	The length of the source buffer available for reading.
[out]	gh	Pointer to the generic header structure to populate.
[out]	lit_comp	Receives the literal section's compressed size.
[out]	tok_comp	Receives the token section's compressed size.

Returns: Bytes consumed (header + table), or a negative zxc_error_t code.

Reads a GLO sub-header and its section descriptors from a source buffer.

Definition at line 965 of file zxc_common.c.

References ZXC_ERROR_SRC_TOO_SMALL, zxc_glo_desc_size(), ZXC_GLO_HEADER_BINARY_SIZE, zxc_le32(), and zxc_read_gnr_header().

◆ zxc_scan_container()

int zxc_scan_container	(	const zxc_scan_src_t *	src,
		size_t	req_chunk,
		zxc_container_info_t *	info
	)

Measures a whole container without decoding: frames from the last back to the first through zxc_scan_frame.

Parameters

[in]	src	Container source.
[in]	req_chunk	Block size every frame must declare, 0 for any.
[out]	info	Totals over the container.

Returns: ZXC_OK, or a negative zxc_error_t; an empty container is ZXC_ERROR_SRC_TOO_SMALL.

Definition at line 613 of file zxc_common.c.

References zxc_frame_info_t::block_size, zxc_frame_info_t::decompressed_size, zxc_frame_info_t::dict_id, zxc_container_info_t::dsize, zxc_container_info_t::first_dict_id, zxc_container_info_t::frames, zxc_container_info_t::uses_dict, ZXC_ERROR_BAD_BLOCK_SIZE, ZXC_ERROR_CORRUPT_DATA, ZXC_FILE_HEADER_SIZE, ZXC_OK, zxc_read_file_header(), zxc_scan_frame(), and zxc_scan_read().

Referenced by zxc_dctx_probe(), zxc_get_decompressed_size(), zxc_probe_without_dst(), and zxc_stream_get_decompressed_size().

◆ zxc_scan_frame()

int zxc_scan_frame	(	const zxc_scan_src_t *	src,
		uint64_t	end,
		uint64_t *	start,
		zxc_frame_info_t *	info,
		size_t *	footer_len
	)

Measures the frame ending at end without decoding: its footer's compressed size gives where it starts.

Parameters

[in]	src	Container source.
[in]	end	Offset just past the frame.
[out]	start	Offset of the frame's header.
[out]	info	Its header and footer, checked like zxc_get_frame_info().
[out]	footer_len	Footer bytes, digest included; may be NULL.

Returns: ZXC_OK, or a negative zxc_error_t.

Definition at line 569 of file zxc_common.c.

References ZXC_ERROR_BAD_MAGIC, ZXC_ERROR_CORRUPT_DATA, ZXC_FILE_HEADER_SIZE, ZXC_FOOTER_MAX_SIZE_WITH_DIGEST, ZXC_FRAME_MIN_SIZE, zxc_frame_tail_len(), ZXC_OK, zxc_parse_file_footer(), zxc_read_frame_info(), zxc_scan_read(), and zxc_short_input_verdict().

Referenced by zxc_get_last_frame_info(), zxc_scan_container(), zxc_scan_whole_frame(), zxc_seek_parse_frame(), and zxc_stream_get_last_frame_info().

◆ zxc_scan_src_mem()

static zxc_scan_src_t zxc_scan_src_mem	(	const uint8_t *	data,
		const size_t	size
	)

inlinestatic

A scan source over size bytes of memory at data.

Definition at line 2199 of file zxc_internal.h.

References zxc_scan_src_s::data, and zxc_scan_src_s::size.

Referenced by zxc_buffer_frame_info(), zxc_dctx_decode_container(), zxc_dctx_probe(), zxc_get_decompressed_size(), zxc_get_last_frame_info(), and zxc_probe_without_dst().

◆ zxc_scan_whole_frame()

int zxc_scan_whole_frame	(	const zxc_scan_src_t *	src,
		zxc_frame_info_t *	info,
		size_t *	footer_len
	)

The frame that must span all of src: zxc_get_frame_info() and its FILE* twin.

The header speaks first, then zxc_scan_frame; a frame starting past offset 0 is ZXC_ERROR_CORRUPT_DATA.

Definition at line 601 of file zxc_common.c.

References ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_SRC_TOO_SMALL, ZXC_FILE_HEADER_SIZE, ZXC_FRAME_MIN_SIZE, ZXC_OK, zxc_scan_frame(), zxc_scan_read(), and zxc_short_input_verdict().

Referenced by zxc_buffer_frame_info(), and zxc_stream_read_frame_info().

◆ zxc_seek_block_count()

static uint64_t zxc_seek_block_count	(	const uint64_t	total_decomp,
		const size_t	block_size
	)

inlinestatic

Blocks in total_decomp bytes of block_size: the seek table's entry count, which the SEK header's field (table size modulo 2^32) cannot give.

Definition at line 1581 of file zxc_internal.h.

References zxc_ctz32().

Referenced by zxc_check_seek_header(), zxc_footer_dsize_plausible(), zxc_inplace_margin(), and zxc_seek_parse_frame().

◆ zxc_seek_table_header()

int zxc_seek_table_header	(	uint8_t *	dst,
		size_t	dst_capacity,
		uint64_t	num_blocks
	)

Writes a seek table's block header for num_blocks entries.

Shared by the writers and by the readers, which compare against it.

Parameters

[out]	dst	Destination, at least ZXC_BLOCK_HEADER_SIZE bytes.
[in]	dst_capacity	Size of `dst`.
[in]	num_blocks	Blocks the table indexes.

Returns: ZXC_BLOCK_HEADER_SIZE, or a negative zxc_error_t.

Definition at line 738 of file zxc_common.c.

References zxc_block_header_t::block_type, zxc_seek_size_field(), zxc_seek_table_bytes(), and zxc_write_block_header().

Referenced by zxc_check_seek_header(), zxc_stream_finish_compress(), zxc_write_empty_frame(), zxc_write_seek_table(), and zxc_write_seek_table_from_blocks().

◆ zxc_seek_write_group()

size_t zxc_seek_write_group	(	uint8_t *	dst,
		uint64_t *	anchor,
		const uint32_t *	sizes,
		uint32_t	cnt
	)

Writes one group (*anchor, then cnt sizes) into dst, which holds ZXC_SEEK_GROUP_BYTES, and advances *anchor past its blocks.

Returns: Bytes written.

Definition at line 770 of file zxc_common.c.

References ZXC_SEEK_ANCHOR_SIZE, ZXC_SEEK_SIZE_ENTRY, zxc_store_le32(), and zxc_store_le64().

Referenced by zxc_stream_finish_compress(), and zxc_write_seek_table().

◆ zxc_seekable_attach_owned_ctx()

void zxc_seekable_attach_owned_ctx	(	zxc_seekable *	s,
		void *	ctx
	)

Hands ownership of a heap-allocated reader context to a seekable handle.

The context will be released via ZXC_FREE when zxc_seekable_free is called on s.

Safe to call exactly once per handle. Intended for thin wrappers that build a zxc_reader_t over their own allocated state (zxc_seekable_open_file) and need that state to outlive the call site.

Parameters

[in,out]	s	Seekable handle returned by zxc_seekable_open_reader.
[in]	ctx	Pointer previously returned by `ZXC_MALLOC` / `ZXC_CALLOC`.

Hands ownership of a heap-allocated reader context to a seekable handle.

Cross-TU hook (declared in zxc_internal.h): ctx is released via ZXC_FREE when zxc_seekable_free runs. Used by zxc_seekable_open_file so its allocated reader state outlives the open call. NULL-safe on s.

Definition at line 1033 of file zxc_seekable.c.

Referenced by zxc_seekable_open_file().

◆ zxc_short_input_verdict()

static int zxc_short_input_verdict	(	const uint8_t *	p,
		const size_t	n
	)

inlinestatic

The verdict on n bytes too short for a frame: the header speaks first, then ZXC_ERROR_SRC_TOO_SMALL.

Definition at line 2172 of file zxc_internal.h.

References ZXC_ERROR_SRC_TOO_SMALL, ZXC_FILE_HEADER_SIZE, ZXC_OK, and zxc_read_file_header().

Referenced by zxc_decompress(), zxc_decompress_dctx(), zxc_scan_frame(), and zxc_scan_whole_frame().

◆ zxc_store_le16()

static void zxc_store_le16	(	void *	p,
		const uint16_t	v
	)

inlinestatic

Writes a 16-bit value little-endian to a possibly unaligned address.

Mirror of zxc_le16(): the memcpy makes the unaligned store defined, and the value is byte-swapped on big-endian hosts so the wire stays LE.

Parameters

[out]	p	Address to write to, at least 2 bytes.
[in]	v	Value, in host order.

Definition at line 1380 of file zxc_internal.h.

Referenced by zxc_dict_save(), zxc_encode_block_glo(), and zxc_file_header_sign().

◆ zxc_store_le32()

static void zxc_store_le32	(	void *	p,
		const uint32_t	v
	)

inlinestatic

Writes a 32-bit value little-endian to a possibly unaligned address.

Mirror of zxc_le32(); see zxc_store_le16() for the memcpy and endianness rationale.

Parameters

[out]	p	Address to write to, at least 4 bytes.
[in]	v	Value, in host order.

Definition at line 1398 of file zxc_internal.h.

Referenced by zxc_compress_chunk_wrapper(), zxc_dict_load(), zxc_dict_save(), zxc_encode_block_ghi(), zxc_seek_write_group(), zxc_write_block_header(), zxc_write_file_header(), zxc_write_glo_header_and_desc(), zxc_write_gnr_header(), and zxc_write_seek_table_from_blocks().

◆ zxc_store_le64()

static void zxc_store_le64	(	void *	p,
		const uint64_t	v
	)

inlinestatic

Writes a 64-bit value little-endian to a possibly unaligned address.

Mirror of zxc_le64(); see zxc_store_le16() for the memcpy and endianness rationale.

Parameters

[out]	p	Address to write to, at least 8 bytes.
[in]	v	Value, in host order.

Definition at line 1416 of file zxc_internal.h.

Referenced by zxc_encode_footer(), zxc_seek_write_group(), and zxc_write_seek_table_from_blocks().

◆ zxc_uint_bytes()

static size_t zxc_uint_bytes ( const uint64_t v )

inlinestatic

Fewest little-endian bytes, 1 to 8, that hold v.

Definition at line 2302 of file zxc_internal.h.

Referenced by zxc_footer_layout(), and zxc_parse_file_footer().

◆ zxc_validate_block_size()

static int zxc_validate_block_size ( const size_t bs )

inlinestatic

Validates a block size.

Must be a power of two in [ZXC_BLOCK_SIZE_MIN, ZXC_BLOCK_SIZE_MAX].

Parameters

[in] bs Block size to validate.

Returns: 1 if valid, 0 otherwise.

Definition at line 1092 of file zxc_internal.h.

References ZXC_BLOCK_SIZE_MAX, and ZXC_BLOCK_SIZE_MIN.

Referenced by zxc_compress(), zxc_compress_cctx(), zxc_create_cctx(), zxc_init_static_cctx(), zxc_init_static_dctx(), zxc_static_cctx_workspace_size(), zxc_static_dctx_workspace_size(), and zxc_stream_compress().

◆ zxc_write_block_header()

int zxc_write_block_header	(	uint8_t *	dst,
		const size_t	dst_capacity,
		const zxc_block_header_t *	bh
	)

Encodes a block header into dst.

Serialises the contents of a zxc_block_header_t structure into a byte array in little-endian format, after checking that dst has sufficient capacity.

Parameters

[out]	dst	Destination buffer.
[in]	dst_capacity	Total capacity of `dst` in bytes.
[in]	bh	Source block header structure to serialise.

Returns: Number of bytes written (ZXC_BLOCK_HEADER_SIZE) on success, or ZXC_ERROR_DST_TOO_SMALL if dst_capacity is insufficient.

Encodes a block header into dst.

Definition at line 684 of file zxc_common.c.

References ZXC_BLOCK_HEADER_SIZE, ZXC_ERROR_DST_TOO_SMALL, zxc_hash8(), and zxc_store_le32().

Referenced by cs_stage_eof(), zxc_check_eof_header(), zxc_compress(), zxc_compress_cctx(), zxc_encode_block_ghi(), zxc_encode_block_glo(), zxc_encode_block_raw(), zxc_seek_table_header(), zxc_stream_finish_compress(), and zxc_write_empty_frame().

◆ zxc_write_file_footer()

int zxc_write_file_footer	(	uint8_t *	dst,
		const size_t	dst_capacity,
		const uint64_t	prefix,
		const uint64_t	src_size,
		const uint64_t	digest,
		const int	checksum_enabled
	)

Writes the footer of a frame whose first prefix bytes precede it.

Returns: Bytes written (ZXC_FILE_FOOTER_MIN_SIZE to ZXC_FILE_FOOTER_MAX_SIZE, plus the digest when checksum_enabled), or ZXC_ERROR_DST_TOO_SMALL.

Writes the footer of a frame whose first prefix bytes precede it.

Definition at line 832 of file zxc_common.c.

References zxc_footer_layout_t::len, zxc_encode_footer(), ZXC_ERROR_DST_TOO_SMALL, and zxc_footer_layout().

Referenced by cs_stage_footer(), zxc_compress(), zxc_compress_cctx(), zxc_stream_finish_compress(), and zxc_write_empty_frame().

◆ zxc_write_file_header()

int zxc_write_file_header	(	uint8_t *	dst,
		const size_t	dst_capacity,
		const size_t	chunk_size,
		const int	has_checksum,
		const uint32_t	dict_id,
		const int	has_seek
	)

Writes the standard ZXC file header into dst.

Stores the magic word (little-endian) and the version number into the provided buffer, after checking that it has sufficient capacity.

Parameters

[out]	dst	Destination buffer.
[in]	dst_capacity	Total capacity of `dst` in bytes.
[in]	chunk_size	Block size to encode in the header.
[in]	has_checksum	Non-zero if the checksum bit must be set.
[in]	dict_id	Dictionary ID (0 = no dictionary).
[in]	has_seek	Non-zero if the archive will carry a SEK block.

Returns: Number of bytes written (ZXC_FILE_HEADER_SIZE) on success, or ZXC_ERROR_DST_TOO_SMALL if dst_capacity is insufficient.

Writes the standard ZXC file header into dst.

Definition at line 486 of file zxc_common.c.

References ZXC_CHECKSUM_RAPIDHASH, ZXC_ERROR_DST_TOO_SMALL, ZXC_FILE_FLAG_HAS_CHECKSUM, ZXC_FILE_FLAG_HAS_DICTIONARY, ZXC_FILE_FLAG_HAS_SEEK_TABLE, ZXC_FILE_FORMAT_VERSION, zxc_file_header_sign(), ZXC_FILE_HEADER_SIZE, zxc_log2_u32(), ZXC_MAGIC_WORD, and zxc_store_le32().

Referenced by cs_stage_file_header(), zxc_compress(), zxc_compress_cctx(), zxc_stream_compress(), and zxc_write_empty_frame().

◆ zxc_write_ghi_header()

int zxc_write_ghi_header	(	uint8_t *	dst,
		const size_t	rem,
		const zxc_gnr_header_t *	gh
	)

Writes a GHI sub-header.

GHI carries no section descriptors.

Parameters

[out]	dst	Pointer to the destination buffer.
[in]	rem	Remaining size available in the destination buffer.
[in]	gh	Pointer to the GNR header structure containing header information.

Returns: The number of bytes written, or a negative error code on failure.

Writes a GHI sub-header.

GHI carries no section descriptors at all: its literals are always RAW (lit_comp == gh->n_literals), its sequence stream is gh->n_sequences * 4 bytes wide, and its extras run from there to the payload end.

Definition at line 997 of file zxc_common.c.

References ZXC_ERROR_DST_TOO_SMALL, ZXC_GHI_HEADER_BINARY_SIZE, and zxc_write_gnr_header().

Referenced by zxc_encode_block_ghi().

◆ zxc_write_glo_header_and_desc()

int zxc_write_glo_header_and_desc	(	uint8_t *	dst,
		const size_t	rem,
		const zxc_gnr_header_t *	gh,
		const uint32_t	lit_comp,
		const uint32_t	tok_comp
	)

Writes a GLO sub-header followed by its section descriptors.

They hold only the two sizes the header cannot imply, and are 0, 4 or 8 bytes wide accordingly.

Parameters

[out]	dst	Pointer to the destination buffer.
[in]	rem	The remaining space in the destination buffer.
[in]	gh	Pointer to the generic header structure to write.
[in]	lit_comp	Compressed size of the literal section.
[in]	tok_comp	Compressed size of the token section.

Returns: The number of bytes written, or a negative error code if the buffer is too small.

Writes a GLO sub-header followed by its section descriptors.

Only the two sizes the header cannot imply are stored: the literal section's compressed size when it is RLE- or entropy-coded, and the token section's when level 7 Huffman-codes it. The decoder derives the rest - literals raw size from n_literals, offsets from n_sequences and enc_off, extras from the payload residue - so those cannot be forged inconsistently.

Definition at line 940 of file zxc_common.c.

References ZXC_ERROR_DST_TOO_SMALL, zxc_glo_desc_size(), ZXC_GLO_HEADER_BINARY_SIZE, zxc_store_le32(), and zxc_write_gnr_header().

Referenced by zxc_encode_block_glo().

Data Structures

Macros

Typedefs

Enumerations

Functions

File Format Constants

Seekable Format Constants

LZ77 Constants

Space-speed section selection

Per-block match splitting (zxc_glo_split_block), a level-table policy

File footer

Detailed Description

Macro Definition Documentation

◆ ZXC_FOOTER_MAX_SIZE_WITH_DIGEST

◆ ZXC_FRAME_MIN_SIZE

◆ ZXC_GLO_SPLIT_CTX_BITS

◆ ZXC_GLO_SPLIT_MIN_MISPREDICT_PCT

◆ ZXC_HUF_BUILD_SCRATCH_SIZE

◆ ZXC_HUF_NUDGE_DP_M

◆ ZXC_HUF_NUDGE_SCRATCH_OFF

◆ ZXC_HUF_NUDGE_SCRATCH_SIZE

◆ ZXC_HUF_PM_LEVEL_BOUND

◆ ZXC_OPTS_BLOCK_SIZE

◆ ZXC_OPTS_DICT_HUF

◆ ZXC_OPTS_DICT_SIZE

◆ ZXC_OPTS_LEVEL

◆ ZXC_PIVCO_SCRATCH_PAD

Typedef Documentation

◆ zxc_glo_split_hist_t

Enumeration Type Documentation

◆ zxc_block_type_t

◆ zxc_section_encoding_t

Function Documentation

◆ zxc_block_is_short_dist_bound()

◆ zxc_block_size_ceil()

◆ zxc_cctx_alloc_entropy_scratch()

◆ zxc_cctx_attach_dict_huf()

◆ zxc_cctx_compute_workspace_size()

◆ zxc_cctx_free()

◆ zxc_cctx_init()

◆ zxc_cctx_init_in_workspace()

◆ zxc_check_eof_header()

◆ zxc_check_file_footer()

◆ zxc_check_seek_header()

◆ zxc_checksum()

◆ zxc_compress_block_at()

◆ zxc_compress_chunk_wrapper()

◆ zxc_container_next()

◆ zxc_copy16()

◆ zxc_copy32()

◆ zxc_ctz32()

◆ zxc_ctz64()

◆ zxc_decompress_chunk_wrapper()

◆ zxc_decompress_chunk_wrapper_dict()

◆ zxc_decompress_chunk_wrapper_safe()

◆ zxc_digest_combine()

◆ zxc_file_header_sign()

◆ zxc_footer_dsize_plausible()

◆ zxc_footer_layout()

◆ zxc_frame_info_copy()

◆ zxc_frame_tail_len()

◆ zxc_get_lz77_params()

◆ zxc_hash16()

◆ zxc_hash8()

◆ zxc_huf_build_code_lengths()

◆ zxc_huf_calc_size()

◆ zxc_huf_calc_size_dict()

◆ zxc_huf_decode_section()

◆ zxc_huf_decode_section_dict()

◆ zxc_huf_dict_tree_build()

◆ zxc_huf_enc_max_code_len()

◆ zxc_huf_encode_section()

◆ zxc_huf_encode_section_dict()

◆ zxc_huf_nudge_code_lengths()

◆ zxc_huf_nudge_cost()

◆ zxc_huf_pack_lengths()

◆ zxc_huf_unpack_lengths()

◆ zxc_le16()

MEMORY & ENDIANNESS HELPERS

◆ zxc_le32()