Contracts for file-local SD block-I/O helpers. More...

#include "ra8_sdmmc_spi_internal.h"

Include dependency graph for ra8_sdmmc_spi_io_contracts_internal.h:

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

Functions
static ra8_err_t	internal_prepare_init (const ra8_sdmmc_spi_transport_t *transport)
	Validate and stage the transport for initialization.
static ra8_err_t	internal_finalize_init (void)
	Switch to data clock and publish initialized state.
static uint32_t	internal_lba_to_arg (uint32_t lba)
	Convert an LBA to the card command argument.
static ra8_err_t	internal_cmd_require_ready (sd_cmd_t cmd, uint32_t arg)
	Send one command and require a ready R1 response.
static ra8_err_t	internal_erase_range (uint32_t lba, uint32_t count)
	Issue the SD erase-start, erase-end, and erase commands.
static ra8_err_t	internal_read_block_payload (uint8_t *buf)
	Read one 512-byte payload from the active data stream.
static ra8_err_t	internal_read_block_crc_check (const uint8_t *buf)
	Read and verify the CRC trailer for one block.
static ra8_err_t	internal_read_data_phase (uint32_t lba, uint8_t *buf)
	Execute one complete CMD17 read data phase.
static ra8_err_t	internal_read_multi_stop (void)
	Stop a CMD18 multi-block read stream.
static ra8_err_t	internal_write_data_block (const uint8_t *buf, uint8_t start_token)
	Transmit one data block, CRC trailer, and start token.
static ra8_err_t	internal_write_multi_stream (const uint8_t *buf, uint32_t count)
	Stream consecutive blocks for an accepted CMD25 operation.
static ra8_err_t	internal_fs_read_block (void ctx, uint64_t lba, uint32_t count, uint8_t buf)
	Adapt the filesystem read callback to SD multi-block reads.
static ra8_err_t	internal_fs_write_block (void ctx, uint64_t lba, uint32_t count, const uint8_t buf)
	Adapt the filesystem write callback to SD multi-block writes.
static ra8_err_t	internal_fs_erase_block (void *ctx, uint64_t lba, uint64_t count)
	Adapt the filesystem erase callback to the SD erase API.
static ra8_err_t	internal_fs_get_capacity (void ctx, uint64_t block_count, uint32_t *block_size)
	Publish SD geometry through the filesystem capacity callback.

Detailed Description

Contracts for file-local SD block-I/O helpers.

Declares only helpers defined by ra8_sdmmc_spi_io.c so contracts remain authoritative without expanding the implementation TU.

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

Definition in file ra8_sdmmc_spi_io_contracts_internal.h.

Function Documentation

◆ internal_cmd_require_ready()

ra8_err_t internal_cmd_require_ready	(	sd_cmd_t	cmd,
		uint32_t	arg )

static

Send one command and require a ready R1 response.

Brackets the command with chip select and rejects any nonzero R1.

Parameters

[in]	cmd	Encoded command byte.
[in]	arg	Command argument.

Returns: ra8_err_t Command result.

Return values

k_ra8_ok	The card returned ready.
other	Transport or protocol error.

Precondition: The card is initialized and transport callbacks are valid.; cmd is legal for the current operation.

Postcondition: Chip select is released before return.; Success confirms an all-clear R1 response.

Note: Used by erase setup and execution commands.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_erase_range()

ra8_err_t internal_erase_range	(	uint32_t	lba,
		uint32_t	count )

static

Issue the SD erase-start, erase-end, and erase commands.

Converts the inclusive range endpoints through the active addressing mode.

Parameters

[in]	lba	First logical block to erase.
[in]	count	Number of consecutive blocks.

Returns: ra8_err_t Erase command result.

Return values

k_ra8_ok	The card accepted and completed the erase.
other	Command, transport, or busy-timeout error.

Precondition: count is positive and the range is capacity-checked.; The driver is initialized.

Postcondition: Success completes the requested card erase range.; Failure is returned without publishing a false success.

Note: Card-level erase granularity is implementation-defined.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_finalize_init()

ra8_err_t internal_finalize_init ( void )

static

Switch to data clock and publish initialized state.

Performs the final clock callback only after protocol setup succeeds.

Returns: ra8_err_t Finalization result.

Return values

k_ra8_ok	Data clock is active and initialization is published.
other	Propagated clock callback failure.

Precondition: The full card initialization sequence succeeded.; The bound set-clock callback remains valid.

