App-domain DEFLATE compress / decompress (zero-heap, firmware-safe). More...

#include <stdint.h>
#include "miniz.h"
#include "ra8_err.h"

Include dependency graph for ra8_compress.h:

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

Enumerations
enum	ra8_compress_const_t : uint32_t { k_ra8_compress_scratch_bytes = (uint32_t)sizeof(tdefl_compressor) }
	Compression scratch sizing. More...

Functions
ra8_err_t	ra8_compress (const uint8_t src, uint32_t src_len, uint8_t out, uint32_t out_cap, void scratch, uint32_t scratch_len, uint32_t out_len)
	Raw-DEFLATE compress src into out.
ra8_err_t	ra8_compress_zlib (const uint8_t src, uint32_t src_len, uint8_t out, uint32_t out_cap, void scratch, uint32_t scratch_len, uint32_t out_len)
	Zlib-wrap and DEFLATE-compress one bounded byte range.
ra8_err_t	ra8_decompress (const uint8_t src, uint32_t src_len, uint8_t out, uint32_t out_cap, uint32_t *out_len)
	Raw-DEFLATE decompress src into out.

Detailed Description

App-domain DEFLATE compress / decompress (zero-heap, firmware-safe).

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

Raw-DEFLATE (RFC 1951, no zlib/gzip header) buffer compression over the vendored miniz, sized for the fabric's .rabook RBKC chunk streams and any compress-on-write / decompress-on-read path.

Both directions are heap-free, which matters because this firmware traps the allocator (_sbrk). Decompression uses tinfl_decompress_mem_to_mem, whose working state lives on miniz's own (SOUP-exempt) stack. Compression needs a ~100 KiB tdefl_compressor, which the caller provides as a scratch buffer – so an app that never compresses pays no RAM, and the caller chooses where the buffer lives (SRAM or SDRAM). The buffer must be at least k_ra8_compress_scratch_bytes and 8-byte aligned.

This header is opt-in: it pulls in miniz, so it is NOT part of the ra8_io.h umbrella. Apps that compress include it directly and add miniz to their ra8_add_app(... LIBS ...).

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

Since: 0.1.0

Definition in file ra8_compress.h.

Enumeration Type Documentation

◆ ra8_compress_const_t

enum ra8_compress_const_t : uint32_t

Compression scratch sizing.

Since: 0.1.0

Enumerator
k_ra8_compress_scratch_bytes	Minimum compress scratch size (one miniz tdefl_compressor).

Definition at line 48 of file ra8_compress.h.

Function Documentation

◆ ra8_compress()

ra8_err_t ra8_compress	(	const uint8_t *	src,
		uint32_t	src_len,
		uint8_t *	out,
		uint32_t	out_cap,
		void *	scratch,
		uint32_t	scratch_len,
		uint32_t *	out_len )

nodiscard

Raw-DEFLATE compress src into out.

Parameters

[in]	src	Bytes to compress.
[in]	src_len	Number of input bytes.
[out]	out	Destination for the compressed stream.
[in]	out_cap	Capacity of out in bytes.
[in]	scratch	Caller buffer >= k_ra8_compress_scratch_bytes, 8-byte aligned (holds the miniz compressor).
[in]	scratch_len	Size of scratch in bytes.
[out]	out_len	Compressed byte count on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Compressed; *out_len set.
k_ra8_err_null_ptr	Any pointer argument was NULL.
k_ra8_err_invalid_size	scratch_len is below the minimum.
k_ra8_err_no_mem	out was too small for the result.
k_ra8_fail	The compressor reported an error.

Precondition: scratch is at least k_ra8_compress_scratch_bytes and 8-aligned.; out is writable for out_cap bytes.

Postcondition: On success out[0 .. *out_len) decompresses back to src.; On any non-ok return out content is unspecified.

Note: Not thread-safe with respect to the same scratch.

Since: 0.1.0

Definition at line 173 of file ra8_compress.c.

References internal_ra8_compress_drive(), internal_ra8_compress_validate(), and k_ra8_ok.

Referenced by internal_encode_tile(), and ra8_vfs_compress_write().

◆ ra8_compress_zlib()

ra8_err_t ra8_compress_zlib	(	const uint8_t *	src,
		uint32_t	src_len,
		uint8_t *	out,
		uint32_t	out_cap,
		void *	scratch,
		uint32_t	scratch_len,
		uint32_t *	out_len )

nodiscard

Zlib-wrap and DEFLATE-compress one bounded byte range.

Uses the same caller-owned tdefl_compressor scratch and bounded output sink as ra8_compress, but emits an RFC 1950 zlib stream (two-byte header plus Adler-32 trailer). This is the wire shape used by each independently compressed chunk in an RBKC .rabook container. Keeping the wrapper choice explicit prevents raw RFC 1951 streams from being mislabeled as zlib data.

Parameters

[in]	src	Bytes to compress.
[in]	src_len	Number of input bytes.
[out]	out	Destination for the zlib stream.
[in]	out_cap	Writable capacity of `out`.
[in]	scratch	Caller buffer for one tdefl_compressor.
[in]	scratch_len	Size of `scratch` in bytes.
[out]	out_len	Receives the complete zlib-stream length.

Returns: Canonical compression status.

Return values

k_ra8_ok	A complete zlib stream was produced.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_invalid_size	Compressor scratch was too small.
k_ra8_err_no_mem	The bounded output could not hold the stream.
k_ra8_fail	The compressor rejected the input.

Precondition: scratch is at least k_ra8_compress_scratch_bytes and 8-byte aligned.; out spans out_cap writable bytes.

Postcondition: On success, inflating out[0..*out_len) as zlib reproduces src.; No allocator is called; all transient state is caller-owned.

Note: Not thread-safe with respect to the same buffers.

Since: 0.1.0

Definition at line 190 of file ra8_compress.c.

References internal_ra8_compress_drive(), internal_ra8_compress_validate(), and k_ra8_ok.

Referenced by internal_write_chunks().

◆ ra8_decompress()

ra8_err_t ra8_decompress	(	const uint8_t *	src,
		uint32_t	src_len,
		uint8_t *	out,
		uint32_t	out_cap,
		uint32_t *	out_len )

nodiscard

Raw-DEFLATE decompress src into out.

Parameters

[in]	src	Compressed stream (raw DEFLATE).
[in]	src_len	Number of input bytes.
[out]	out	Destination for the decompressed bytes.
[in]	out_cap	Capacity of out (must hold the whole result).
[out]	out_len	Decompressed byte count on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Decompressed; *out_len set.
k_ra8_err_null_ptr	Any pointer argument was NULL.
k_ra8_err_no_mem	out was too small, or the stream is corrupt.

Precondition: out is large enough to hold the whole decompressed stream.; src is a raw-DEFLATE stream produced compatibly.

Postcondition: On success out[0 .. *out_len) holds the original bytes.; On any non-ok return out content is unspecified.

Note: Heap-free; not thread-safe with respect to out.

Since: 0.1.0

Definition at line 208 of file ra8_compress.c.

References k_ra8_err_no_mem, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_decode_stream(), and ra8_vfs_compress_read().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_compress_const_t

Function Documentation

◆ ra8_compress()

◆ ra8_compress_zlib()

◆ ra8_decompress()