Block-device -> ra8_vsource read adapter (LBA<->byte translation). More...

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

Include dependency graph for ra8_io_blockdev_vsource.c:

Data Structures
struct	ra8_io_bd_vsource_cursor_t
	Mutable walk state shared by the head/middle/tail read segments. More...

Enumerations
enum	ra8_io_bd_vsource_const_t : uint32_t { k_ra8_io_bd_vsource_one_block = 1 }
	Adapter layout constants. More...

Functions
static ra8_err_t	internal_bd_read_sector (ra8_io_blockdev_vsource_ctx_t *ctx, uint32_t lba)
	Read one sector at lba into the context bounce buffer.
static ra8_err_t	internal_bd_copy_slice (ra8_io_blockdev_vsource_ctx_t ctx, uint32_t lba, uint32_t in_block, uint32_t n, uint8_t dst)
	Copy a slice out of the bounce buffer after a one-sector read.
static ra8_err_t	internal_bd_read_head (ra8_io_blockdev_vsource_ctx_t ctx, ra8_io_bd_vsource_cursor_t cur, uint64_t block_bytes)
	Service the unaligned head sector of a byte-offset read.
static ra8_err_t	internal_bd_read_middle (ra8_io_blockdev_vsource_ctx_t ctx, ra8_io_bd_vsource_cursor_t cur, uint64_t block_bytes)
	Service the aligned middle of a byte-offset read.
static ra8_err_t	internal_bd_read_tail (ra8_io_blockdev_vsource_ctx_t ctx, ra8_io_bd_vsource_cursor_t cur, uint64_t block_bytes)
	Service the unaligned tail sector of a byte-offset read.
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.

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

Detailed Description

Block-device -> ra8_vsource read adapter (LBA<->byte translation).

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

Implements the read-only bridge declared in ra8_io_blockdev_vsource.h. A byte-offset read is split into an optional unaligned head sector, a run of whole aligned sectors copied straight into the caller's buffer, and an optional unaligned tail sector. The head and tail are serviced through the context's one-sector bounce buffer so only the bytes actually requested reach the caller. Pure block-device access plus memcpy, so it runs identically on host and target.

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

Definition in file ra8_io_blockdev_vsource.c.

Enumeration Type Documentation

◆ ra8_io_bd_vsource_const_t

enum ra8_io_bd_vsource_const_t : uint32_t

Adapter layout constants.

Since: 0.1.0

Enumerator
k_ra8_io_bd_vsource_one_block	Blocks transferred per bounce read.

Definition at line 42 of file ra8_io_blockdev_vsource.c.

Function Documentation

◆ internal_bd_copy_slice()

ra8_err_t internal_bd_copy_slice	(	ra8_io_blockdev_vsource_ctx_t *	ctx,
		uint32_t	lba,
		uint32_t	in_block,
		uint32_t	n,
		uint8_t *	dst )

static

Copy a slice out of the bounce buffer after a one-sector read.

Reads the sector at lba into ctx->scratch, then copies n bytes starting at in_block of that sector into dst. Used for the unaligned head and tail of a byte-offset request, where only part of a sector is wanted.

Parameters

[in]	ctx	Bound adapter context (non-NULL, checked by the caller).
[in]	lba	Logical block address of the sector holding the slice.
[in]	in_block	Byte offset of the slice within the sector (< 512).
[in]	n	Number of bytes to copy (in_block + n <= 512).
[out]	dst	Destination for the n copied bytes.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	n bytes copied into dst.
k_ra8_err_*	Any error reported by the sector read.

Precondition: in_block + n <= k_ra8_io_block_size_bytes.; dst is writable for n bytes.

Postcondition: On success dst[0 .. n) mirrors the device bytes of that slice.; On any non-ok return dst content is unspecified.

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

Since: 0.1.0

Definition at line 105 of file ra8_io_blockdev_vsource.c.

References internal_bd_read_sector(), k_ra8_ok, memcpy(), RA8_INTERNAL, and ra8_io_blockdev_vsource_ctx_t::scratch.

Referenced by internal_bd_read_head(), and internal_bd_read_tail().

◆ internal_bd_read_head()

ra8_err_t internal_bd_read_head	(	ra8_io_blockdev_vsource_ctx_t *	ctx,
		ra8_io_bd_vsource_cursor_t *	cur,
		uint64_t	block_bytes )

static

Service the unaligned head sector of a byte-offset read.

When the request does not begin on a sector boundary, copies the partial leading sector through the bounce buffer and advances the cursor past it. If the request already starts on a boundary this is a no-op returning success. The copy is clamped so a sub-sector request never reads past cur->remain.

Parameters

[in]	ctx	Bound adapter context (non-NULL, checked by caller).
[in,out]	cur	Walk state advanced past the head bytes on success.
[in]	block_bytes	Logical block size in bytes (one sector).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Head serviced (possibly a no-op) and cursor advanced.
k_ra8_err_*	Any error reported by the bounce-buffer read.

Precondition: block_bytes equals the device logical block size and is non-zero.; cur->out is writable for at least cur->remain bytes.

Postcondition: On success the cursor reflects a sector-aligned cur->cur, or remain reached zero.; On any non-ok return the cursor is left unspecified.

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

