Heap-free scratch allocator hooks for the vendored libwebp decoder. More...

#include <stddef.h>
#include <stdint.h>

Include dependency graph for ra8_webp_arena.h:

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

Data Structures
struct	ra8_webp_arena_t
	Caller-owned bump arena backing a single WebP decode. More...

Functions
void	ra8_webp_arena_bind (ra8_webp_arena_t *arena)
	Bind `arena` as the active scratch for subsequent decode allocations.
void	ra8_webp_arena_unbind (void)
	Unbind the active arena; subsequent allocation hooks fail with nullptr.
void *	ra8_webp_arena_malloc (size_t n)
	libwebp WebPSafeMalloc hook: bump `n` bytes from the bound arena.
void *	ra8_webp_arena_calloc (size_t nmemb, size_t size)
	libwebp WebPSafeCalloc hook: zeroed `nmemb` * `size` bytes.
void	ra8_webp_arena_free (void *p)
	libwebp WebPSafeFree hook: release a block; auto-reset when none live.

Detailed Description

Heap-free scratch allocator hooks for the vendored libwebp decoder.

libwebp funnels every heap request through WebPSafeMalloc / WebPSafeCalloc / WebPSafeFree in apps/shared_libs/third_party/libwebp/src/utils/ utils.c. The firmware has no heap (_sbrk traps after init), so that file carries a delimited RA8 LOCAL PATCH (documented in docs/SOUP/libwebp.md) that – when built with -DRA8_WEBP_USE_ARENA – redirects those three functions to the hooks below, exactly the way stb_image is fronted by ::ra8_img_arena (see apps/shared_libs/third_party/stb/stb_image_impl.c). This arena is a deliberate sibling of ra8_img_arena rather than a reuse of it: keeping the WebP decoder decoupled from apps/shared_libs/reflow until the #289 band-tile render path lands avoids a premature cross-library dependency, and the WebP path additionally needs a zeroing ra8_webp_arena_calloc that the stb hooks do not expose.

The allocator is a bump arena with reference-counted auto-reset: each ra8_webp_arena_malloc()/_calloc() bumps offset and increments live; each ra8_webp_arena_free() decrements live and, when it reaches zero, rewinds offset to the base. A one-shot WebP decode frees all of its scratch before returning, so the arena fully drains after each decode – no caller bookkeeping, robust to any free order, immune to fragmentation. On exhaustion the malloc hook returns nullptr; libwebp propagates that as a decode failure rather than corrupting memory.

NASA Power-of-10 Rule 3 (no dynamic allocation after init): the backing store is caller-owned static/SRAM/SDRAM storage, never malloc.

[Ring 4 / WebP] {World: NS}

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

Since: 0.1.0

Definition in file ra8_webp_arena.h.

Function Documentation

◆ ra8_webp_arena_bind()

void ra8_webp_arena_bind ( ra8_webp_arena_t * arena )

Bind arena as the active scratch for subsequent decode allocations.

Records arena in a file-static slot and resets it to empty (offset = 0, live = 0). Every ra8_webp_arena_malloc() / _calloc() / _free() until the next ra8_webp_arena_bind() or ra8_webp_arena_unbind() operates on it.

Parameters

[in,out] arena Arena to make active; reset to empty on entry. NULL unbinds (equivalent to ra8_webp_arena_unbind()).

Returns: None.

Precondition: arena, if non-NULL, has base pointing at cap writable bytes.; Called single-threaded around one decode (decoding is not re-entrant).

Postcondition: The active arena is arena and, if non-NULL, it is empty.; A subsequent ra8_webp_arena_malloc() draws from arena.

Note: Not thread-safe: image decoding is single-threaded on this target.

See also: ra8_webp_arena_unbind()

Since: 0.1.0

Definition at line 39 of file ra8_webp_arena.c.

References ra8_webp_arena_t::live, ra8_webp_arena_t::offset, and s_arena.

Referenced by internal_webp_decode_impl().

◆ ra8_webp_arena_calloc()

void * ra8_webp_arena_calloc	(	size_t	nmemb,
		size_t	size )

libwebp WebPSafeCalloc hook: zeroed nmemb * size bytes.

