ra8_io_blockdev_ram.c File Reference

RAM block-device backend – a flat buffer as 512-byte logical blocks. More...

#include "ra8_io_blockdev_ram.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_blockdev_backend.h"

Include dependency graph for ra8_io_blockdev_ram.c:

Go to the source code of this file.

Enumerations
enum	ra8_io_ram_const_t : uint32_t {   k_ra8_io_ram_erase_unit_blocks = 1 ,   k_ra8_io_ram_min_blocks = 1 }
	RAM-backend layout constants. More...

Functions
static ra8_err_t	internal_ram_bounds (const ra8_io_blockdev_ram_state_t *st, uint32_t lba, uint32_t count)
	Reject an out-of-range [lba, lba+count) block range.
static ra8_err_t	internal_ram_read (void *ctx, uint32_t lba, uint32_t count, uint8_t *buf)
	RAM backend: read count blocks at lba into buf.
static ra8_err_t	internal_ram_write (void *ctx, uint32_t lba, uint32_t count, const uint8_t *buf)
	RAM backend: write count blocks from buf at lba.
static ra8_err_t	internal_ram_erase (void *ctx, uint32_t lba, uint32_t count)
	RAM backend: erase (zero-fill) count blocks at lba.
static ra8_err_t	internal_ram_get_caps (const void *ctx, ra8_io_blockdev_caps_t *out)
	RAM backend: report medium capabilities.
ra8_err_t	ra8_io_blockdev_ram_init (ra8_io_blockdev_t *bd, ra8_io_blockdev_ram_state_t *state, uint8_t *storage, uint32_t block_count, bool read_only)
	Bind a RAM block-device backend into a caller-owned handle.

Variables
static const char *const	s_tag = "ra8_io_blockdev_ram"
	Module log tag.
static const ra8_io_blockdev_iface_t	s_ram_iface
	RAM backend vtable.

Detailed Description

RAM block-device backend – a flat buffer as 512-byte logical blocks.

Tag

[Ring 4 / PAL] {World: NS}

Reference implementation of ra8_io_blockdev_iface. Reads and writes are bounds-checked memcpys into the caller-owned buffer; erase zero-fills. Pure memory access, so it runs identically on host and target.

Copyright

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

Definition in file ra8_io_blockdev_ram.c.

Enumeration Type Documentation

ra8_io_ram_const_t

enum ra8_io_ram_const_t : uint32_t

RAM-backend layout constants.

Since

0.1.0

Enumerator
k_ra8_io_ram_erase_unit_blocks	One logical block per erase unit.
k_ra8_io_ram_min_blocks	Smallest legal device size.

Definition at line 38 of file ra8_io_blockdev_ram.c.

Function Documentation

internal_ram_bounds()

ra8_err_t internal_ram_bounds ( const ra8_io_blockdev_ram_state_t * st, uint32_t lba, uint32_t count )

static

Reject an out-of-range [lba, lba+count) block range.

Split into two single-condition checks (no compound decision) so the bounds test needs no MC/DC vectors and never underflows block_count - count.

Parameters

[in]	st	RAM backend state.
[in]	lba	First logical block address.
[in]	count	Number of blocks in the range.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Range lies within the device.
k_ra8_err_out_of_range	Range extends past the device capacity.

Precondition

st is non-NULL.

st->block_count reflects the backing buffer size.

Postcondition

No state is mutated.

The return reflects only the range/capacity comparison.

Note

Thread-safe (pure comparison).

Since

0.1.0

Definition at line 69 of file ra8_io_blockdev_ram.c.

References ra8_io_blockdev_ram_state_t::block_count, k_ra8_err_out_of_range, and k_ra8_ok.

Referenced by internal_ram_erase(), internal_ram_read(), and internal_ram_write().

internal_ram_erase()

ra8_err_t internal_ram_erase ( void * ctx, uint32_t lba, uint32_t count )

static

