board_periph_sd.h File Reference

SD-card-over-SPI device model for ra8_emulator (attached to SPI_B). More...

#include <stdint.h>

Include dependency graph for board_periph_sd.h:

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

Go to the source code of this file.

Functions
bool	board_sd_attach (const char *path)
	Attach an SD-card image from a host file.
bool	board_sd_attached (void)
	Report whether an SD-card image is currently attached.
bool	board_sd_attach_blank (uint32_t total_sectors, uint8_t fat_bits, const char *label)
	Create a blank, FAT-formatted sparse SD card and attach it.
bool	board_sd_save (const char *path)
	Transactionally publish the current SD-card image to a file.
void	board_sd_info (bool *attached, uint64_t *bytes, uint8_t *fat_bits, const char **label)
	Read back the attached card's summary (for the status view / report).
uint8_t	board_sd_exchange (uint8_t tx)
	Exchange one full-duplex SPI byte with the modelled card.
bool	board_sd_read_block (uint32_t lba, uint8_t *dst)
	Copy one 512-byte block straight out of the backing image.
bool	board_sd_write_block (uint32_t lba, const uint8_t *src)
	Copy one 512-byte block straight into the backing image.
void	board_sd_reset (void)
	Reset the card's command / response framing to power-on.

Detailed Description

SD-card-over-SPI device model for ra8_emulator (attached to SPI_B).

Models a high-capacity (SDHC) SD card running in SPI mode, backed by a host image file passed with --sd. The SPI_B block model (board_periph_spi.c) routes each SPDR byte exchange into board_sd_exchange when a card is attached and the channel is NOT in internal loopback, so the firmware's genuine ra8_sdmmc_spi command / response / data-token path runs against a real FAT image.

The protocol handled: CMD0 / CMD8 / CMD55+ACMD41 / CMD58 / CMD9 (CSD) / CMD17 (single-block read), with R1/R3/R7 responses, the 0xFE data token, and CRC16-CCITT data CRCs. Commands self-frame off the 01xxxxxx lead bits, so no chip-select wiring is required.

Copyright

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

Since

0.1.0

Definition in file board_periph_sd.h.

Function Documentation

board_sd_attach()

bool board_sd_attach

(

const char *

path

)

Attach an SD-card image from a host file.

Copies the file into a private anonymous sparse working descriptor with fixed-size transfers, so firmware writes never mutate the source. A second successful call closes and replaces the prior working descriptor.

Parameters

[in]

path

Host path to a raw FAT image (512-byte sectors).

Returns

true if the image loaded and the card is armed; false on I/O error.

Return values

false

The file could not be opened or read.

Precondition

path is non-null.

Called once during ra8_emulator start-up (single-threaded).

Postcondition

On success board_sd_attached returns true.

On failure any previously attached card remains attached.

Note

Not thread-safe.

Since

0.1.0

Definition at line 267 of file board_periph_sd_image.c.

References emu_io_file_t::fd, g_board_sd, internal_adopt_image(), internal_close_fd(), internal_copy_bytes(), internal_create_sparse(), k_emu_io_ok, priv_emu_io_close(), priv_emu_io_errf(), priv_emu_io_open_read(), and emu_io_file_t::size.

Referenced by internal_args_try_sd().

board_sd_attach_blank()

bool board_sd_attach_blank	(	uint32_t	total_sectors,
		uint8_t	fat_bits,
		const char *	label )

Create a blank, FAT-formatted sparse SD card and attach it.