Since: 0.1.0

Definition at line 169 of file ra8_io_blockdev_vsource.c.

References ra8_io_bd_vsource_cursor_t::cur, internal_bd_copy_slice(), k_ra8_ok, ra8_io_bd_vsource_cursor_t::out, RA8_INTERNAL, and ra8_io_bd_vsource_cursor_t::remain.

Referenced by ra8_io_blockdev_vsource_read().

◆ internal_bd_read_middle()

ra8_err_t internal_bd_read_middle	(	ra8_io_blockdev_vsource_ctx_t *	ctx,
		ra8_io_bd_vsource_cursor_t *	cur,
		uint64_t	block_bytes )

static

Service the aligned middle of a byte-offset read.

Reads every whole sector that fits in the remaining length straight into the caller's buffer with no intermediate copy, then advances the cursor past them. If fewer than one full sector remains this is a no-op returning success.

Parameters

[in]	ctx	Bound adapter context (non-NULL, checked by caller).
[in,out]	cur	Walk state advanced past the whole sectors copied.
[in]	block_bytes	Logical block size in bytes (one sector).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Whole sectors (possibly none) copied and cursor advanced.
k_ra8_err_*	Any error reported by the block device's read.

Precondition: block_bytes equals the device logical block size and is non-zero.; cur->cur is sector-aligned on entry.

Postcondition: On success cur->remain is strictly less than block_bytes.; On any non-ok return the cursor is left unspecified.

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

Since: 0.1.0

Definition at line 221 of file ra8_io_blockdev_vsource.c.

References ra8_io_blockdev_vsource_ctx_t::bd, ra8_io_bd_vsource_cursor_t::cur, k_ra8_ok, ra8_io_bd_vsource_cursor_t::out, RA8_INTERNAL, ra8_io_blockdev_read(), and ra8_io_bd_vsource_cursor_t::remain.

Referenced by ra8_io_blockdev_vsource_read().

◆ internal_bd_read_sector()

ra8_err_t internal_bd_read_sector	(	ra8_io_blockdev_vsource_ctx_t *	ctx,
		uint32_t	lba )

static

Read one sector at lba into the context bounce buffer.

Single-block read into ctx->scratch, used to service the unaligned head and tail of a byte-offset request. Wrapped here so both call sites share one bounds-checked path.

Parameters

[in]	ctx	Bound adapter context (non-NULL, checked by the caller).
[in]	lba	Logical block address of the sector to read.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Sector copied into ctx->scratch.
k_ra8_err_*	Any error reported by the block device's read.

Precondition: ctx->bd is a bound block device.; ctx->scratch is one logical block of writable storage.

Postcondition: On success ctx->scratch holds the sector at lba.; On any non-ok return ctx->scratch content is unspecified.

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

Since: 0.1.0

Definition at line 71 of file ra8_io_blockdev_vsource.c.

References ra8_io_blockdev_vsource_ctx_t::bd, k_ra8_io_bd_vsource_one_block, RA8_INTERNAL, ra8_io_blockdev_read(), and ra8_io_blockdev_vsource_ctx_t::scratch.

Referenced by internal_bd_copy_slice().

◆ internal_bd_read_tail()

ra8_err_t internal_bd_read_tail	(	ra8_io_blockdev_vsource_ctx_t *	ctx,
		ra8_io_bd_vsource_cursor_t *	cur,
		uint64_t	block_bytes )

static

Service the unaligned tail sector of a byte-offset read.

Copies any sub-sector remainder left after the aligned middle through the bounce buffer. By construction the tail always starts on a sector boundary, so the in-block offset is zero. A zero remainder is a no-op returning success.

Parameters

[in]	ctx	Bound adapter context (non-NULL, checked by caller).
[in,out]	cur	Walk state; cur->remain reaches zero on success.
[in]	block_bytes	Logical block size in bytes (one sector).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Tail serviced (possibly a no-op); request fully satisfied.
k_ra8_err_*	Any error reported by the bounce-buffer read.

Precondition: block_bytes equals the device logical block size and is non-zero.; cur->cur is sector-aligned on entry.

Postcondition: On success cur->remain is zero.; On any non-ok return the cursor is left unspecified.

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

Since: 0.1.0

Definition at line 267 of file ra8_io_blockdev_vsource.c.

References ra8_io_bd_vsource_cursor_t::cur, internal_bd_copy_slice(), k_ra8_ok, ra8_io_bd_vsource_cursor_t::out, RA8_INTERNAL, and ra8_io_bd_vsource_cursor_t::remain.

Referenced by ra8_io_blockdev_vsource_read().

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

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_io_blockdev_vsource"

static

Module log tag.

Definition at line 34 of file ra8_io_blockdev_vsource.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_io_bd_vsource_const_t

Function Documentation

◆ internal_bd_copy_slice()

◆ internal_bd_read_head()

◆ internal_bd_read_middle()

◆ internal_bd_read_sector()

◆ internal_bd_read_tail()

◆ ra8_io_blockdev_vsource_init()

◆ ra8_io_blockdev_vsource_read()

Variable Documentation

◆ s_tag