Thin adapter exposing an ra8_io block device as an ra8_vsource reader. More...

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

Include dependency graph for ra8_io_blockdev_vsource.h:

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

Data Structures
struct	ra8_io_blockdev_vsource_ctx_t
	Caller-owned adapter context binding a block device to a vsource read. More...

Functions
ra8_err_t	ra8_io_blockdev_vsource_init (ra8_io_blockdev_vsource_ctx_t ctx, const ra8_io_blockdev_t bd)
	Bind a block device into a vsource adapter context.
ra8_err_t	ra8_io_blockdev_vsource_read (void ctx, uint64_t offset, uint8_t buf, uint32_t len)
	Read len bytes at byte offset from the bound block device.

Detailed Description

Thin adapter exposing an ra8_io block device as an ra8_vsource reader.

Tag: [Ring 4 / PAL] {World: NS}

The #147 page cache (Layer 2, ra8_vmem) pages objects in through a Layer-1 object-source registry (ra8_vsource, Ring 2 / Core). That registry binds each paged object to a generic byte-offset read callback of type ra8_vsource_read_fn so the cache stays free of any storage dependency. A block device (ra8_io_blockdev_t, Ring 4 / PAL) speaks 512-byte logical blocks addressed by LBA, not byte offsets.

This file is the sanctioned bridge between the two seams. It exposes a bound block device as a read-only ra8_vsource_read_fn, performing the LBA<->byte translation once so apps wiring a block device into the page cache via ra8_vsource_add_paged do not re-roll that arithmetic inline.

Ring direction

This adapter lives in ra8_io (Ring 4) and depends on both ra8_vsource.h (Ring 2) and ra8_io_blockdev.h (Ring 4). A Ring-4 file depending on a Ring-2 header is allowed; the reverse – making Ring-2 ra8_vsource depend on Ring-4 ra8_io_blockdev – is forbidden because it would invert ring ordering (see docs/RING_AND_WORLD.md). The two storage seams are kept distinct on purpose: ra8_io_blockdev is read/write/erase at Ring 4; ra8_vsource is a read-only byte-offset view at Ring 2. This adapter is the intentional, ring-respecting bridge, not a sign the seams should be unified.

Bounce buffer

Reads that are not sector-aligned, or that do not cover a whole number of sectors, are serviced through a one-sector bounce buffer held inside the caller-owned context (ra8_io_blockdev_vsource_ctx_t). No dynamic allocation occurs (NASA P10 Rule 3); the caller owns the context and it must out-live every read made through it.

static ra8_io_blockdev_vsource_ctx_t s_vsrc_ctx;
(void)ra8_io_blockdev_vsource_init(&s_vsrc_ctx, &bd);
 
uint32_t oid = 0;
(void)ra8_vsource_add_paged(&vs, ra8_io_blockdev_vsource_read, &s_vsrc_ctx,
                           0U, file_size_bytes, &oid);

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

Since: 0.1.0

Definition in file ra8_io_blockdev_vsource.h.

Function Documentation

◆ ra8_io_blockdev_vsource_init()

ra8_err_t ra8_io_blockdev_vsource_init	(	ra8_io_blockdev_vsource_ctx_t *	ctx,
		const ra8_io_blockdev_t *	bd )

nodiscard

Bind a block device into a vsource adapter context.

Records bd in ctx so ra8_io_blockdev_vsource_read can service byte-offset reads against it. No device access occurs here; the device is only touched on the first read. No allocation occurs.

Parameters

[out]	ctx	Caller-owned adapter context (zero-initialised by the caller).
[in]	bd	Bound block-device handle to expose as a read-only source.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Adapter bound; ctx is usable.
k_ra8_err_null_ptr	ctx or bd was NULL.

Precondition: bd has a backend bound and out-lives every read through ctx.; ctx out-lives every read made through it.

Postcondition: On success ctx->bd == bd.; On any non-ok return ctx is left unbound.

Note: Not thread-safe with respect to the same context.

See also: ra8_io_blockdev_vsource_read The read callback to register.; ra8_vsource_add_paged Where to wire the callback + context.

Since: 0.1.0

Definition at line 277 of file ra8_io_blockdev_vsource.c.

References ra8_io_blockdev_vsource_ctx_t::bd, k_ra8_ok, memset(), RA8_CHECK_NULL_PTR, s_tag, and ra8_io_blockdev_vsource_ctx_t::scratch.

◆ ra8_io_blockdev_vsource_read()

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

nodiscard

Read len bytes at byte offset from the bound block device.

The ra8_vsource_read_fn-compatible entry point. Translates the absolute byte offset to an LBA + intra-block offset and reads len bytes, splitting the request into three parts as needed: an unaligned head sector, a run of whole aligned sectors read straight into buf, and an unaligned tail sector. The head and tail go through the context's one-sector bounce buffer; the aligned middle is read directly with no copy. Reads that walk past the device end are rejected by the block device, not silently truncated.

Parameters

[in]	ctx	The ra8_io_blockdev_vsource_ctx_t (as a void cookie).
[in]	offset	Absolute byte offset within the device.
[out]	buf	Destination buffer (len writable bytes).
[in]	len	Number of bytes to read.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	len bytes copied into buf.
k_ra8_err_null_ptr	ctx or buf was NULL.
k_ra8_err_out_of_range	offset + len overflows the 64-bit range.
k_ra8_err_*	Any error reported by the block device's read.

Precondition: ctx was populated by ra8_io_blockdev_vsource_init.; buf is writable for len bytes.

Postcondition: On success buf[0 .. len) mirrors the device bytes at offset.; On any non-ok return buf content is unspecified.

Note: Not thread-safe with respect to the same context (uses the shared bounce buffer).

See also: ra8_io_blockdev_vsource_init Bind a device before calling this.

Since: 0.1.0

Definition at line 287 of file ra8_io_blockdev_vsource.c.

References internal_bd_read_head(), internal_bd_read_middle(), internal_bd_read_tail(), k_ra8_err_out_of_range, k_ra8_io_block_size_bytes, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.