ra8_sdcard.h File Reference

SD card driver layered on top of the RA8D2 SDHI peripheral. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_sdhi.h"

Include dependency graph for ra8_sdcard.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ra8_sdcard_cfg_t
	User-supplied configuration for ra8_sdcard_init. More...

Enumerations
enum	ra8_sdcard_card_type_t : uint8_t {   k_ra8_sdcard_type_unknown = 0U ,   k_ra8_sdcard_type_sdsc = 1U ,   k_ra8_sdcard_type_sdhc = 2U ,   k_ra8_sdcard_type_sdxc = 3U }
	Detected SD card capacity / addressing class. More...

Functions
ra8_err_t	ra8_sdcard_init (const ra8_sdcard_cfg_t *cfg)
	Bring up the SDHI block and perform full SD card initialization.
ra8_err_t	ra8_sdcard_read_blocks (uint32_t lba, uint8_t *buf, uint32_t count)
	Read count 512-byte blocks starting at lba.
ra8_err_t	ra8_sdcard_write_blocks (uint32_t lba, const uint8_t *buf, uint32_t count)
	Write count 512-byte blocks starting at lba.
ra8_err_t	ra8_sdcard_get_capacity (uint32_t *out_blocks)
	Return card capacity in 512-byte blocks.
ra8_err_t	ra8_sdcard_get_type (ra8_sdcard_card_type_t *out_type)
	Return the detected card type (SDSC / SDHC / SDXC).
ra8_err_t	ra8_sdcard_deinit (void)
	Tear down the card driver and release the SDHI block.

Detailed Description

SD card driver layered on top of the RA8D2 SDHI peripheral.

Tag

[Ring 3 / HAL] {World: NS}

High-level SD/SDHC/SDXC card driver. Sits on top of the lower-level ra8_sdhi register-driver primitive and implements the standard SD Physical Layer initialization sequence:

1. CMD0 GO_IDLE_STATE (reset card to idle)
2. CMD8 SEND_IF_COND (interface condition + V2 probe)
3. ACMD41 SD_SEND_OP_COND (operating-condition negotiation, HCS=1 -> SDHC/SDXC support)
4. CMD2 ALL_SEND_CID (capture CID)
5. CMD3 SEND_RELATIVE_ADDR (host obtains card RCA)
6. CMD9 SEND_CSD (capture CSD -> capacity, class)
7. CMD7 SELECT_CARD (place card in transfer state)

After CMD7 the bus clock is bumped from the 400 kHz identification speed to 25 MHz default-speed; SDR50 / DDR50 is left as a future extension.

Block I/O is delegated straight to ra8_sdhi_read_block / ra8_sdhi_write_block, which already implement the polled SD_BUF0 FIFO drain. ra8_sdcard only owns the protocol state (capacity in 512-byte blocks, RCA, OCR card-type bits, init flag).

Citations against the RA8D2 Hardware User's Manual reference Ch 47 "SD/MMC Host Interface (SDHI)" (HUM pages 3122-3179). SD command indices and response formats are from the SD Physical Layer Specification v6.00 (open-access) – the manual cites that spec directly in 47.1 "SDHI Overview".

Copyright

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

Definition in file ra8_sdcard.h.

Enumeration Type Documentation

ra8_sdcard_card_type_t

enum ra8_sdcard_card_type_t : uint8_t

Detected SD card capacity / addressing class.

Enumerator
k_ra8_sdcard_type_unknown	Not yet probed or no card present.
k_ra8_sdcard_type_sdsc	Standard-capacity, byte-addressed (<= 2 GB).
k_ra8_sdcard_type_sdhc	High-capacity, block-addressed (2-32 GB).
k_ra8_sdcard_type_sdxc	Extended-capacity, block-addressed (>32 GB).

Definition at line 57 of file ra8_sdcard.h.

Function Documentation

ra8_sdcard_deinit()

ra8_err_t ra8_sdcard_deinit ( void )

nodiscard

Tear down the card driver and release the SDHI block.

Resets the internal protocol state (capacity, RCA, type) and calls ra8_sdhi_deinit on the underlying instance. After this call ra8_sdcard_init may be invoked again.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Success (or already-deinit no-op).
k_ra8_err_invalid_state	SDHI deinit failed.

Precondition

None.

Postcondition

Internal state is the same as before the first ra8_sdcard_init.

SDHI module is gated off (MSTP).

Since

0.1.0

Definition at line 664 of file ra8_sdcard.c.

References k_ra8_err_invalid_state, k_ra8_ok, k_ra8_sdcard_type_unknown, ra8_sdhi_deinit(), and s_sdcard.

ra8_sdcard_get_capacity()

ra8_err_t ra8_sdcard_get_capacity ( uint32_t * out_blocks )

nodiscard

Return card capacity in 512-byte blocks.

Parameters

[out]

out_blocks

Receives the block count; non-NULL.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Success.
k_ra8_err_null_ptr	out_blocks was NULL.
k_ra8_err_invalid_state	Card never initialized.

Precondition

out_blocks is non-NULL.

ra8_sdcard_init has returned k_ra8_ok.

Postcondition

On success *out_blocks > 0.

Driver state unchanged.

Since

0.1.0

Definition at line 644 of file ra8_sdcard.c.

References k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, s_sdcard, and s_tag.

Referenced by internal_sdhi_get_caps(), and sdhi_card_check_capacity().

ra8_sdcard_get_type()

ra8_err_t ra8_sdcard_get_type ( ra8_sdcard_card_type_t * out_type )

nodiscard

Return the detected card type (SDSC / SDHC / SDXC).

Parameters

[out]

out_type

Receives the card type; non-NULL.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Success.
k_ra8_err_null_ptr	out_type was NULL.
k_ra8_err_invalid_state	Card never initialized.

