Contracts for file-local SD protocol helpers. More...

#include "ra8_sdmmc_spi_internal.h"

Include dependency graph for ra8_sdmmc_spi_core_contracts_internal.h:

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

Functions
static void	internal_build_frame (sd_cmd_t cmd, uint32_t arg, uint8_t *out_frame)
	Serialize one command and argument into an SD wire frame.
static ra8_err_t	internal_read_r1 (uint8_t *out_r1)
	Poll and decode the one-byte R1 command response.
static ra8_err_t	internal_read_r3_or_r7_tail (uint32_t *out_word)
	Read the four-byte tail of an R3 or R7 response.
static uint32_t	internal_csd_to_blocks (const uint8_t *csd)
	Decode a CSD register into 512-byte logical blocks.
static ra8_err_t	internal_send_cmd0 (void)
	Send CMD0 and require the idle-state response.
static ra8_err_t	internal_send_cmd8 (bool *out_is_v2)
	Probe SD v2 voltage support with CMD8.
static ra8_err_t	internal_acmd41_loop (bool is_v2)
	Poll ACMD41 until the card leaves idle state.
static ra8_err_t	internal_read_ocr (bool *out_is_hc)
	Read OCR and classify high-capacity addressing.
static ra8_err_t	internal_set_block_len (void)
	Set the fixed 512-byte block length for byte-addressed cards.
static ra8_sdmmc_spi_card_type_t	internal_classify_card (bool is_v2, bool is_hc)
	Map generation and CCS facts to the public card type.
static ra8_err_t	internal_probe_card (bool out_is_v2, bool out_is_hc)
	Execute the wake, CMD0, CMD8, ACMD41, and OCR probe stages.

Detailed Description

Contracts for file-local SD protocol helpers.

Declares only helpers defined by ra8_sdmmc_spi.c so their complete contracts stay authoritative without inflating the implementation.

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

Definition in file ra8_sdmmc_spi_core_contracts_internal.h.

Function Documentation

◆ internal_acmd41_loop()

ra8_err_t internal_acmd41_loop ( bool is_v2 )

static

Poll ACMD41 until the card leaves idle state.

Sends CMD55/ACMD41 pairs with the HCS argument selected by generation.

Parameters

[in] is_v2 True when CMD8 identified an SD v2 card.

Returns: ra8_err_t Readiness-poll result.

Return values

k_ra8_ok	The card reported ready.
other	Transport, protocol, or bounded-attempt timeout.

Precondition: CMD8 classification has completed.; The transport remains bound at initialization speed.

Postcondition: Success confirms the card left idle state.; Every attempt releases chip select before the next.

Note: The attempt count is compile-time bounded.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_build_frame()

void internal_build_frame	(	sd_cmd_t	cmd,
		uint32_t	arg,
		uint8_t *	out_frame )

static

Serialize one command and argument into an SD wire frame.

Writes the command byte, big-endian argument, and required CRC/end bits.

Parameters

[in]	cmd	Encoded SD command byte.
[in]	arg	Command argument in host order.
[out]	out_frame	Writable six-byte frame.

Precondition: out_frame addresses at least six writable bytes.; cmd is a command supported by the driver.

Postcondition: out_frame contains a complete command frame.; No transport or driver state is changed.

Note: CMD0 and CMD8 use their mandated fixed CRC values.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_classify_card()

ra8_sdmmc_spi_card_type_t internal_classify_card	(	bool	is_v2,
		bool	is_hc )

static

Map generation and CCS facts to the public card type.

Gives high-capacity classification precedence over SD version.

Parameters

[in]	is_v2	True for a valid CMD8 echo.
[in]	is_hc	True when OCR advertises block addressing.

Returns: Classified card type.

Return values

k_ra8_sdmmc_spi_type_sdhc	High-capacity card.
other	SD v1 or SD v2 standard-capacity type.

Precondition: Both facts were obtained from validated protocol responses.; The two Boolean inputs are stable for the call.

Postcondition: No driver or transport state is changed.; A supported non-unknown card type is returned.

Note: This routine performs no I/O.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_csd_to_blocks()

uint32_t internal_csd_to_blocks ( const uint8_t * csd )

static

Decode a CSD register into 512-byte logical blocks.

Handles the SD CSD v1 and v2 capacity encodings with checked arithmetic.

Parameters

[in] csd Sixteen-byte CSD register image.

Returns: Decoded logical block count.

Return values

0	The CSD version or geometry is invalid.
other	Positive count of 512-byte blocks.

Precondition: csd addresses a complete CSD response.; CSD bytes remain immutable during decoding.

Postcondition: The input register image is unchanged.; The result is zero or a representable block count.

Note: This routine performs no transport I/O.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_probe_card()

ra8_err_t internal_probe_card	(	bool *	out_is_v2,
		bool *	out_is_hc )

static

Execute the wake, CMD0, CMD8, ACMD41, and OCR probe stages.

