ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
ra8_arena.h File Reference
E-reader stack

Init-time bump arena – carves per-tier slab backing, zero-heap. More...

#include <stdint.h>
#include "ra8_err.h"
Include dependency graph for ra8_arena.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ra8_arena_t
 Caller-owned bump-arena state over one tier region. More...

Functions

ra8_err_t ra8_arena_init (ra8_arena_t *arena, void *base, uint32_t size)
 Bind a bump arena over a caller-owned tier region.
ra8_err_t ra8_arena_carve (ra8_arena_t *arena, uint32_t bytes, uint32_t align, void **out_ptr)
 Carve an aligned sub-block from the arena (bump; no free).
ra8_err_t ra8_arena_remaining (const ra8_arena_t *arena, uint32_t *out_remaining)
 Report the bytes still available in the arena.

Detailed Description

Init-time bump arena – carves per-tier slab backing, zero-heap.

Tag
[Ring 2 / Core] {World: NS}

Layer 0 of the #147 memory hierarchy, paired with ::ra8_slab. An arena owns one contiguous memory region of a single tier (DTCM, SRAM, or SDRAM) and hands out aligned sub-blocks by bumping a high-water mark. It is an init-time API: there is no free – you carve all the slab backing (and any other fixed buffers) once during bring-up, then never allocate again (NASA Power-of-10 Rule 3). The remaining-bytes query lets the bring-up code fail fast if the budget is over-subscribed.

extern uint8_t __sdram_pool_start[]; // from the linker script
ra8_arena_t sdram = {};
(void)ra8_arena_init(&sdram, __sdram_pool_start, 40U * 1024U * 1024U);
void* frame_backing = nullptr;
(void)ra8_arena_carve(&sdram, 64U * 4096U, 8U, &frame_backing); // 64 x 4 KiB
ra8_slab_t frames = {};
(void)ra8_slab_init(&frames, frame_backing, 64U * 4096U, 4096U);
ra8_arena_carve
ra8_err_t ra8_arena_carve(ra8_arena_t *arena, uint32_t bytes, uint32_t align, void **out_ptr)
Carve an aligned sub-block from the arena (bump; no free).
Definition ra8_arena.c:69
ra8_arena_init
ra8_err_t ra8_arena_init(ra8_arena_t *arena, void *base, uint32_t size)
Bind a bump arena over a caller-owned tier region.
Definition ra8_arena.c:56
ra8_slab_init
ra8_err_t ra8_slab_init(ra8_slab_t *slab, void *buffer, uint32_t buffer_bytes, uint32_t cell_bytes)
Initialise a slab over a caller-owned buffer.
Definition ra8_slab.c:85
ra8_arena_t
Caller-owned bump-arena state over one tier region.
Definition ra8_arena.h:56
ra8_slab_t
Caller-owned state for one fixed-cell pool.
Definition ra8_slab.h:75
Note
Not thread-safe; bring-up runs single-threaded.
Copyright
Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT
Since
0.1.0

Definition in file ra8_arena.h.

Function Documentation

◆ ra8_arena_carve()

ra8_err_t ra8_arena_carve ( ra8_arena_t * arena,
uint32_t bytes,
uint32_t align,
void ** out_ptr )
nodiscard

Carve an aligned sub-block from the arena (bump; no free).

Parameters
[in]arenaInitialised arena.
[in]bytesBlock size to carve (> 0).
[in]alignRequired alignment in bytes (a power of two, >= 1).
[out]out_ptrReceives the aligned block pointer on success.
Returns
ra8_err_t Error code.
Return values
k_ra8_okBlock carved; *out_ptr set.
k_ra8_err_null_ptrarena or out_ptr was NULL.
k_ra8_err_invalid_sizebytes was zero.
k_ra8_err_invalid_argalign was zero or not a power of two.
k_ra8_err_no_memThe aligned block does not fit the remainder.
Precondition
arena was populated by ra8_arena_init.
align is a power of two.
Postcondition
On success *out_ptr is align-aligned with bytes of storage, and arena->used advanced past it.
On any non-ok return the arena is unchanged.
Note
Not thread-safe; init-time use only (there is no matching free).
Since
0.1.0

Definition at line 69 of file ra8_arena.c.

References ra8_arena_t::base, internal_is_pow2(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, ra8_arena_t::size, and ra8_arena_t::used.

Referenced by mem_run_arena().

◆ ra8_arena_init()

ra8_err_t ra8_arena_init ( ra8_arena_t * arena,
void * base,
uint32_t size )
nodiscard

Bind a bump arena over a caller-owned tier region.

Parameters
[out]arenaArena state to populate (zero-initialised by caller).
[in]baseFirst byte of the region (out-lives the arena).
[in]sizeRegion length in bytes.
Returns
ra8_err_t Error code.
Return values
k_ra8_okArena ready (empty).
k_ra8_err_null_ptrarena or base was NULL.
k_ra8_err_invalid_sizesize was zero.
Precondition
base addresses at least size writable bytes.
arena does not alias base.
Postcondition
On success arena->used == 0 and the whole region is available.
On any non-ok return arena is left unbound.
Note
Not thread-safe.
Since
0.1.0

Definition at line 56 of file ra8_arena.c.

References ra8_arena_t::base, k_ra8_err_invalid_size, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, ra8_arena_t::size, and ra8_arena_t::used.

Referenced by mem_run_arena().

◆ ra8_arena_remaining()

ra8_err_t ra8_arena_remaining ( const ra8_arena_t * arena,
uint32_t * out_remaining )
nodiscard

Report the bytes still available in the arena.

Parameters
[in]arenaInitialised arena.
[out]out_remainingReceives size - used.
Returns
ra8_err_t Error code.
Return values
k_ra8_okRemaining bytes reported.
k_ra8_err_null_ptrarena or out_remaining was NULL.
Precondition
arena was populated by ra8_arena_init.
out_remaining is writable.
Postcondition
*out_remaining == arena->size - arena->used.
No arena state is mutated.
Note
Thread-safe with respect to a quiescent arena (pure read).
Since
0.1.0

Definition at line 94 of file ra8_arena.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, ra8_arena_t::size, and ra8_arena_t::used.

Referenced by mem_run_arena().