Virtual-memory object sources – the page-cache storage seam (Layer 1, #147). More...

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

Include dependency graph for ra8_vsource.h:

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

Data Structures
struct	ra8_vsource_obj_t
	One registered object's backing (paged or XIP). More...
struct	ra8_vsource_t
	Object-source registry (caller-owned; treat as private). More...

Typedefs
typedef ra8_err_t(*	ra8_vsource_read_fn) (void ctx, uint64_t offset, uint8_t buf, uint32_t len)
	Read len bytes at offset from a paged object's backing.

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).

Detailed Description

Virtual-memory object sources – the page-cache storage seam (Layer 1, #147).

Layer 1 of the #147 memory hierarchy. ::ra8_vmem (Layer 2) pages objects in through a single loader callback keyed by an object_id; a source registry maps each object_id to its backing so one cache can serve many objects of two kinds:

Paged – backed by slow storage (SD/exFAT file, OSPI as data, MRAM, ...). The registry holds a generic read callback (offset -> bytes) so this layer stays free of any storage dependency; the app wires the callback to an ra8_io block device or ra8_fs file. Paged objects are demand-paged through the Layer-2 cache.
XIP – backed by an already memory-mapped, execute-in-place region (OSPI flash). Resident assets (fonts!) cost zero SRAM: ra8_vsource_xip_ptr hands back a real pointer with no copy and no cache frame.

ra8_vsource_loader is the ra8_vmem_loader_fn the cache calls on a miss: it looks up the object, bounds-checks the request, and fills the frame from the object's backing (read callback, or memcpy for an XIP object), zero-padding any tail beyond the object's end.

Boundary with ra8_io_blockdev

This source is read-only and byte-addressed, and lives at [Ring 2 / Core]. The ra8_io block-device fabric (ra8_io_blockdev.h, [Ring 4 / PAL]) is a separate storage seam: read/write/erase over 512-byte LBAs. The two are kept distinct on purpose – a read-only byte view for the page cache versus a read/write block fabric for filesystems – and the split is intentional, not drift. ::ra8_vsource must never depend on ra8_io_blockdev: that would make Ring 2 depend on Ring 4 and invert ring ordering (see docs/RING_AND_WORLD.md). The sanctioned bridge runs the other (allowed) way: the Ring-4 adapter ra8_io_blockdev_vsource.h exposes a block device as a ra8_vsource_read_fn, doing the LBA<->byte translation so apps can wire a block device straight into ra8_vsource_add_paged.

Zero allocation (NASA P10 Rule 3): the caller supplies the object array.

Note: Not thread-safe; the reader serialises access.

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

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

Since: 0.1.0

Definition in file ra8_vsource.h.

Typedef Documentation

◆ ra8_vsource_read_fn

typedef ra8_err_t(* ra8_vsource_read_fn) (void *ctx, uint64_t offset, uint8_t *buf, uint32_t len)

Read len bytes at offset from a paged object's backing.

The storage seam: the app binds this to an ra8_io block device or an ra8_fs file so ::ra8_vsource stays storage-agnostic.

Parameters

[in]	ctx	Opaque backing context registered with the object.
[in]	offset	Absolute byte offset within the backing.
[out]	buf	Destination buffer (len writable bytes).
[in]	len	Number of bytes to read.

Returns: ra8_err_t k_ra8_ok on success; any error aborts the page-in.

Since: 0.1.0

Definition at line 79 of file ra8_vsource.h.

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.

Data Structures

Typedefs

Functions

Detailed Description

Boundary with ra8_io_blockdev

Typedef Documentation

◆ ra8_vsource_read_fn

Function Documentation

◆ ra8_vsource_add_paged()

◆ ra8_vsource_add_xip()

◆ ra8_vsource_init()

◆ ra8_vsource_loader()

◆ ra8_vsource_xip_ptr()