Sizes an anonymous sparse raw-file backend, then formats an empty FAT16 or FAT32 volume with fixed one-sector buffers (complete BPB + FAT media / EOC markers, valid to a host fsck_msdos and the firmware's ra8_fs).

Parameters

[in]	total_sectors	Card size in 512-byte sectors (>= 64).
[in]	fat_bits	16 for FAT16, 32 for FAT32 (other values -> FAT16).
[in]	label	Up to 11-char volume label (NULL -> blank).

Returns

true on success (a blank card is attached and serving).

Return values

false

Size too small, sparse-file creation failed, or formatting failed.

Precondition

Called once during ra8_emulator start-up (single-threaded).

Postcondition

On success board_sd_attached returns true.

Note

Not thread-safe.

Since

0.1.0

Precondition

The call executes on the emulator's single owning thread.

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 335 of file board_periph_sd_image.c.

References g_board_sd, internal_adopt_image(), internal_close_fd(), internal_create_sparse(), internal_report_created(), k_fat16_bits, k_fat32_bits, k_fmt_label_len, k_fmt_sec_bytes, k_sd_min_sectors, priv_board_sd_format_fat16(), priv_board_sd_format_fat32(), priv_board_sd_label_field(), and priv_emu_io_errf().

Referenced by internal_args_attach_blank_sd().

board_sd_attached()

bool board_sd_attached

(

void

)

Report whether an SD-card image is currently attached.

Returns

true if a card image is loaded and serving.

Return values

false

No --sd image was attached.

Precondition

None.

None.

Postcondition

No state is modified.

No state is modified.

Note

Not thread-safe.

Since

0.1.0

Report whether an sd-card image is currently attached; this step is contained within the board periph SD model and uses bounded caller or module-owned storage.

Definition at line 299 of file board_periph_sd_image.c.

References g_board_sd.

Referenced by internal_on_sdmmc_read_block(), internal_sci_reg_write(), and internal_spi_spdr_write().

board_sd_exchange()

uint8_t board_sd_exchange

(

uint8_t

tx

)

Exchange one full-duplex SPI byte with the modelled card.

Drives the SD SPI-mode state machine: command bytes are framed and answered with the matching R1/R3/R7 + data-token + block stream.

Parameters

[in]

tx

Byte clocked out by the host (host-out).

Returns

The byte the card drives back (card-out); 0xFF when idle.

Return values

255	Bus idle / no response pending.

Precondition

A card is attached (board_sd_attached is true).

None.

Postcondition

The model's command / response state may advance.

Reads leave storage unchanged; accepted write/erase commands update it.

Note

Not thread-safe.

Since

0.1.0

Definition at line 708 of file board_periph_sd.c.

References g_board_sd, internal_board_sd_process_cmd(), internal_board_sd_read_stream_next(), internal_board_sd_write_byte(), k_sd_cmd_len, k_sd_cmd_mask, k_sd_cmd_start, k_sd_idle, and k_sd_wr_idle.

Referenced by internal_sci_reg_write(), and internal_spi_spdr_write().

board_sd_info()

void board_sd_info	(	bool *	attached,
		uint64_t *	bytes,
		uint8_t *	fat_bits,
		const char **	label )

Read back the attached card's summary (for the status view / report).

Parameters

[out]	attached	Receives whether a card is attached (may be NULL).
[out]	bytes	Receives the card size in bytes, 64-bit for >4 GB (NULL ok).
[out]	fat_bits	Receives 12/16/32 if formatted by –sd-new, else 0 (NULL ok).
[out]	label	Receives a pointer to the NUL-terminated label (NULL ok).

Precondition

None.

Postcondition

No card state is modified.

Note

Not thread-safe.

Since

0.1.0

Read back the attached card's summary (for the status view / report); this step is contained within the board periph SD model and uses bounded caller or module-owned storage.

Precondition

The call executes on the emulator's single owning thread.

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 394 of file board_periph_sd_image.c.

References g_board_sd.

Referenced by internal_fill_status_hw(), internal_run_print_sd_summary(), and internal_sdhi_make_csd().

board_sd_read_block()

bool board_sd_read_block	(	uint32_t	lba,
		uint8_t *	dst )

Copy one 512-byte block straight out of the backing image.

The byte-identical data CMD17 would stream back, served in a single call so ra8_emulator's --fast-sd block-read hook can fill the firmware's sector buffer without clocking 512 individual SPI byte-exchanges through MMIO. Uses the same SDHC block-addressing (lba * 512) as the modelled CMD17 path, so the bytes delivered are exactly those the full protocol would produce.

Parameters

[in]	lba	Logical block address (SDHC block units).
[out]	dst	Destination for 512 bytes; must hold at least 512 bytes.

Returns

true if a card is attached, lba is in range, and the exact read succeeds.

Return values

false

No card is attached, the block is out of range, or backend I/O failed.

Precondition

dst is non-null and sized for >= 512 bytes.

A card image is attached (board_sd_attached is true).

Postcondition

On true, dst holds the block; the backing image is unmodified.

On false, dst is left unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 741 of file board_periph_sd.c.

References g_board_sd, internal_board_sd_fill_block(), k_sd_block, and memcpy().

Referenced by internal_on_sdmmc_read_block(), and internal_sdhi_load_block().

board_sd_reset()

void board_sd_reset

(

void

)

Reset the card's command / response framing to power-on.

Clears the in-flight command collector and pending response; the attached image and learned ready state are preserved.

Returns

None.

Precondition

None.

None.

Postcondition

Framing state is cleared; any attached image stays attached.

No host I/O is performed.

Note

Not thread-safe.

Since

0.1.0

Definition at line 775 of file board_periph_sd.c.

References g_board_sd, and k_sd_wr_idle.

Referenced by internal_spi_reset().

board_sd_save()

bool board_sd_save

(

const char *

path

)

Transactionally publish the current SD-card image to a file.

Copies through a bounded buffer into a same-directory private file, then syncs and renames only after the complete image is present.

Parameters

[in]

path

Output path for the raw card image.

Returns

true on success.

Return values

false

No card attached, or the file could not be written.

Precondition

A card is attached.

path is non-null, NUL-terminated, and names an accessible parent.

Postcondition

On success the host file atomically holds the current card contents.

On failure an existing target remains unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 366 of file board_periph_sd_image.c.

References emu_io_txn_t::fd, g_board_sd, internal_copy_bytes(), k_emu_io_ok, k_sd_save_max_bytes, k_unit_kib, priv_emu_io_errf(), priv_emu_io_txn_abort(), priv_emu_io_txn_begin(), and priv_emu_io_txn_commit().

Referenced by priv_run_cleanup().

board_sd_write_block()

bool board_sd_write_block	(	uint32_t	lba,
		const uint8_t *	src )

Copy one 512-byte block straight into the backing image.

The write-side mirror of board_sd_read_block: stores the byte-identical data a CMD24 single-block write would land, served in a single call so the native-SDHI block model can commit the firmware's sector buffer without clocking 128 individual SD_BUF0 FIFO words. Uses the same SDHC block-addressing (lba * 512) as the modelled CMD24 path, so the bytes stored are exactly those the full protocol would write.

Parameters

[in]	lba	Logical block address (SDHC block units).
[in]	src	Source of 512 bytes; must hold at least 512 bytes.

Returns

true if a card is attached, a full block fits, and the exact write succeeds.

Return values

false

No card is attached, the block is out of range, or backend I/O failed.

Precondition

src is non-null and sized for >= 512 bytes.

A card image is attached (board_sd_attached is true).

Postcondition

On true, the block at lba holds src.

On validation failure the backing image is unchanged.

On host-I/O failure the return value is false; a short positioned write may have made the progress reported internally by the raw-I/O seam.

Note

Not thread-safe.

Since

0.1.0

Definition at line 759 of file board_periph_sd.c.

References g_board_sd, k_sd_block, and priv_board_sd_storage_write().

Referenced by internal_sdhi_buf_write().