Bump-arena implementation behind xz-embedded's allocator seam. More...

#include "unarch_xz_pool.h"
#include "ra8_check.h"

Include dependency graph for unarch_xz_pool.c:

Functions
ra8_err_t	unarch_xz_pool_install (void *base, uint32_t len)
	Install a caller-owned scratch buffer as the XZ allocation arena.
void	unarch_xz_pool_reset (void)
	Release the installed arena (invalidates every pool allocation).
void *	unarch_xz_pool_alloc (uint32_t size)
	Bump-allocate `size` bytes from the installed arena.
uint32_t	unarch_xz_pool_used (void)
	Bytes currently bump-allocated from the installed arena.

Variables
static uint8_t *	s_pool_base = nullptr
	Start of the installed arena (NULL when uninstalled).
static uint32_t	s_pool_len = 0U
	Length of the installed arena in bytes (0 when uninstalled).
static uint32_t	s_pool_off = 0U
	Bump cursor: bytes consumed from the installed arena.

Detailed Description

Bump-arena implementation behind xz-embedded's allocator seam.

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

See unarch_xz_pool.h for the contract. The arena is three module statics (base, length, cursor); install/reset pairs are strictly nested and the single-threaded reader loop is the only client. Alignment is enforced on install (caller buffer) and on every bump (request rounding), so the vendored decoder's uint64_t-bearing structs are always aligned.

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

Since: Version 0.1.0

Definition in file unarch_xz_pool.c.

Function Documentation

◆ unarch_xz_pool_alloc()

void * unarch_xz_pool_alloc ( uint32_t size )

nodiscard

Bump-allocate size bytes from the installed arena.

The kmalloc / vmalloc target for the vendored decoder (via the first-party xz_config.h). Returns 8-aligned storage carved from the installed scratch, or NULL when no arena is installed, the request is zero, or the remaining space is too small – xz-embedded treats a NULL return as allocation failure and aborts its init cleanly (the wrapper maps that to a bounded ra8_err_t), so exhaustion fails closed.

Parameters

[in] size Bytes requested (> 0).

Returns: Pointer to size bytes of 8-aligned storage, or NULL.

Return values

NULL	No arena installed, zero `size`, or arena exhausted.

Precondition: unarch_xz_pool_install succeeded (else NULL is returned).; size is non-zero (else NULL is returned).

Postcondition: A non-NULL result stays valid until unarch_xz_pool_reset.; The bump cursor advanced by the aligned request size.

Note: Not thread-safe. Frees are no-ops (arena semantics).

See also: unarch_xz_pool_used()

Since: Version 0.1.0

Definition at line 84 of file unarch_xz_pool.c.

References k_unarch_xz_pool_align, s_pool_base, s_pool_len, and s_pool_off.

◆ unarch_xz_pool_install()

ra8_err_t unarch_xz_pool_install	(	void *	base,
		uint32_t	len )

nodiscard

Install a caller-owned scratch buffer as the XZ allocation arena.

Binds [base, base + len) as the arena xz-embedded's kmalloc / vmalloc calls bump from. Refused when an arena is already installed (strictly nested wrapper usage) so two concurrent XZ decodes cannot silently share state.

Parameters

[in]	base	Scratch buffer start (non-NULL, 8-byte aligned).
[in]	len	Scratch buffer length in bytes (> 0).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Arena installed; allocations may begin.
k_ra8_err_null_ptr	`base` was NULL.
k_ra8_err_invalid_size	`len` was 0 or `base` was misaligned.
k_ra8_err_busy	An arena is already installed.

Precondition: base is aligned to k_unarch_xz_pool_align.; No other XZ decode is in flight (single-threaded reader loop).

Postcondition: On k_ra8_ok the pool serves unarch_xz_pool_alloc calls.; On any error the pool state is unchanged.

Note: Not thread-safe.

See also: unarch_xz_pool_reset()

Since: Version 0.1.0

Definition at line 57 of file unarch_xz_pool.c.

