First-party porting header for the vendored xz-embedded decoder. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "unarch_xz_pool.h"
#include "xz.h"

Include dependency graph for xz_config.h:

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

Macros
#define	XZ_DEC_PREALLOC
	Enable xz-embedded's preallocated-dictionary streaming mode.
#define	XZ_USE_CRC64
	Verify CRC64 block/stream checks (the xz(1) default).
#define	kmalloc(size, flags)
	xz-embedded allocator seam -> zero-heap bump arena (state structs).
#define	kfree(ptr)
	xz-embedded free seam – no-op under arena semantics.
#define	vmalloc(size)
	xz-embedded large-allocation seam (dictionary) -> same bump arena.
#define	vfree(ptr)
	xz-embedded large-free seam – no-op under arena semantics.
#define	memeq(a, b, size)
	Byte-equality shim the SOUP uses for magic/footer comparison.
#define	memzero(buf, size)
	Zero-fill shim the SOUP uses to reset decoder state.
#define	min(x, y)
	Untyped minimum shim used by the SOUP's buffer clamping.
#define	min_t(type, x, y)
	Typed minimum shim used by the SOUP's buffer clamping.
#define	fallthrough [[fallthrough]]
	Explicit switch-case fall-through marker for the SOUP sources.
#define	__always_inline [[gnu::always_inline]] inline
	Kernel-style force-inline marker used by the SOUP hot paths.
#define	get_unaligned_le32(buf)
	SOUP porting alias onto ra8_xz_cfg_get_unaligned_le32.
#define	get_le32(buf)
	SOUP porting alias: aligned LE32 load via the unaligned helper.

Enumerations
enum	ra8_xz_cfg_shift_t : uint8_t { k_ra8_xz_cfg_shift_b1 = 8U , k_ra8_xz_cfg_shift_b2 = 16U , k_ra8_xz_cfg_shift_b3 = 24U }
	Byte-lane shift distances for the little-endian load shim. More...

Functions
static uint32_t	ra8_xz_cfg_get_unaligned_le32 (const uint8_t *buf)
	Load an unaligned little-endian 32-bit value byte by byte.

Detailed Description

First-party porting header for the vendored xz-embedded decoder.

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

xz-embedded (SOUP, apps/shared_libs/third_party/xz_embedded/) is written against the Linux kernel environment; outside the kernel its private header includes a platform-supplied "xz_config.h" for the allocator, byte-order, and compiler shims. This is that platform header for ra8-firmware. It exists so the vendored tree stays byte-identical to upstream (no local patches; the SBOM records modified: false) while the decoder's allocations route through the zero-heap bump arena in unarch_xz_pool.h (NASA P10 Rule 3 – this firmware traps _sbrk).

The macro names below (kmalloc, memeq, min_t, ...) are not this project's choice: they are the exact porting contract the SOUP sources consume, so they cannot be renamed to project conventions. Every macro here is the allowed "conditional compilation / porting seam" kind – none defines a bare integer constant.

Feature selection (compile-time, decode-only):

XZ_DEC_PREALLOC only: the zero-growth streaming mode the wrapper uses (decoder state + dictionary allocated once at init from the caller scratch). XZ_DEC_DYNALLOC is deliberately NOT defined: it would grow the dictionary on demand from hostile header values. XZ_DEC_SINGLE is likewise not defined: no consumer decodes from a fully-resident input buffer, and every enabled mode is dead weight.
XZ_USE_CRC64: verify the CRC64 integrity check that xz(1) emits by default; without it every default-created .xz would be rejected or ride unverified.
No XZ_DEC_* BCJ filter is enabled: e-reader content is data, not executables, so a stream using a BCJ filter is rejected fail-closed by the decoder (XZ_OPTIONS_ERROR).

Note: Include-path only for the vendored xz-embedded translation units and the first-party XZ wrapper; nothing else in the tree includes this.