Postcondition: Success sets initialized true.; Failure leaves initialized false.

Note: Publication occurs after the fallible clock transition.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_fs_erase_block()

ra8_err_t internal_fs_erase_block	(	void *	ctx,
		uint64_t	lba,
		uint64_t	count )

static

Adapt the filesystem erase callback to the SD erase API.

Validates and narrows the filesystem range before delegation.

Parameters

[in]	ctx	Unused backend context.
[in]	lba	First logical block.
[in]	count	Number of blocks.

Returns: ra8_err_t Adapter result.

Return values

k_ra8_ok	Requested range was erased.
other	Validation or driver error.

Precondition: The range fits the driver 32-bit geometry.; The driver is initialized.

Postcondition: ctx remains untouched.; Success confirms the erase operation completed.

Note: Zero-length ranges are rejected by the public layer.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_fs_get_capacity()

ra8_err_t internal_fs_get_capacity	(	void *	ctx,
		uint64_t *	block_count,
		uint32_t *	block_size )

static

Publish SD geometry through the filesystem capacity callback.

Returns the initialized block count and fixed 512-byte block size.

Parameters

[in]	ctx	Unused backend context.
[out]	block_count	Destination for logical block count.
[out]	block_size	Destination for bytes per block.

Returns: ra8_err_t Capacity query result.

Return values

k_ra8_ok	Both geometry values were published.
other	Null-pointer or invalid-state error.

Precondition: Both output pointers are non-null and writable.; The driver is initialized with validated capacity.

Postcondition: Success publishes both geometry values.; ctx remains untouched.

Note: The block size is always k_ra8_sdmmc_spi_block_size.

Since: 0.1.0

◆ internal_fs_read_block()

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

static

Adapt the filesystem read callback to SD multi-block reads.

Narrows checked 64-bit arguments and delegates to the public driver API.

Parameters

[in]	ctx	Unused backend context.
[in]	lba	First logical block.
[in]	count	Number of blocks.
[out]	buf	Writable destination blocks.

Returns: ra8_err_t Adapter result.

Return values

k_ra8_ok	Requested blocks were read.
other	Validation or driver error.

Precondition: buf is non-null for a nonzero request.; Inputs fit the driver 32-bit geometry.

Postcondition: Success initializes all requested destination blocks.; ctx remains untouched.

Note: The bound backend intentionally uses no context object.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_fs_write_block()

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

static

Adapt the filesystem write callback to SD multi-block writes.

Narrows checked 64-bit arguments and delegates to the public driver API.

Parameters

[in]	ctx	Unused backend context.
[in]	lba	First logical block.
[in]	count	Number of blocks.
[in]	buf	Immutable source blocks.

Returns: ra8_err_t Adapter result.

Return values

k_ra8_ok	Requested blocks were written.
other	Validation or driver error.

Precondition: buf is non-null for a nonzero request.; Inputs fit the driver 32-bit geometry.

Postcondition: Source blocks remain unchanged.; ctx remains untouched.

Note: The bound backend intentionally uses no context object.

Since: 0.1.0

◆ internal_lba_to_arg()

uint32_t internal_lba_to_arg ( uint32_t lba )

static

Convert an LBA to the card command argument.

Uses block addressing for SDHC and checked byte addressing otherwise.

Parameters

[in] lba Logical 512-byte block address.

Returns: Command argument for the active card type.

Return values

other LBA or byte-addressed LBA value.

Precondition: Card type was classified during initialization.; lba is within the published capacity.

Postcondition: No state or storage is modified.; The result follows the active card addressing mode.

Note: Caller range checks prevent byte-address overflow.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_prepare_init()

ra8_err_t internal_prepare_init ( const ra8_sdmmc_spi_transport_t * transport )

static

Validate and stage the transport for initialization.

Rejects reinitialization, copies callbacks, and selects the init clock.

Parameters

[in] transport Complete caller-owned transport descriptor.

Returns: ra8_err_t Preparation result.

Return values

k_ra8_ok	Transport state and init clock are ready.
other	Invalid state or clock callback failure.

Precondition: transport passed the public callback validation.; The caller owns the singleton initialization sequence.

Postcondition: Success binds the transport without publishing initialization.; Failure leaves initialized false.

Note: The transport descriptor is copied, not retained by address.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_read_block_crc_check()

ra8_err_t internal_read_block_crc_check ( const uint8_t * buf )

static

Read and verify the CRC trailer for one block.