References k_ra8_err_busy, k_ra8_err_invalid_size, k_ra8_ok, k_unarch_xz_pool_align, RA8_CHECK_NULL_PTR, s_pool_base, s_pool_len, and s_pool_off.

Referenced by unarch_xz_stream_begin().

◆ unarch_xz_pool_reset()

void unarch_xz_pool_reset ( void )

Release the installed arena (invalidates every pool allocation).

Unbinds the arena and zeroes the bump cursor. Idempotent: calling with no arena installed is a no-op, so teardown paths may call it unconditionally.

Precondition: Any pointers previously handed out are dead after this returns.; The owning decode (xz_dec_end) has finished with them.

Postcondition: The pool is uninstalled; unarch_xz_pool_alloc returns NULL.; A fresh unarch_xz_pool_install may follow.

Note: Not thread-safe.

See also: unarch_xz_pool_install()

Since: Version 0.1.0

Definition at line 77 of file unarch_xz_pool.c.

References s_pool_base, s_pool_len, and s_pool_off.

Referenced by unarch_xz_stream_begin(), and unarch_xz_stream_end().

◆ unarch_xz_pool_used()

uint32_t unarch_xz_pool_used ( void )

nodiscard

Bytes currently bump-allocated from the installed arena.

Introspection for tests and RAM-high-water assertions: the exact number of scratch bytes the current decode has consumed. Zero when no arena is installed.

Returns: Consumed bytes (aligned sum of every allocation so far).

Return values

0	No arena installed or nothing allocated yet.

Precondition: None – safe to call in any pool state.; No allocation races (single-threaded reader loop).

Postcondition: No state is modified (pure read).; The result is monotonic between install and reset.

Note: Not thread-safe.

See also: unarch_xz_pool_alloc()

Since: Version 0.1.0

Definition at line 105 of file unarch_xz_pool.c.

References s_pool_base, and s_pool_off.

Variable Documentation

◆ s_pool_base

uint8_t* s_pool_base = nullptr

static

Start of the installed arena (NULL when uninstalled).

Set by unarch_xz_pool_install, cleared by unarch_xz_pool_reset; every allocation is carved from [s_pool_base, s_pool_base + s_pool_len).

Note: Module-private; mutate only through the install/reset API.

Warning: Never modify directly – the cursor invariant depends on it.

Since: Version 0.1.0

Definition at line 34 of file unarch_xz_pool.c.

Referenced by unarch_xz_pool_alloc(), unarch_xz_pool_install(), unarch_xz_pool_reset(), and unarch_xz_pool_used().

◆ s_pool_len

uint32_t s_pool_len = 0U

static

Length of the installed arena in bytes (0 when uninstalled).

Upper bound for the bump cursor s_pool_off.

Note: Module-private; mutate only through the install/reset API.

Warning: Never modify directly – the cursor invariant depends on it.

Since: Version 0.1.0

Definition at line 44 of file unarch_xz_pool.c.

Referenced by unarch_xz_pool_alloc(), unarch_xz_pool_install(), and unarch_xz_pool_reset().

◆ s_pool_off

uint32_t s_pool_off = 0U

static

Bump cursor: bytes consumed from the installed arena.

Invariant s_pool_off <= s_pool_len; advances only in unarch_xz_pool_alloc by 8-aligned amounts.

Note: Module-private; mutate only through the pool API.

Warning: Never modify directly – outstanding pointers depend on it.

Since: Version 0.1.0

Definition at line 55 of file unarch_xz_pool.c.

Referenced by unarch_xz_pool_alloc(), unarch_xz_pool_install(), unarch_xz_pool_reset(), and unarch_xz_pool_used().

Functions

Variables

Detailed Description

Function Documentation

◆ unarch_xz_pool_alloc()

◆ unarch_xz_pool_install()

◆ unarch_xz_pool_reset()

◆ unarch_xz_pool_used()

Variable Documentation

◆ s_pool_base

◆ s_pool_len

◆ s_pool_off