Block-device byte-stream sink – buffer bytes into 512-byte sectors. More...

#include "ra8_io_stream_blockdev.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_io_stream_backend.h"

Include dependency graph for ra8_io_stream_blockdev.c:

Enumerations
enum	ra8_io_stream_bd_const_t : uint32_t { k_bd_one_block = 1 , k_bd_pad_byte = 0 }
	Block-device sink constants. More...

Functions
static ra8_err_t	internal_bdsink_commit_sector (ra8_io_stream_blockdev_state_t *st)
	Commit the buffered sector as one logical block and advance the LBA.
static uint32_t	internal_bdsink_fill_chunk (ra8_io_stream_blockdev_state_t st, const uint8_t buf, uint32_t len, uint32_t *done)
	Copy one bounded chunk from the source into the sector buffer.
static ra8_err_t	internal_bdsink_commit_if_full (ra8_io_stream_blockdev_state_t *st)
	Commit the buffered sector iff it is exactly full.
static ra8_err_t	internal_bdsink_write (void ctx, const uint8_t buf, uint32_t len, uint32_t *out_written)
	Block-device sink: buffer bytes, auto-committing full sectors.
static ra8_err_t	internal_bdsink_flush (void *ctx)
	Block-device sink: commit a partial trailing sector (zero-padded).
ra8_err_t	ra8_io_stream_blockdev_init (ra8_io_stream_t s, ra8_io_stream_blockdev_state_t state, const ra8_io_blockdev_t *bd, uint32_t start_lba)
	Bind a block-device stream sink into a caller-owned stream handle.

Variables
static const char *const	s_tag = "ra8_io_stream_blockdev"
	Module log tag.
static const ra8_io_stream_iface_t	s_bd_iface
	Block-device stream sink vtable.

Detailed Description

Block-device byte-stream sink – buffer bytes into 512-byte sectors.

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

Accumulates stream bytes into a sector buffer; a full sector is committed via ra8_io_blockdev_write and the LBA advances. A flush zero-pads and commits the partial trailing sector. The sector buffer lives in the caller-owned state, so there is no allocation.

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

Definition in file ra8_io_stream_blockdev.c.

Enumeration Type Documentation

◆ ra8_io_stream_bd_const_t

enum ra8_io_stream_bd_const_t : uint32_t

Block-device sink constants.

Since: 0.1.0

Enumerator
k_bd_one_block	Single-block transfer count.
k_bd_pad_byte	Pad value for a partial trailing sector.

Definition at line 39 of file ra8_io_stream_blockdev.c.

Function Documentation

◆ internal_bdsink_commit_if_full()

ra8_err_t internal_bdsink_commit_if_full ( ra8_io_stream_blockdev_state_t * st )

static

Commit the buffered sector iff it is exactly full.

Helper for internal_bdsink_write – writes the staged sector through internal_bdsink_commit_sector only when fill has reached one logical block, otherwise it is a no-op. Extracted so internal_bdsink_write stays within the nesting-depth limit.

Parameters

[in] st Block-device sink state.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Sector committed, or none was full yet.
k_ra8_err_*	Propagated from internal_bdsink_commit_sector.

Precondition: st is a populated block-device sink state.; st->fill is in [0, k_ra8_io_block_size_bytes].

Postcondition: On a full buffer the sector is written and fill is reset.; On a partial buffer no I/O occurs and state is unchanged.

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

Since: 0.1.0

Definition at line 148 of file ra8_io_stream_blockdev.c.

References ra8_io_stream_blockdev_state_t::fill, internal_bdsink_commit_sector(), k_ra8_io_block_size_bytes, k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_bdsink_write().

◆ internal_bdsink_commit_sector()

ra8_err_t internal_bdsink_commit_sector ( ra8_io_stream_blockdev_state_t * st )

static

Commit the buffered sector as one logical block and advance the LBA.

Writes the full sector buffer to the device at the current LBA via ra8_io_blockdev_write. On success the LBA advances by one block and the fill counter is reset to zero; on failure the error is returned and the state is left unchanged so the caller can decide how to report it.

Parameters

[in,out] st Block-device sink state with a sector ready to commit.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Sector written; LBA advanced and fill reset.
k_ra8_err_*	Propagated from ra8_io_blockdev_write.

Precondition: st is a populated block-device sink state.; st->sector holds the bytes to commit.

Postcondition: On success st->lba is advanced by one block and st->fill is zero.; On failure st is left unmodified.

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

Since: 0.1.0

Definition at line 68 of file ra8_io_stream_blockdev.c.

References ra8_io_stream_blockdev_state_t::bd, ra8_io_stream_blockdev_state_t::fill, k_bd_one_block, k_ra8_ok, ra8_io_stream_blockdev_state_t::lba, RA8_CHECK_NULL_PTR, RA8_INTERNAL, ra8_io_blockdev_write(), s_tag, and ra8_io_stream_blockdev_state_t::sector.

Referenced by internal_bdsink_commit_if_full(), and internal_bdsink_flush().

◆ internal_bdsink_fill_chunk()

uint32_t internal_bdsink_fill_chunk	(	ra8_io_stream_blockdev_state_t *	st,
		const uint8_t *	buf,
		uint32_t	len,
		uint32_t *	done )

static

Copy one bounded chunk from the source into the sector buffer.

Copies up to a full sector's worth of bytes – limited by both the bytes that remain in the source (len - done) and the room left in the sector buffer – then advances both the fill counter and the consumed count. Performs no device I/O; committing a now-full sector is the caller's responsibility.

Parameters