Precondition

out_type is non-NULL.

ra8_sdcard_init has returned k_ra8_ok.

Postcondition

Driver state unchanged.

Since

0.1.0

Definition at line 654 of file ra8_sdcard.c.

References k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, s_sdcard, and s_tag.

ra8_sdcard_init()

ra8_err_t ra8_sdcard_init ( const ra8_sdcard_cfg_t * cfg )

nodiscard

Bring up the SDHI block and perform full SD card initialization.

Runs the standard SD Physical Layer init sequence:

1. ra8_sdhi_init – MSTP gate + soft-reset + 400 kHz clock
2. CMD0 GO_IDLE_STATE
3. CMD8 SEND_IF_COND (pattern 0x1AA, 2.7-3.6 V)
4. ACMD41 with HCS=1 looped until OCR busy bit clears
5. CMD2 ALL_SEND_CID
6. CMD3 SEND_RELATIVE_ADDR – captures the card-assigned RCA
7. CMD9 SEND_CSD – decodes capacity + speed class
8. CMD7 SELECT_CARD – transitions card to TRAN state
9. optional ACMD6 4-bit bus-width negotiation when cfg->bus_width requests it (best-effort; see ra8_sdcard_cfg_t)

ra8_sdhi_set_clock to 25 MHz default-speed

On success the internal state holds card type, RCA, and capacity in 512-byte blocks, and the SDHI block is ready for read_blocks / write_blocks traffic.

Parameters

[in]

cfg

Non-NULL configuration with a valid SDHI instance.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Card initialized, ready for I/O.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	cfg->instance out of range.
k_ra8_err_invalid_state	Already initialized (call ra8_sdcard_deinit first).
k_ra8_err_hw_timeout	A command never produced RSPEND.
k_ra8_err_hw_init_failed	CMD8 echo / ACMD41 pattern mismatch.

Precondition

cfg is non-NULL and points to a fully populated config struct.

No other consumer is currently using the chosen SDHI instance.

Postcondition

On success ra8_sdcard_get_capacity returns a non-zero block count.

On success the SDHI bus clock is at default speed (25 MHz).

Note

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

Example:

ra8_sdcard_cfg_t cfg = { .instance = 0U, .bus_width = k_ra8_sdhi_bus_width_4bit };
ra8_err_t        err = ra8_sdcard_init(&cfg);

See also

ra8_sdcard_read_blocks

ra8_sdcard_get_capacity

Since

0.1.0

Definition at line 544 of file ra8_sdcard.c.

References ra8_sdcard_cfg_t::bus_width, ra8_sdcard_cfg_t::instance, internal_classify(), internal_sdcard_card_online(), internal_sdcard_negotiate_width(), k_ra8_err_invalid_state, k_ra8_ok, k_ra8_sdcard_default_clk_div, RA8_CHECK_NULL_PTR, ra8_log_info_val, RA8_RETURN_ON_ERROR, ra8_sdhi_set_clock(), s_sdcard, and s_tag.

Referenced by internal_sdcard_thread_entry(), sdhi_card_init_or_halt(), and sdhi_demo_init_card_or_halt().

ra8_sdcard_read_blocks()

ra8_err_t ra8_sdcard_read_blocks ( uint32_t lba, uint8_t * buf, uint32_t count )

nodiscard

Read count 512-byte blocks starting at lba.

Thin pass-through to ra8_sdhi_read_block once the card has been initialized. The lba argument is the logical block address as understood by the card – which means block address for SDHC/SDXC and byte address for SDSC. ra8_sdcard translates the SDSC case internally (lba * 512) so callers always pass block indices.

Parameters

[in]	lba	Logical block address (sector number).
[out]	buf	Destination buffer; must hold count * 512 bytes.
[in]	count	Number of 512-byte blocks; must be > 0.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Success.
k_ra8_err_null_ptr	buf was NULL.
k_ra8_err_invalid_arg	count was 0.
k_ra8_err_invalid_state	Card never initialized.
k_ra8_err_out_of_range	lba + count exceeds card capacity.

Precondition

ra8_sdcard_init has returned k_ra8_ok.

buf is non-NULL.

Postcondition

Buffer holds card data on success.

Card remains in TRAN state.

Note

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

Since

0.1.0

Definition at line 612 of file ra8_sdcard.c.

References internal_to_card_address(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_out_of_range, RA8_CHECK_NULL_PTR, ra8_sdhi_read_block(), s_sdcard, and s_tag.

Referenced by internal_sdcard_one_pass(), internal_sdhi_read(), and sdhi_card_block_roundtrip().

ra8_sdcard_write_blocks()

ra8_err_t ra8_sdcard_write_blocks ( uint32_t lba, const uint8_t * buf, uint32_t count )

nodiscard

Write count 512-byte blocks starting at lba.

Thin pass-through to ra8_sdhi_write_block. Same SDSC byte-address translation as ra8_sdcard_read_blocks. The driver does not perform pre-erase (ACMD23) or busy-poll the card after writes; the caller is expected to layer those on top if required.

Parameters

[in]	lba	Logical block address.
[in]	buf	Source buffer; must hold count * 512 bytes.
[in]	count	Number of 512-byte blocks; must be > 0.

Returns

ra8_err_t Error code (same as ra8_sdcard_read_blocks).

Precondition

ra8_sdcard_init has returned k_ra8_ok.

buf is non-NULL.

Postcondition

On success the requested block range was pushed to the card.

Card remains in TRAN state.

Since

0.1.0

Definition at line 628 of file ra8_sdcard.c.

References internal_to_card_address(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_out_of_range, RA8_CHECK_NULL_PTR, ra8_sdhi_write_block(), s_sdcard, and s_tag.

Referenced by internal_sdhi_write(), and sdhi_card_block_roundtrip().