See also: unarch_xz_pool.h The bump arena kmalloc / vmalloc map onto.; unarch_xz.h The bounded decode wrapper over the SOUP.; docs/SOUP/xz_embedded.md Qualification record for the vendored tree.

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

Since: Version 0.1.0

Definition in file xz_config.h.

Macro Definition Documentation

◆ __always_inline

#define __always_inline [[gnu::always_inline]] inline

Kernel-style force-inline marker used by the SOUP hot paths.

Always inline.

Kept as a plain attribute-inline mapping; the decoder is fast enough on the M85 without further tuning.

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 194 of file xz_config.h.

◆ fallthrough

#define fallthrough [[fallthrough]]

Explicit switch-case fall-through marker for the SOUP sources.

Fallthrough.

Maps to the C23 attribute so -Wimplicit-fallthrough stays meaningful inside the vendored decoder.

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 181 of file xz_config.h.

◆ get_le32

#define get_le32 ( buf )

Value:

ra8_xz_cfg_get_unaligned_le32(buf)

ra8_xz_cfg_get_unaligned_le32

static uint32_t ra8_xz_cfg_get_unaligned_le32(const uint8_t *buf)

Load an unaligned little-endian 32-bit value byte by byte.

Definition xz_config.h:224

SOUP porting alias: aligned LE32 load via the unaligned helper.

Upstream uses the generic unaligned load for aligned accesses too; this keeps that behaviour.

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 248 of file xz_config.h.

◆ get_unaligned_le32

#define get_unaligned_le32 ( buf )

Value:

ra8_xz_cfg_get_unaligned_le32(buf)

SOUP porting alias onto ra8_xz_cfg_get_unaligned_le32.

Kernel-contract name for the unaligned LE32 load.

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 238 of file xz_config.h.

◆ kfree

#define kfree ( ptr )

Value:

((void)(ptr))

xz-embedded free seam – no-op under arena semantics.

The decoder frees only at xz_dec_end, immediately before the wrapper resets the whole arena, so individual frees are void.

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 107 of file xz_config.h.

◆ kmalloc

#define kmalloc	(		size,
			flags )

Value:

unarch_xz_pool_alloc((uint32_t)(size))

unarch_xz_pool_alloc

void * unarch_xz_pool_alloc(uint32_t size)

Bump-allocate size bytes from the installed arena.

Definition unarch_xz_pool.c:84

xz-embedded allocator seam -> zero-heap bump arena (state structs).

The flags argument is kernel GFP noise and is discarded. A NULL return makes the decoder abort its init cleanly, which the wrapper maps to a bounded ra8_err_t (fail-closed).

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 97 of file xz_config.h.

◆ memeq

#define memeq	(	a,
		b,
		size )

Value:

(memcmp((a), (b), (size)) == 0)

memcmp

int memcmp(const void *a, const void *b, size_t n)

Compare bytes in two memory areas.

Definition ra8_freestanding_mem.c:136

Byte-equality shim the SOUP uses for magic/footer comparison.

Thin memcmp == 0 wrapper (code de-duplication macro).

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 135 of file xz_config.h.

Referenced by unarch_xz_magic().

◆ memzero

#define memzero	(		buf,
			size )

Value:

memset((buf), 0, (size))

memset

void * memset(void *dst, int value, size_t n)

Fill memory with a constant byte value.

Definition ra8_freestanding_mem.c:45

Zero-fill shim the SOUP uses to reset decoder state.

Thin memset(0) wrapper (code de-duplication macro).

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 144 of file xz_config.h.

◆ min

#define min	(		x,
			y )

Value:

(((x) < (y)) ? (x) : (y))

Untyped minimum shim used by the SOUP's buffer clamping.

Minimum.

Evaluates to the smaller of x and y, exactly as the kernel macro the sources were written against (both operands are always same-typed at the call sites).

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 157 of file xz_config.h.

Referenced by internal_sort_by_chapter_num(), and zoom_scale_cycle().

◆ min_t

#define min_t	(	type,
		x,
		y )