Recovers a stuck card once and publishes only validated classification facts.

Parameters

[out]	out_is_v2	Receives the card-generation fact.
[out]	out_is_hc	Receives the high-capacity fact.

Returns: ra8_err_t Probe sequence result.

Return values

k_ra8_ok	Both classification facts are valid.
other	Transport, timeout, or protocol error.

Precondition: The transport is bound and initialization is unpublished.; Both output pointers are non-null and writable.

Postcondition: Success publishes both classification facts.; Failure leaves initialization unpublished.

Note: Recovery remains bounded and does not recurse.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_read_ocr()

ra8_err_t internal_read_ocr ( bool * out_is_hc )

static

Read OCR and classify high-capacity addressing.

Sends CMD58, validates R1, and inspects the CCS bit in the R3 tail.

Parameters

[out] out_is_hc Receives the OCR high-capacity classification.

Returns: ra8_err_t OCR transaction result.

Return values

k_ra8_ok	OCR was read and classified.
other	Transport or protocol error.

Precondition: ACMD41 reported the card ready.; out_is_hc is non-null and writable.

Postcondition: Success publishes the CCS classification.; Chip select is released before return.

Note: SD v1 initialization skips this helper.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_read_r1()

ra8_err_t internal_read_r1 ( uint8_t * out_r1 )

static

Poll and decode the one-byte R1 command response.

Clocks bounded idle bytes until the card clears the response high bit.

Parameters

[out] out_r1 Destination for the accepted R1 byte.

Returns: ra8_err_t Response polling result.

Return values

k_ra8_ok	A valid R1 byte was received.
other	Transport failure or bounded response timeout.

Precondition: Chip select is asserted for the active command.; out_r1 is non-null and writable.

Postcondition: Success publishes exactly one R1 byte through out_r1.; Failure does not publish an unvalidated response.

Note: Polling is bounded by the SD response limit.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_read_r3_or_r7_tail()

ra8_err_t internal_read_r3_or_r7_tail ( uint32_t * out_word )

static

Read the four-byte tail of an R3 or R7 response.

Uses the bulk transport and a bounded byte fallback when necessary.

Parameters

[out] out_word Destination for the assembled big-endian response word.

Returns: ra8_err_t Tail transfer result.

Return values

k_ra8_ok	Four response bytes were assembled.
other	Propagated transport error.

Precondition: Chip select remains asserted after a successful R1 response.; out_word is non-null and writable.

Postcondition: Success publishes the complete response word.; Failure leaves no partially accepted protocol result.

Note: The fallback preserves transports that reject multi-byte transfers.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_send_cmd0()

ra8_err_t internal_send_cmd0 ( void )

static

Send CMD0 and require the idle-state response.

Brackets GO_IDLE_STATE with chip select and validates R1 exactly.

Returns: ra8_err_t CMD0 transaction result.

Return values

k_ra8_ok	The card entered SPI idle state.
other	Transport, timeout, or protocol error.

Precondition: The transport is bound and wake clocks were sent.; Driver initialization is not yet published.

Postcondition: Chip select is released before return.; Success confirms the idle-state R1 value.

Note: This is the first command of initialization.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_send_cmd8()

ra8_err_t internal_send_cmd8 ( bool * out_is_v2 )

static

Probe SD v2 voltage support with CMD8.

Validates the R7 voltage/check pattern or classifies an illegal CMD8 as v1.

Parameters

[out] out_is_v2 Receives true when the CMD8 echo is valid.

Returns: ra8_err_t CMD8 probe result.

Return values

k_ra8_ok	Card generation was classified.
other	Transport or malformed-response error.

Precondition: CMD0 completed and the card remains idle.; out_is_v2 is non-null and writable.

Postcondition: Success publishes the card-generation classification.; Chip select is released before return.

Note: Illegal-command R1 is the supported v1 classification path.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_set_block_len()

ra8_err_t internal_set_block_len ( void )

static

Set the fixed 512-byte block length for byte-addressed cards.

Sends CMD16 and requires a ready R1 response.

Returns: ra8_err_t Block-length command result.

Return values

k_ra8_ok	The card accepted 512-byte blocks.
other	Transport or protocol error.

Precondition: Card generation and capacity have been classified.; The transport remains bound.

Postcondition: Chip select is released before return.; Success confirms the block length required by the public API.

Note: SDHC cards do not require CMD16.

Since: 0.1.0

References RA8_INTERNAL.

Functions

Detailed Description

Function Documentation

◆ internal_acmd41_loop()

◆ internal_build_frame()

◆ internal_classify_card()

◆ internal_csd_to_blocks()

◆ internal_probe_card()

◆ internal_read_ocr()

◆ internal_read_r1()

◆ internal_read_r3_or_r7_tail()

◆ internal_send_cmd0()

◆ internal_send_cmd8()

◆ internal_set_block_len()