Computes the product with an overflow guard, bump-allocates it via the same path as ra8_webp_arena_malloc(), then zero-fills the block (the arena backing store is reused across decodes and is not pre-zeroed).

Parameters

[in]	nmemb	Element count requested by libwebp.
[in]	size	Per-element size in bytes.

Returns: 16-byte-aligned zeroed pointer into the bound arena, or nullptr.

Return values

nullptr No arena bound, the product overflows size_t, or it does not fit the remaining capacity.

Precondition: Either an arena is bound (then a decode is in progress) or the call fails.; Called single-threaded from the decoder.

Postcondition: On success the returned block is fully zeroed and live is incremented.; On failure the arena state is unchanged.

Note: Not thread-safe: image decoding is single-threaded on this target.

See also: ra8_webp_arena_malloc()

Since: 0.1.0

Definition at line 74 of file ra8_webp_arena.c.

References memset(), and ra8_webp_arena_malloc().

◆ ra8_webp_arena_free()

void ra8_webp_arena_free ( void * p )

libwebp WebPSafeFree hook: release a block; auto-reset when none live.

Decrements the bound arena's live-block count; the bump offset is not tracked per block. When the count reaches zero the arena has fully drained, so the offset rewinds to the base. A nullptr argument, or no bound arena, is ignored.

Parameters

[in] p Pointer to release; nullptr is ignored.

Returns: None.

Precondition: p was returned by ra8_webp_arena_malloc()/_calloc(), or is nullptr.; Called single-threaded from the decoder.

Postcondition: The live-block count is decremented (never below zero).; When the live-block count reaches zero the arena offset rewinds to base.

Note: Not thread-safe: image decoding is single-threaded on this target.

See also: ra8_webp_arena_malloc()

Since: 0.1.0

Definition at line 92 of file ra8_webp_arena.c.

References ra8_webp_arena_t::live, ra8_webp_arena_t::offset, and s_arena.

◆ ra8_webp_arena_malloc()

void * ra8_webp_arena_malloc ( size_t n )

libwebp WebPSafeMalloc hook: bump n bytes from the bound arena.

Rounds n up to the 16-byte alignment, bumps the bound arena's offset, and increments its live-block count. Fails with nullptr when no arena is bound, when n exceeds the capacity, or when the request does not fit the remaining capacity.

Parameters

[in] n Byte count requested by libwebp.

Returns: 16-byte-aligned pointer into the bound arena, or nullptr.

Return values

nullptr No arena bound, or the request does not fit.

Precondition: Either an arena is bound (then a decode is in progress) or the call fails.; Called single-threaded from the decoder.

Postcondition: On success the live-block count is incremented and the offset advances.; On failure the arena state is unchanged.

Note: Not thread-safe: image decoding is single-threaded on this target.

See also: ra8_webp_arena_calloc()

Since: 0.1.0

Definition at line 53 of file ra8_webp_arena.c.

References ra8_webp_arena_t::base, ra8_webp_arena_t::cap, k_ra8_webp_align_mask, ra8_webp_arena_t::live, ra8_webp_arena_t::offset, and s_arena.

Referenced by ra8_webp_arena_calloc().

◆ ra8_webp_arena_unbind()

void ra8_webp_arena_unbind ( void )

Unbind the active arena; subsequent allocation hooks fail with nullptr.

Clears the file-static active-arena slot. Used to fence the libwebp hooks outside a decode so a stray allocation cannot scribble on a stale buffer.

Returns: None.

Precondition: None.; Called single-threaded around one decode.

Postcondition: The active-arena slot is NULL.; A subsequent ra8_webp_arena_malloc() returns nullptr until the next bind.

Note: Not thread-safe: image decoding is single-threaded on this target.

See also: ra8_webp_arena_bind()

Since: 0.1.0

Definition at line 48 of file ra8_webp_arena.c.

References s_arena.

Referenced by internal_webp_decode_impl().

Data Structures

Functions

Detailed Description

Function Documentation

◆ ra8_webp_arena_bind()

◆ ra8_webp_arena_calloc()

◆ ra8_webp_arena_free()

◆ ra8_webp_arena_malloc()

◆ ra8_webp_arena_unbind()