Value:

(((type)(x) < (type)(y)) ? (type)(x) : (type)(y))

Typed minimum shim used by the SOUP's buffer clamping.

Evaluates to the smaller of x and y after casting both to type, exactly as the kernel macro the sources were written against.

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 169 of file xz_config.h.

◆ vfree

#define vfree ( ptr )

Value:

((void)(ptr))

xz-embedded large-free seam – no-op under arena semantics.

See kfree; the arena reset reclaims everything at once.

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 126 of file xz_config.h.

◆ vmalloc

#define vmalloc ( size )

Value:

unarch_xz_pool_alloc((uint32_t)(size))

xz-embedded large-allocation seam (dictionary) -> same bump arena.

Only the XZ_PREALLOC dictionary comes through here; its size is policy-bounded by the wrapper before init.

Note: Name fixed by the SOUP porting contract; do not rename.

Since: Version 0.1.0

Definition at line 117 of file xz_config.h.

◆ XZ_DEC_PREALLOC

#define XZ_DEC_PREALLOC

Enable xz-embedded's preallocated-dictionary streaming mode.

Multi-call decoding with the decoder state and dictionary allocated once at init (from the caller scratch via the pool) and never grown. The only mode the unarch_xz wrapper uses; XZ_DEC_SINGLE / XZ_DEC_DYNALLOC stay disabled.

Note: Build-configuration flag consumed by the SOUP sources.

Since: Version 0.1.0

Definition at line 74 of file xz_config.h.

◆ XZ_USE_CRC64

#define XZ_USE_CRC64

Verify CRC64 block/stream checks (the xz(1) default).

Compiles xz_crc64.c support in so default-created archives are integrity-verified instead of rejected as unsupported.

Note: Build-configuration flag consumed by the SOUP sources.

Since: Version 0.1.0

Definition at line 84 of file xz_config.h.

Enumeration Type Documentation

◆ ra8_xz_cfg_shift_t

enum ra8_xz_cfg_shift_t : uint8_t

Byte-lane shift distances for the little-endian load shim.

Named per the no-magic-numbers rule; used only by ra8_xz_cfg_get_unaligned_le32.

Since: Version 0.1.0

Enumerator
k_ra8_xz_cfg_shift_b1	Second byte lane shift.
k_ra8_xz_cfg_shift_b2	Third byte lane shift.
k_ra8_xz_cfg_shift_b3	Fourth byte lane shift.

Definition at line 204 of file xz_config.h.

Function Documentation

◆ ra8_xz_cfg_get_unaligned_le32()

uint32_t ra8_xz_cfg_get_unaligned_le32 ( const uint8_t * buf )

inlinestatic

Load an unaligned little-endian 32-bit value byte by byte.

Portable (alignment- and endian-safe) implementation of the kernel helper the SOUP calls for CRC and header fields.

Parameters

[in] buf Source bytes (>= 4 readable).

Returns: The 32-bit value assembled little-endian from buf[0..3].

Return values

uint32_t Any value; pure assembly of the four input bytes.

Precondition: buf addresses at least four readable bytes.; No alignment requirement on buf.

Postcondition: No state is modified (pure read).; The result depends only on the four input bytes.

Note: Thread-safe: pure read.

Since: Version 0.1.0

Definition at line 224 of file xz_config.h.

References k_ra8_xz_cfg_shift_b1, k_ra8_xz_cfg_shift_b2, and k_ra8_xz_cfg_shift_b3.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ __always_inline

◆ fallthrough

◆ get_le32

◆ get_unaligned_le32

◆ kfree

◆ kmalloc

◆ memeq

◆ memzero

◆ min

◆ min_t

◆ vfree

◆ vmalloc

◆ XZ_DEC_PREALLOC

◆ XZ_USE_CRC64

Enumeration Type Documentation

◆ ra8_xz_cfg_shift_t

Function Documentation

◆ ra8_xz_cfg_get_unaligned_le32()