Micro-SD-over-SPI block-device backend – thin shim over ra8_sdmmc_spi. More...

#include "ra8_io_blockdev_sdspi.h"
#include <stddef.h>
#include <stdint.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 "ra8_sdmmc_spi.h"

Include dependency graph for ra8_io_blockdev_sdspi.c:

Enumerations
enum	ra8_io_sdspi_const_t : uint32_t { k_ra8_io_sdspi_erase_unit_blocks = 1 }
	SD-SPI backend layout constants. More...

Functions
static ra8_err_t	internal_sdspi_read (void ctx, uint32_t lba, uint32_t count, uint8_t buf)
	SD-SPI backend: read count blocks at lba into buf.
static ra8_err_t	internal_sdspi_write (void ctx, uint32_t lba, uint32_t count, const uint8_t buf)
	SD-SPI backend: write count blocks from buf at lba.
static ra8_err_t	internal_sdspi_erase (void *ctx, uint32_t lba, uint32_t count)
	SD-SPI backend: erase count blocks at lba to all-zero.
static ra8_err_t	internal_sdspi_get_caps (const void ctx, ra8_io_blockdev_caps_t out)
	SD-SPI backend: report card capabilities.
ra8_err_t	ra8_io_blockdev_sdspi_init (ra8_io_blockdev_t *bd)
	Bind the micro-SD-over-SPI backend into a caller-owned handle.

Variables
static const char *const	s_tag = "ra8_io_blockdev_sdspi"
	Module log tag.
static const ra8_io_blockdev_iface_t	s_sdspi_iface
	SD-SPI backend vtable.

Detailed Description

Micro-SD-over-SPI block-device backend – thin shim over ra8_sdmmc_spi.

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

Implements ra8_io_blockdev_iface by forwarding to the ra8_sdmmc_spi singleton driver. The driver owns all card state, so this backend keeps no context: the read primitive forwards to the bulk CMD18 path, the write primitive forwards to the bulk CMD25 path, erase forwards to the driver's verified-zero CMD32/CMD33/CMD38 sequence, and capabilities are derived from the driver's reported block count. No raw MMIO is touched here; the driver carries every HUM citation.

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

Definition in file ra8_io_blockdev_sdspi.c.

Enumeration Type Documentation

◆ ra8_io_sdspi_const_t

enum ra8_io_sdspi_const_t : uint32_t

SD-SPI backend layout constants.

The SD card erases a logical block at a time from the fabric's point of view and programs in whole 512-byte blocks, so the erase unit and program size are fixed singletons here.

Since: 0.1.0

Enumerator
k_ra8_io_sdspi_erase_unit_blocks	One logical block per erase unit.

Definition at line 47 of file ra8_io_blockdev_sdspi.c.

Function Documentation

◆ internal_sdspi_erase()

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

static

SD-SPI backend: erase count blocks at lba to all-zero.

Forwards to the driver's CMD32/CMD33/CMD38 sequence, which verifies the range reads back as 0x00 (returning k_ra8_err_not_supported on a ones-erasing card so the caller can fall back to writing zeros).

Parameters