[in,out]	st	Block-device sink state receiving the bytes.
[in]	buf	Source bytes.
[in]	len	Total number of bytes the caller is streaming.
[in,out]	done	Running consumed-byte count, advanced by the chunk.

Returns: uint32_t Number of bytes copied in this chunk (1..block size).

Return values

k_ra8_io_block_size_bytes	The chunk filled the remaining sector room (source had at least that many bytes left).
other	A value in [1, k_ra8_io_block_size_bytes) when the source (len - *done) is exhausted before the sector fills.

Precondition: st is a populated block-device sink state with room to spare.; buf is readable for len bytes and *done < len.

Postcondition: st->fill and *done are advanced by the returned chunk size.; The returned chunk size never overflows the sector buffer.

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

Since: 0.1.0

Definition at line 110 of file ra8_io_stream_blockdev.c.

References ra8_io_stream_blockdev_state_t::fill, k_ra8_io_block_size_bytes, memcpy(), RA8_INTERNAL, and ra8_io_stream_blockdev_state_t::sector.

Referenced by internal_bdsink_write().

◆ internal_bdsink_flush()

ra8_err_t internal_bdsink_flush ( void * ctx )

static

Block-device sink: commit a partial trailing sector (zero-padded).

If a partial sector is buffered, the remainder is zero-filled and the sector is written as one logical block. A flush with no pending bytes is a no-op.

Parameters

[in] ctx Block-device sink state (as a void cookie).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Pending sector committed (or none pending).
k_ra8_err_null_ptr	ctx was NULL.
k_ra8_err_*	Propagated from ra8_io_blockdev_write.

Precondition: ctx is a populated block-device sink state.; The stream is idle.

Postcondition: On success the device holds every streamed byte (last sector padded).; fill is reset to zero.

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

Since: 0.1.0

Definition at line 229 of file ra8_io_stream_blockdev.c.

References ra8_io_stream_blockdev_state_t::fill, internal_bdsink_commit_sector(), k_bd_pad_byte, k_ra8_io_block_size_bytes, k_ra8_ok, memset(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, s_tag, and ra8_io_stream_blockdev_state_t::sector.

◆ internal_bdsink_write()

ra8_err_t internal_bdsink_write	(	void *	ctx,
		const uint8_t *	buf,
		uint32_t	len,
		uint32_t *	out_written )

static

Block-device sink: buffer bytes, auto-committing full sectors.

Copies bytes into the sector buffer in chunks; whenever the buffer fills it is written as one logical block and the LBA advances. Reports the consumed count.

Parameters

[in]	ctx	Block-device sink state (as a void cookie).
[in]	buf	Source bytes.
[in]	len	Number of bytes to stream.
[out]	out_written	Consumed byte count, or NULL.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	All bytes buffered (full sectors committed).
k_ra8_err_null_ptr	ctx or buf was NULL.
k_ra8_err_*	Propagated from ra8_io_blockdev_write.

Precondition: ctx is a populated block-device sink state.; buf is readable for len bytes.

Postcondition: On success every full sector reached has been written to the device.; *out_written (when provided) holds the consumed count.

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

Since: 0.1.0

Definition at line 184 of file ra8_io_stream_blockdev.c.

References internal_bdsink_commit_if_full(), internal_bdsink_fill_chunk(), k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_io_stream_blockdev_init()

ra8_err_t ra8_io_stream_blockdev_init	(	ra8_io_stream_t *	s,
		ra8_io_stream_blockdev_state_t *	state,
		const ra8_io_blockdev_t *	bd,
		uint32_t	start_lba )

nodiscard

Bind a block-device stream sink into a caller-owned stream handle.

Parameters

[out]	s	Stream handle to bind (zero-initialised by the caller).
[out]	state	Caller-owned sink state to populate.
[in]	bd	Bound block device to stream into.
[in]	start_lba	First logical block address to write.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Sink bound; s is usable.
k_ra8_err_null_ptr	s, state, or bd was NULL.

Precondition: bd is a bound block device that out-lives the stream.; s and state out-live every call made through the stream.

Postcondition: On success s streams bytes onto bd from start_lba.; On any non-ok return s and state are left unbound/untouched.

Note: Not thread-safe with respect to the same stream. Call ra8_io_stream_flush to commit a partial trailing sector.

Since: 0.1.0

Definition at line 247 of file ra8_io_stream_blockdev.c.

References ra8_io_stream_blockdev_state_t::bd, ra8_io_stream_blockdev_state_t::fill, ra8_io_stream_blockdev_state_t::lba, RA8_CHECK_NULL_PTR, ra8_io_stream_bind(), s_bd_iface, and s_tag.

Variable Documentation

◆ s_bd_iface

const ra8_io_stream_iface_t s_bd_iface

static

Initial value:

                                              = {
  .write = internal_bdsink_write,
  .flush = internal_bdsink_flush,
}

Block-device stream sink vtable.

Definition at line 242 of file ra8_io_stream_blockdev.c.

Referenced by ra8_io_stream_blockdev_init().

◆ s_tag

const char* const s_tag = "ra8_io_stream_blockdev"

static

Module log tag.

Definition at line 31 of file ra8_io_stream_blockdev.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_io_stream_bd_const_t

Function Documentation

◆ internal_bdsink_commit_if_full()

◆ internal_bdsink_commit_sector()

◆ internal_bdsink_fill_chunk()

◆ internal_bdsink_flush()

◆ internal_bdsink_write()

◆ ra8_io_stream_blockdev_init()

Variable Documentation

◆ s_bd_iface

◆ s_tag