ra8_io_blockdev_sdhi.c File Reference

Native-SDHI block-device backend – an SD card as 512-byte blocks. More...

#include "ra8_io_blockdev_sdhi.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_sdcard.h"

Include dependency graph for ra8_io_blockdev_sdhi.c:

Go to the source code of this file.

Enumerations
enum	ra8_io_sdhi_const_t : uint32_t { k_ra8_io_sdhi_erase_unit_blocks = 1 }
	Native-SDHI backend layout constants. More...

Functions
static ra8_err_t	internal_sdhi_read (void *ctx, uint32_t lba, uint32_t count, uint8_t *buf)
	Native-SDHI backend: read count blocks at lba into buf.
static ra8_err_t	internal_sdhi_write (void *ctx, uint32_t lba, uint32_t count, const uint8_t *buf)
	Native-SDHI backend: write count blocks from buf at lba.
static ra8_err_t	internal_sdhi_get_caps (const void *ctx, ra8_io_blockdev_caps_t *out)
	Native-SDHI backend: report medium capabilities.
ra8_err_t	ra8_io_blockdev_sdhi_init (ra8_io_blockdev_t *bd)
	Bind the native-SDHI SD-card backend into a caller-owned handle.

Variables
static const char *const	s_tag = "ra8_io_blockdev_sdhi"
	Module log tag.
static const ra8_io_blockdev_iface_t	s_sdhi_iface
	Native-SDHI backend vtable.

Detailed Description

Native-SDHI block-device backend – an SD card as 512-byte blocks.

Tag

[Ring 4 / PAL] {World: NS}

Implements ra8_io_blockdev_iface by forwarding reads and writes to the ra8_sdcard HAL driver, which drives the RA8D2 4-bit SDHI controller. The card is a singleton, so the bound context is NULL and this file carries no per-device state. The card exposes no host erase primitive, so the vtable's erase slot is NULL; capacity comes from ra8_sdcard_get_capacity. This file touches no raw MMIO – the HUM citations live in the ra8_sdcard driver.

Copyright

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

Definition in file ra8_io_blockdev_sdhi.c.

Enumeration Type Documentation

ra8_io_sdhi_const_t

enum ra8_io_sdhi_const_t : uint32_t

Native-SDHI backend layout constants.

Since

0.1.0

Enumerator
k_ra8_io_sdhi_erase_unit_blocks	One logical block per erase unit.

Definition at line 40 of file ra8_io_blockdev_sdhi.c.

Function Documentation

internal_sdhi_get_caps()

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

static

Native-SDHI backend: report medium capabilities.

Queries the card block count via ra8_sdcard_get_capacity and fills out for a zero-erase, no-erase-required, read-write medium with a 512-byte program and erase unit. ctx is unused (the card is a singleton).

Parameters

[in]	ctx	Unused backend context (always NULL for this backend).
[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.
k_ra8_err_invalid_state	The card was never initialised.

Precondition

ra8_sdcard_init has returned k_ra8_ok.

out is writable.

Postcondition

On success *out describes a zero-erase, read-write SD medium.

No card or backend state is mutated.

Note

Thread-safe (pure read of card-reported capacity).

Since

0.1.0

Definition at line 146 of file ra8_io_blockdev_sdhi.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_sdhi_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_sdcard_get_capacity(), ra8_io_blockdev_caps_t::read_only, and s_tag.

internal_sdhi_read()

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

static

Native-SDHI backend: read count blocks at lba into buf.

Validates buf then forwards straight to ra8_sdcard_read_blocks; the card driver enforces capacity bounds and initialisation state. ctx is unused (the card is a singleton).

Parameters

[in]	ctx	Unused backend context (always NULL for this backend).
[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_invalid_arg	count was zero.
k_ra8_err_invalid_state	The card was never initialised.
k_ra8_err_out_of_range	Range past card capacity.

Precondition

ra8_sdcard_init has returned k_ra8_ok.

buf is writable for count * 512 bytes.

Postcondition

On success buf holds the requested card data.

On failure buf is left as the card driver leaves it.

Note

Blocking, polled; not safe to call from an ISR.

Since

0.1.0

Definition at line 75 of file ra8_io_blockdev_sdhi.c.

References RA8_CHECK_NULL_PTR, ra8_sdcard_read_blocks(), and s_tag.

internal_sdhi_write()

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

static

Native-SDHI backend: write count blocks from buf at lba.

Validates buf then forwards straight to ra8_sdcard_write_blocks; the card driver enforces capacity bounds and initialisation state. ctx is unused (the card is a singleton).

Parameters

[in]	ctx	Unused backend context (always NULL for this backend).
[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 to the card.
k_ra8_err_null_ptr	buf was NULL.
k_ra8_err_invalid_arg	count was zero.
k_ra8_err_invalid_state	The card was never initialised.
k_ra8_err_out_of_range	Range past card capacity.

Precondition

ra8_sdcard_init has returned k_ra8_ok.

buf is readable for count * 512 bytes.

Postcondition

On success the card range [lba, lba+count) equals buf.

On failure the card is left as the card driver leaves it.

Note

Blocking, polled; not safe to call from an ISR.

Since

0.1.0

Definition at line 113 of file ra8_io_blockdev_sdhi.c.

References RA8_CHECK_NULL_PTR, ra8_sdcard_write_blocks(), and s_tag.

ra8_io_blockdev_sdhi_init()

ra8_err_t ra8_io_blockdev_sdhi_init ( ra8_io_blockdev_t * bd )

nodiscard

Bind the native-SDHI SD-card backend into a caller-owned handle.

Points bd at the SDHI vtable with a NULL context (the card is a singleton owned by ra8_sdcard). No allocation occurs; the caller owns bd. The card itself must already have been initialised with ra8_sdcard_init – this helper only wires the dispatch table and does not touch the controller.

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.
k_ra8_err_null_ptr	bd was NULL.

Precondition

bd out-lives every call made through the device.

ra8_sdcard_init has returned k_ra8_ok before any I/O through bd.

Postcondition

On success bd dispatches to the native-SDHI backend.

On any non-ok return bd is left untouched.

Note

Not thread-safe with respect to the same device.

Since

0.1.0

Definition at line 174 of file ra8_io_blockdev_sdhi.c.

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

Referenced by sdhi_demo_mount_via_io().

Variable Documentation

s_sdhi_iface

const ra8_io_blockdev_iface_t s_sdhi_iface

static

Initial value:

                                                  = {
  .read     = internal_sdhi_read,
  .write    = internal_sdhi_write,
  .erase    = nullptr,
  .get_caps = internal_sdhi_get_caps,
  .sync     = nullptr,
}

Native-SDHI backend vtable.

erase/sync are NULL (no host erase, no buffering).

Definition at line 166 of file ra8_io_blockdev_sdhi.c.

Referenced by ra8_io_blockdev_sdhi_init().

s_tag

const char* const s_tag = "ra8_io_blockdev_sdhi"

static

Module log tag.

Definition at line 32 of file ra8_io_blockdev_sdhi.c.