Compares the two wire CRC bytes against CRC16 of caller data.

Parameters

[in] buf Complete block payload to authenticate.

Returns: ra8_err_t CRC validation result.

Return values

k_ra8_ok	Wire and computed CRC values match.
other	Transport failure or CRC mismatch.

Precondition: buf contains one complete block.; The stream is positioned at the CRC trailer.

Postcondition: Input payload remains unchanged.; Success authenticates the just-read block.

Note: CRC uses the SD SPI polynomial and seed.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_read_block_payload()

ra8_err_t internal_read_block_payload ( uint8_t * buf )

static

Read one 512-byte payload from the active data stream.

Clocks exactly one public block into caller storage.

Parameters

[out] buf Writable block-sized destination.

Returns: ra8_err_t Payload transfer result.

Return values

k_ra8_ok	Exactly one block was received.
other	Propagated transport failure.

Precondition: A valid data-start token was consumed.; buf addresses at least one block.

Postcondition: Success initializes every destination byte.; No bytes beyond the destination block are written.

Note: CRC bytes are handled separately.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_read_data_phase()

ra8_err_t internal_read_data_phase	(	uint32_t	lba,
		uint8_t *	buf )

static

Execute one complete CMD17 read data phase.

Sends the addressed command, waits for a token, reads data, and checks CRC.

Parameters

[in]	lba	Capacity-checked logical block address.
[out]	buf	Writable block destination.

Returns: ra8_err_t Single-block read result.

Return values

k_ra8_ok	One authenticated block was read.
other	Command, token, transfer, or CRC error.

Precondition: The driver is initialized and lba is in range.; buf addresses at least one block.

Postcondition: Chip select is released before return.; Success publishes a complete authenticated block.

Note: The public wrapper owns null and range validation.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_read_multi_stop()

ra8_err_t internal_read_multi_stop ( void )

static

Stop a CMD18 multi-block read stream.

Sends CMD12, accepts its stuff byte, and waits for card readiness.

Returns: ra8_err_t Stop-sequence result.

Return values

k_ra8_ok	The stream stopped and the card became ready.
other	Transport, response, or busy-timeout error.

Precondition: A CMD18 stream is active with chip select asserted.; The bound transport remains valid.

Postcondition: The card stop sequence was attempted exactly once.; Caller can release chip select after return.

Note: Stop is attempted even after an earlier stream error.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_write_data_block()

ra8_err_t internal_write_data_block	(	const uint8_t *	buf,
		uint8_t	start_token )

static

Transmit one data block, CRC trailer, and start token.

Validates the card data-response token and waits out programming busy.

Parameters

[in]	buf	Complete 512-byte source block.
[in]	start_token	Single- or multi-block data-start token.

Returns: ra8_err_t Data-block write result.

Return values

k_ra8_ok	The card accepted and programmed the block.
other	Transport, response, or busy-timeout error.

Precondition: Chip select is asserted for an accepted write command.; buf addresses one immutable source block.

Postcondition: Source bytes remain unchanged.; Success confirms the card left its programming-busy state.

Note: CRC16 is generated from the source payload.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_write_multi_stream()

ra8_err_t internal_write_multi_stream	(	const uint8_t *	buf,
		uint32_t	count )

static

Stream consecutive blocks for an accepted CMD25 operation.

Writes each source block, then sends the multi-block stop token.

Parameters

[in]	buf	Contiguous immutable source blocks.
[in]	count	Number of blocks to transmit.

Returns: ra8_err_t Stream result.

Return values

k_ra8_ok	Every block and the stop token were accepted.
other	First transfer, response, or busy error.

Precondition: buf addresses count complete blocks.; count is positive and capacity-checked.

Postcondition: Source storage remains unchanged.; The stop token is attempted before successful return.

Note: The caller releases chip select around the stream.

Since: 0.1.0

References RA8_INTERNAL.

Functions

Detailed Description

Function Documentation

◆ internal_cmd_require_ready()

◆ internal_erase_range()

◆ internal_finalize_init()

◆ internal_fs_erase_block()

◆ internal_fs_get_capacity()

◆ internal_fs_read_block()

◆ internal_fs_write_block()

◆ internal_lba_to_arg()

◆ internal_prepare_init()

◆ internal_read_block_crc_check()

◆ internal_read_block_payload()

◆ internal_read_data_phase()

◆ internal_read_multi_stop()

◆ internal_write_data_block()

◆ internal_write_multi_stream()