Virtual-memory object sources – implementation (Layer 1, #147). More...

#include "ra8_vsource.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_check.h"
#include "ra8_err.h"

Include dependency graph for ra8_vsource.c:

Functions
ra8_err_t	ra8_vsource_init (ra8_vsource_t vs, ra8_vsource_obj_t objs, uint32_t cap)
	Initialise an empty source registry over a caller-owned object array.
ra8_err_t	ra8_vsource_add_paged (ra8_vsource_t vs, ra8_vsource_read_fn read, void ctx, uint64_t base, uint64_t size, uint32_t *out_id)
	Register a storage-paged object; returns its object_id.
ra8_err_t	ra8_vsource_add_xip (ra8_vsource_t vs, const uint8_t xip_base, uint64_t size, uint32_t *out_id)
	Register an execute-in-place (memory-mapped) object; returns its id.
ra8_err_t	ra8_vsource_loader (void ctx, uint32_t object_id, uint64_t offset, uint8_t frame, uint32_t frame_bytes)
	Fill a page frame from an object – the ra8_vmem_loader_fn adapter.
ra8_err_t	ra8_vsource_xip_ptr (const ra8_vsource_t vs, uint32_t object_id, uint64_t offset, uint32_t len, const uint8_t *out_ptr)
	Get a direct pointer into an XIP object (no copy, no cache).

Variables
static const char *const	s_tag = "ra8_vsource"
	Module log tag.

Detailed Description

Virtual-memory object sources – implementation (Layer 1, #147).

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

A flat object array indexed by object_id (the assignment order). The loader adapter zeroes the whole frame first, then fills the in-range prefix from the object's backing, so a short tail at the object's end reads back as zeros.

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

Definition in file ra8_vsource.c.

Function Documentation

◆ ra8_vsource_add_paged()

ra8_err_t ra8_vsource_add_paged	(	ra8_vsource_t *	vs,
		ra8_vsource_read_fn	read,
		void *	ctx,
		uint64_t	base,
		uint64_t	size,
		uint32_t *	out_id )

nodiscard

Register a storage-paged object; returns its object_id.

Parameters

[in]	vs	Initialised registry.
[in]	read	Backing read callback.
[in]	ctx	Context for `read`.
[in]	base	Absolute base offset of the object within the backing.
[in]	size	Object length in bytes (> 0).
[out]	out_id	Receives the assigned object_id.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Registered; *out_id set.
k_ra8_err_null_ptr	vs, read, or out_id was NULL.
k_ra8_err_invalid_size	size was zero.
k_ra8_err_no_mem	The registry is full.

Precondition: read reads the object's bytes for offsets in [base, base + size).; vs was populated by ra8_vsource_init.

Postcondition: On success the object is addressable via ra8_vsource_loader.; On any non-ok return the registry is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 42 of file ra8_vsource.c.

References ra8_vsource_t::cap, ra8_vsource_t::count, k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_ok, ra8_vsource_t::objs, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_cache_bind(), internal_cache_open(), internal_prepare(), mem_run_vmem(), and sh_paged_bind().

◆ ra8_vsource_add_xip()

ra8_err_t ra8_vsource_add_xip	(	ra8_vsource_t *	vs,
		const uint8_t *	xip_base,
		uint64_t	size,
		uint32_t *	out_id )

nodiscard

Register an execute-in-place (memory-mapped) object; returns its id.

Parameters

[in]	vs	Initialised registry.
[in]	xip_base	Base pointer of the memory-mapped object.
[in]	size	Object length in bytes (> 0).
[out]	out_id	Receives the assigned object_id.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Registered; *out_id set.
k_ra8_err_null_ptr	vs, xip_base, or out_id was NULL.
k_ra8_err_invalid_size	size was zero.
k_ra8_err_no_mem	The registry is full.

Precondition: xip_base is a readable region of at least size bytes.; vs was populated by ra8_vsource_init.

Postcondition: On success ra8_vsource_xip_ptr returns pointers into the region.; On any non-ok return the registry is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 66 of file ra8_vsource.c.

References ra8_vsource_t::cap, ra8_vsource_t::count, k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_ok, ra8_vsource_t::objs, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_vsource_init()

ra8_err_t ra8_vsource_init	(	ra8_vsource_t *	vs,
		ra8_vsource_obj_t *	objs,
		uint32_t	cap )

nodiscard

Initialise an empty source registry over a caller-owned object array.

Parameters

[out]	vs	Registry to populate (zero-initialised by the caller).
[in]	objs	Object slot array (out-lives the registry).
[in]	cap	Number of slots in `objs` (>= 1).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Registry ready (empty).
k_ra8_err_null_ptr	vs or objs was NULL.
k_ra8_err_invalid_size	cap was zero.

Precondition: objs covers cap entries and out-lives the registry.; vs does not alias objs.

Postcondition: On success vs->count == 0.; On any non-ok return vs is left unbound.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 29 of file ra8_vsource.c.

References ra8_vsource_t::cap, ra8_vsource_t::count, k_ra8_err_invalid_size, k_ra8_ok, ra8_vsource_t::objs, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_cache_bind(), internal_cache_open(), internal_prepare(), mem_run_vmem(), and sh_paged_bind().

◆ ra8_vsource_loader()

ra8_err_t ra8_vsource_loader	(	void *	ctx,
		uint32_t	object_id,
		uint64_t	offset,
		uint8_t *	frame,
		uint32_t	frame_bytes )

nodiscard

Fill a page frame from an object – the ra8_vmem_loader_fn adapter.

Looks up object_id, bounds-checks against the object size, and fills frame from the object's backing (paged read callback, or memcpy for an XIP object). Any tail beyond the object end is zeroed. The signature matches ra8_vmem_loader_fn, so pass vs as the cache's loader_ctx and this function as its loader.

Parameters

[in]	ctx	The ra8_vsource_t registry (as a void cookie).
[in]	object_id	Object to page in.
[in]	offset	Frame-aligned byte offset within the object.
[out]	frame	Destination frame (frame_bytes writable).
[in]	frame_bytes	Frame size in bytes.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Frame filled (zero-padded past the object end).
k_ra8_err_null_ptr	ctx or frame was NULL.
k_ra8_err_out_of_range	object_id is not registered, or offset is at or beyond the object size.
k_ra8_err_*	The read callback's error (paged objects).

Precondition: ctx is a populated ra8_vsource_t.; frame is writable for frame_bytes.

Postcondition: On success frame holds the object's bytes at offset (tail zeroed).; On any non-ok return frame content is unspecified.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 84 of file ra8_vsource.c.

References ra8_vsource_obj_t::base, ra8_vsource_t::count, ra8_vsource_obj_t::ctx, k_ra8_err_out_of_range, k_ra8_ok, memcpy(), memset(), ra8_vsource_t::objs, RA8_CHECK_NULL_PTR, ra8_vsource_obj_t::read, s_tag, ra8_vsource_obj_t::size, and ra8_vsource_obj_t::xip.

Referenced by internal_cache_bind(), internal_cache_open(), internal_vmem_setup(), mem_run_vmem(), and sh_paged_bind().

◆ ra8_vsource_xip_ptr()

ra8_err_t ra8_vsource_xip_ptr	(	const ra8_vsource_t *	vs,
		uint32_t	object_id,
		uint64_t	offset,
		uint32_t	len,
		const uint8_t **	out_ptr )

nodiscard

Get a direct pointer into an XIP object (no copy, no cache).

Parameters

[in]	vs	Initialised registry.
[in]	object_id	An XIP object id.
[in]	offset	Byte offset within the object.
[in]	len	Number of bytes the caller will read.
[out]	out_ptr	Receives the pointer to object[offset].

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Pointer returned.
k_ra8_err_null_ptr	vs or out_ptr was NULL.
k_ra8_err_out_of_range	Unknown id, or offset + len exceeds the size.
k_ra8_err_not_supported	The object is paged, not XIP.

Precondition: vs was populated by ra8_vsource_init.; object_id was registered via ra8_vsource_add_xip.

Postcondition: On success *out_ptr is valid for len bytes.; No registry state is mutated.

Note: Thread-safe with respect to a quiescent registry (pure read).

Since: 0.1.0

Definition at line 110 of file ra8_vsource.c.

References ra8_vsource_t::count, k_ra8_err_not_supported, k_ra8_err_out_of_range, k_ra8_ok, ra8_vsource_t::objs, RA8_CHECK_NULL_PTR, s_tag, ra8_vsource_obj_t::size, and ra8_vsource_obj_t::xip.

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_vsource"

static

Module log tag.

Definition at line 27 of file ra8_vsource.c.

Functions

Variables

Detailed Description

Function Documentation

◆ ra8_vsource_add_paged()

◆ ra8_vsource_add_xip()

◆ ra8_vsource_init()

◆ ra8_vsource_loader()

◆ ra8_vsource_xip_ptr()

Variable Documentation

◆ s_tag