unarch_xz_pool.h File Reference

Caller-owned bump arena backing xz-embedded's allocator seam. More...

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

Include dependency graph for unarch_xz_pool.h:

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

Go to the source code of this file.

Enumerations
enum	unarch_xz_pool_dims_t : uint32_t { k_unarch_xz_pool_align = 8U }
	Alignment and sizing constants for the XZ bump arena. More...

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.

Detailed Description

Caller-owned bump arena backing xz-embedded's allocator seam.

Tag

[Ring 4 / Domain] {World: NS}

The vendored xz-embedded decoder (SOUP, apps/shared_libs/third_party/xz_embedded/) allocates its state through the kernel-style kmalloc / vmalloc seam that its porting header (xz_config.h, first-party) maps onto this pool. This firmware traps the allocator (_sbrk, NASA P10 Rule 3), so the pool is a deterministic bump arena over a caller-provided scratch buffer: the XZ wrapper installs the caller's buffer before xz_dec_init, the decoder's fixed set of init-time allocations bump from it, and the wrapper resets the pool when the decode ends. Frees are no-ops (arena semantics – xz-embedded only frees at xz_dec_end, right before the wrapper resets).

The pool is intentionally module-static and single-client: the e-reader's single-threaded content loop opens one XZ stream at a time, and the wrapper install/reset pairs are strictly nested. A second concurrent install is refused fail-closed.

Note

Not thread-safe; the single-threaded reader loop serialises access.

See also

unarch_xz.h The bounded XZ decode wrapper that installs this pool.

xz_config.h The porting header mapping kmalloc/vmalloc here.

Copyright

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

Since

Version 0.1.0

Definition in file unarch_xz_pool.h.

Enumeration Type Documentation

unarch_xz_pool_dims_t

enum unarch_xz_pool_dims_t : uint32_t

Alignment and sizing constants for the XZ bump arena.

Every allocation is rounded up to k_unarch_xz_pool_align so the decoder's structs (which hold uint64_t fields) are always correctly aligned regardless of request order.

Since

Version 0.1.0

Enumerator
k_unarch_xz_pool_align	Bump-allocation alignment, bytes.

Definition at line 54 of file unarch_xz_pool.h.

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.