RAM backend: erase (zero-fill) count blocks at lba.

Bounds-checks the range, honours the read-only flag, then zero-fills count * 512 bytes (the RAM erase value).

Parameters

[in]	ctx	RAM backend state (as a void cookie).
[in]	lba	First logical block address.
[in]	count	Number of blocks to erase.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Range zero-filled.
k_ra8_err_null_ptr	ctx was NULL.
k_ra8_err_not_supported	The device is read-only.
k_ra8_err_out_of_range	Range past capacity.

Precondition

ctx is a populated RAM state.

count is non-zero for any observable effect.

Postcondition

On success the range reads back as 0x00.

On failure the backing buffer is untouched.

Note

Not thread-safe with respect to the same device.

Since

0.1.0

Definition at line 197 of file ra8_io_blockdev_ram.c.

References internal_ram_bounds(), k_ra8_err_not_supported, k_ra8_io_block_size_bytes, k_ra8_io_erase_value_zero, k_ra8_ok, memset(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, ra8_io_blockdev_ram_state_t::read_only, s_tag, and ra8_io_blockdev_ram_state_t::storage.

internal_ram_get_caps()

ra8_err_t internal_ram_get_caps ( const void * ctx, ra8_io_blockdev_caps_t * out )

static

RAM backend: report medium capabilities.

Reports a zero-erase medium that needs no erase-before-write, sized by the backing buffer.

Parameters

[in]	ctx	RAM backend state (as a const void cookie).
[out]	out	Capabilities snapshot.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	*out populated.
k_ra8_err_null_ptr	ctx or out was NULL.

Precondition

ctx is a populated RAM state.

out is writable.

Postcondition

On success *out describes a zero-erase, no-erase-required medium.

No state is mutated.

Note

Thread-safe (pure read).

Since

0.1.0

Definition at line 238 of file ra8_io_blockdev_ram.c.

References ra8_io_blockdev_caps_t::block_count, ra8_io_blockdev_ram_state_t::block_count, ra8_io_blockdev_caps_t::erase_unit_blocks, ra8_io_blockdev_caps_t::erase_value, k_ra8_io_block_size_bytes, k_ra8_io_erase_value_zero, k_ra8_io_ram_erase_unit_blocks, k_ra8_ok, ra8_io_blockdev_caps_t::logical_block_bytes, ra8_io_blockdev_caps_t::must_erase_before_write, ra8_io_blockdev_caps_t::program_size_bytes, RA8_CHECK_NULL_PTR, RA8_INTERNAL, ra8_io_blockdev_caps_t::read_only, ra8_io_blockdev_ram_state_t::read_only, and s_tag.

internal_ram_read()

ra8_err_t internal_ram_read ( void * ctx, uint32_t lba, uint32_t count, uint8_t * buf )

static

RAM backend: read count blocks at lba into buf.

Bounds-checks the range, then copies count * 512 bytes from the backing buffer.

Parameters

[in]	ctx	RAM backend state (as a void cookie).
[in]	lba	First logical block address.
[in]	count	Number of blocks to read.
[out]	buf	Destination buffer.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Blocks copied into buf.
k_ra8_err_null_ptr	ctx or buf was NULL.
k_ra8_err_out_of_range	Range past capacity.

Precondition

ctx is a populated RAM state.

buf is writable for count * 512 bytes.

Postcondition

On success buf mirrors the backing buffer.

On failure buf is untouched.

Note

Not thread-safe with respect to the same device.

Since

0.1.0

Definition at line 108 of file ra8_io_blockdev_ram.c.

References internal_ram_bounds(), k_ra8_io_block_size_bytes, k_ra8_ok, memcpy(), RA8_CHECK_NULL_PTR, s_tag, and ra8_io_blockdev_ram_state_t::storage.

Referenced by lx_nor_ram_init().

internal_ram_write()

ra8_err_t internal_ram_write ( void * ctx, uint32_t lba, uint32_t count, const uint8_t * buf )

static

RAM backend: write count blocks from buf at lba.

Bounds-checks the range, honours the read-only flag, then copies count * 512 bytes into the backing buffer.

Parameters

[in]	ctx	RAM backend state (as a void cookie).
[in]	lba	First logical block address.
[in]	count	Number of blocks to write.
[in]	buf	Source buffer.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Blocks copied into the backing buffer.
k_ra8_err_null_ptr	ctx or buf was NULL.
k_ra8_err_not_supported	The device is read-only.
k_ra8_err_out_of_range	Range past capacity.

Precondition

ctx is a populated RAM state.

buf is readable for count * 512 bytes.

Postcondition

On success the backing buffer reflects buf.

On failure the backing buffer is untouched.

Note

Not thread-safe with respect to the same device.

Since

0.1.0

Definition at line 152 of file ra8_io_blockdev_ram.c.

References internal_ram_bounds(), k_ra8_err_not_supported, k_ra8_io_block_size_bytes, k_ra8_ok, memcpy(), RA8_CHECK_NULL_PTR, ra8_io_blockdev_ram_state_t::read_only, s_tag, and ra8_io_blockdev_ram_state_t::storage.

ra8_io_blockdev_ram_init()

ra8_err_t ra8_io_blockdev_ram_init ( ra8_io_blockdev_t * bd, ra8_io_blockdev_ram_state_t * state, uint8_t * storage, uint32_t block_count, bool read_only )

nodiscard

Bind a RAM block-device backend into a caller-owned handle.

Records storage/block_count in state, marks it read-only per read_only, and points bd at the RAM vtable with state as its context. No allocation occurs; the caller owns both bd and state.

Parameters

[out]	bd	Handle to bind (zero-initialised by the caller).
[out]	state	Caller-owned backend state to populate.
[in]	storage	Backing buffer of block_count * 512 bytes.
[in]	block_count	Number of 512-byte logical blocks (>= 1).
[in]	read_only	true to reject writes and erases on this device.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Backend bound; bd is usable.
k_ra8_err_null_ptr	bd, state, or storage was NULL.
k_ra8_err_invalid_size	block_count was zero.

Precondition

storage covers at least block_count * 512 bytes.

bd and state out-live every call made through the device.

Postcondition

On success bd dispatches to the RAM backend over storage.

On any non-ok return bd and state are left unbound/untouched.

Note

Not thread-safe with respect to the same device.

Since

0.1.0

Definition at line 262 of file ra8_io_blockdev_ram.c.

References ra8_io_blockdev_ram_state_t::block_count, ra8_io_blockdev_t::ctx, ra8_io_blockdev_t::iface, k_ra8_err_invalid_size, k_ra8_io_ram_min_blocks, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_io_blockdev_ram_state_t::read_only, s_ram_iface, s_tag, and ra8_io_blockdev_ram_state_t::storage.

Referenced by internal_demo_mount(), internal_demo_probe_fat(), internal_demo_probe_foreign(), internal_demo_run(), internal_demo_run(), internal_swap_run_all(), and ra8_io_blockdev_sdram_init().

Variable Documentation

s_ram_iface

const ra8_io_blockdev_iface_t s_ram_iface

static

Initial value:

                                                 = {
  .read     = internal_ram_read,
  .write    = internal_ram_write,
  .erase    = internal_ram_erase,
  .get_caps = internal_ram_get_caps,
  .sync     = nullptr,
}

RAM backend vtable.

sync is NULL: writes hit memory immediately.

Definition at line 254 of file ra8_io_blockdev_ram.c.

Referenced by ra8_io_blockdev_ram_init(), and ra8_io_stream_ram_init().

s_tag

const char* const s_tag = "ra8_io_blockdev_ram"

static

Module log tag.

Definition at line 30 of file ra8_io_blockdev_ram.c.