[in]	ctx	Unused (the driver is a singleton).
[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 erased and verified to read back zero.
k_ra8_err_invalid_arg	count was zero.
k_ra8_err_out_of_range	Range past the card capacity.
k_ra8_err_not_supported	Card erases to a non-zero value.

Precondition: The card is initialised via ra8_sdmmc_spi_init.; count is non-zero for any observable effect.

Postcondition: On success the range reads back as 0x00.; On failure the card is left as the driver leaves it.

Note: Not thread-safe with respect to the driver singleton.

Since: 0.1.0

Definition at line 150 of file ra8_io_blockdev_sdspi.c.

References RA8_INTERNAL, and ra8_sdmmc_spi_erase_blocks().

◆ internal_sdspi_get_caps()

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

static

SD-SPI backend: report card capabilities.

Queries the driver for the 512-byte block count and fills a fixed capability snapshot: one-block erase unit, 512-byte program size, zero erase value, and no erase-before-write requirement (the card programs blocks directly).

Parameters

[in]	ctx	Unused (the driver is a singleton).
[out]	out	Capabilities snapshot.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	*out populated.
k_ra8_err_null_ptr	out was NULL.

Precondition: The card is initialised via ra8_sdmmc_spi_init.; out is writable.

Postcondition: On success *out describes a zero-erase 512-byte block device.; No driver or handle state is mutated.

Note: Not thread-safe with respect to the driver singleton.

Since: 0.1.0

Definition at line 181 of file ra8_io_blockdev_sdspi.c.

References ra8_io_blockdev_caps_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_sdspi_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_RETURN_ON_ERROR, ra8_sdmmc_spi_get_capacity(), ra8_io_blockdev_caps_t::read_only, and s_tag.

◆ internal_sdspi_read()

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

static

SD-SPI backend: read count blocks at lba into buf.

Forwards to the driver's bulk CMD18 path, which streams every block in a single READ_MULTIPLE_BLOCK transaction terminated by CMD12 (falling back to CMD17 for a single block).

Parameters

[in]	ctx	Unused (the driver is a singleton).
[in]	lba	First logical block address.
[in]	count	Number of blocks to read.
[out]	buf	Destination buffer (>= count * 512 bytes).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Blocks read into buf.
k_ra8_err_null_ptr	buf was NULL.
k_ra8_err_out_of_range	Range past the card capacity.

Precondition: The card is initialised via ra8_sdmmc_spi_init.; buf is writable for count * 512 bytes.

Postcondition: On success buf mirrors the card contents.; On failure buf holds at most the blocks streamed before the error.

Note: Not thread-safe with respect to the driver singleton.

Since: 0.1.0

Definition at line 80 of file ra8_io_blockdev_sdspi.c.

References RA8_CHECK_NULL_PTR, ra8_sdmmc_spi_read_blocks(), and s_tag.

◆ internal_sdspi_write()

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

static

SD-SPI backend: write count blocks from buf at lba.

Forwards to the driver's bulk CMD25 path, which streams every block in a single transaction (falling back to CMD24 for a single block).

Parameters

[in]	ctx	Unused (the driver is a singleton).
[in]	lba	First logical block address.
[in]	count	Number of blocks to write.
[in]	buf	Source buffer (>= count * 512 bytes).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Blocks written.
k_ra8_err_null_ptr	buf was NULL.
k_ra8_err_out_of_range	Range past the card capacity.

Precondition: The card is initialised via ra8_sdmmc_spi_init.; buf is readable for count * 512 bytes.

Postcondition: On success the card blocks [lba, lba+count) equal buf.; On failure the card is left as the driver leaves it.

Note: Not thread-safe with respect to the driver singleton.

Since: 0.1.0

Definition at line 115 of file ra8_io_blockdev_sdspi.c.

References RA8_CHECK_NULL_PTR, ra8_sdmmc_spi_write_blocks(), and s_tag.

◆ ra8_io_blockdev_sdspi_init()

ra8_err_t ra8_io_blockdev_sdspi_init ( ra8_io_blockdev_t * bd )

nodiscard

Bind the micro-SD-over-SPI backend into a caller-owned handle.

Points bd at the SD-SPI vtable with a NULL context (the ra8_sdmmc_spi driver is a single global instance, so no per-device state is needed). No allocation and no bus traffic occur; the caller owns bd. The card itself must already be initialised with ra8_sdmmc_spi_init before any I/O call is made through the bound device.

Parameters

[out] bd Handle to bind (zero-initialised by the caller).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Backend bound; bd is usable once the card is up.
k_ra8_err_null_ptr	bd was NULL.

Precondition: bd is non-NULL and out-lives every call made through the device.; The application calls ra8_sdmmc_spi_init before issuing I/O.

Postcondition: On success bd dispatches to the SD-SPI singleton driver.; On any non-ok return bd is left unbound/untouched.

Note: Not thread-safe with respect to the same device or the driver singleton.

Since: 0.1.0

Definition at line 206 of file ra8_io_blockdev_sdspi.c.

References ra8_io_blockdev_t::ctx, ra8_io_blockdev_t::iface, k_ra8_ok, RA8_CHECK_NULL_PTR, s_sdspi_iface, and s_tag.

Referenced by internal_sd_demo_roundtrip().

Variable Documentation

◆ s_sdspi_iface

const ra8_io_blockdev_iface_t s_sdspi_iface

static

Initial value:

                                                   = {
  .read     = internal_sdspi_read,
  .write    = internal_sdspi_write,
  .erase    = internal_sdspi_erase,
  .get_caps = internal_sdspi_get_caps,
  .sync     = nullptr,
}

SD-SPI backend vtable.

sync is NULL: the driver writes synchronously.

Definition at line 198 of file ra8_io_blockdev_sdspi.c.

Referenced by ra8_io_blockdev_sdspi_init().

◆ s_tag

const char* const s_tag = "ra8_io_blockdev_sdspi"

static

Module log tag.

Definition at line 34 of file ra8_io_blockdev_sdspi.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_io_sdspi_const_t

Function Documentation

◆ internal_sdspi_erase()

◆ internal_sdspi_get_caps()

◆ internal_sdspi_read()

◆ internal_sdspi_write()

◆ ra8_io_blockdev_sdspi_init()

Variable Documentation

◆ s_sdspi_iface

◆ s_tag