board_periph_sd_internal.h File Reference

Module-private FAT formatter shared by the board_periph_sd TUs. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"

Include dependency graph for board_periph_sd_internal.h:

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

Go to the source code of this file.

Data Structures
struct	board_sd_state_t
	The modelled card: backing image + command/response framing. More...

Enumerations
enum	board_sd_const_t : uint16_t {   k_sd_block = 512U ,   k_sd_cmd_len = 6U ,   k_sd_resp_cap = 520U ,   k_sd_cmd_start = 0x40U ,   k_sd_cmd_mask = 0xC0U ,   k_sd_idx_mask = 0x3FU ,   k_sd_idle = 0xFFU ,   k_sd_tok_data = 0xFEU ,   k_sd_tok_wmulti = 0xFCU ,   k_sd_tok_stop = 0xFDU ,   k_sd_data_accept = 0x05U ,   k_sd_data_error = 0x0DU ,   k_sd_read_error = 0x01U ,   k_sd_busy = 0x00U ,   k_sd_crc_len = 2U ,   k_sd_label_cap = 12U ,   k_sd_r1_idle = 0x01U ,   k_sd_r1_ready = 0x00U ,   k_sd_r1_param_err = 0x40U ,   k_sd_byte_mask = 0xFFU ,   k_sd_byte_bits = 8U ,   k_sd_r7_len = 5U ,   k_sd_arg_sh0 = 24U ,   k_sd_arg_sh1 = 16U ,   k_sd_cmd8_echo = 0xAAU ,   k_sd_ocr_pwrccs = 0xC0U ,   k_sd_ocr_volt = 0x80U ,   k_sd_csd_v2 = 0x40U ,   k_sd_csd_csize = 0x0FU ,   k_sd_csd_len = 16U ,   k_sd_csd_csize_b7 = 7U ,   k_sd_csd_csize_b8 = 8U ,   k_sd_csd_off = 9U ,   k_sd_csize_b7_mask = 0x3FU ,   k_sd_crc_poly = 0x1021U ,   k_sd_crc_msb = 0x8000U }
	SD SPI-mode protocol and sizing constants (no magic numbers). More...
enum	board_sd_wr_phase_t : uint8_t {   k_sd_wr_idle = 0U ,   k_sd_wr_token = 1U ,   k_sd_wr_data = 2U ,   k_sd_wr_crc = 3U }
	Block-write sub-state once a CMD24/CMD25 has been accepted. More...
enum	board_sd_const32_t : uint32_t {   k_sd_csd_unit = 512U * 1024U ,   k_sd_save_max_bytes = 2U * 1024U * 1024U * 1024U ,   k_unit_kib = 1024U ,   k_sd_min_sectors = 64U }
	SD sizing constants that exceed 16 bits. More...
enum	sd_fat_bits_t : uint32_t {   k_fat32_bits = 32U ,   k_fat16_bits = 16U }
	FAT flavour selectors shared by the formatter and the card model. More...
enum	sd_fmt_const_t : uint32_t {   k_fmt_sec_bytes = 512U ,   k_fmt_fat16_max = 65524U ,   k_fmt_fat16_min = 4085U ,   k_fmt_spc_max = 64U ,   k_fmt_fat32_pref = 4194304U ,   k_fmt_root_ents = 512U ,   k_fmt_volid = 0x52A8D200U ,   k_fmt_resv_f16 = 1U ,   k_fmt_resv_f32 = 32U ,   k_fmt_label_len = 11U ,   k_fmt_totsec16_max = 0x10000U }
	FAT BPB field offsets + format constants. More...

Functions
bool	priv_board_sd_format_fat16 (int image_fd, uint32_t total_sectors, const char *label, uint32_t *out_spc)
	Format the attached sparse backend as a FAT16 volume.
bool	priv_board_sd_format_fat32 (int image_fd, uint32_t total_sectors, const char *label, uint32_t *out_spc)
	Format the attached sparse backend as a FAT32 volume.
bool	priv_board_sd_storage_read (uint64_t offset, void *dst, size_t count)
	Read exactly from the current sparse backend at a checked byte offset.
bool	priv_board_sd_storage_write (uint64_t offset, const void *src, size_t count)
	Write exactly to the current sparse backend at a checked byte offset.
bool	priv_board_sd_storage_zero (uint64_t offset, uint64_t count)
	Make a checked byte range read as zero while preserving sparse storage.
void	priv_board_sd_label_field (uint8_t *dst, const char *label)
	Copy a volume label into an 11-char space-padded 8.3 field.

Variables
board_sd_state_t	g_board_sd
	The single modelled SD card (defined in board_periph_sd.c).

Detailed Description

Module-private FAT formatter shared by the board_periph_sd TUs.

Carries what the three board_periph_sd translation units share: the modelled card's state type and the single instance of it, the SD SPI sizing constants that type is built from, and the blank-card (–sd-new) FAT16/FAT32 bounded sector formatters. board_periph_sd.c models the SPI protocol, board_periph_sd_image.c owns the sparse raw-file lifecycle, and board_periph_sd_format.c serializes the initial sectors through that backend.

Copyright

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

Since

0.1.0

Definition in file board_periph_sd_internal.h.

Enumeration Type Documentation

board_sd_const32_t

enum board_sd_const32_t : uint32_t

SD sizing constants that exceed 16 bits.

Enumerator
k_sd_csd_unit	CSD v2.0 C_SIZE unit: 512 KiB.
k_sd_save_max_bytes	–save-sd cap: 2 GiB.
k_unit_kib	Binary kilo multiplier (KiB).
k_sd_min_sectors	–sd-new floor: 32 KiB of sectors.

Definition at line 113 of file board_periph_sd_internal.h.

board_sd_const_t

enum board_sd_const_t : uint16_t

SD SPI-mode protocol and sizing constants (no magic numbers).

Enumerator
k_sd_block	Bytes per SD block.
k_sd_cmd_len	Command frame: opcode + 4 arg + crc.
k_sd_resp_cap	R1 + token + 512 data + 2 CRC.
k_sd_cmd_start	SPI command lead bits (01xxxxxx).
k_sd_cmd_mask	Mask isolating the lead bits.
k_sd_idx_mask	Command index in the lead byte.
k_sd_idle	Bus idle / CIPO-high byte.
k_sd_tok_data	Single-block read / write data token.
k_sd_tok_wmulti	Multi-block write data-start token.
k_sd_tok_stop	Multi-block write stop-tran token.
k_sd_data_accept	Data-response token: block accepted.
k_sd_data_error	Data-response token: backend write error.
k_sd_read_error	Read data-error token: backend fault.
k_sd_busy	CIPO held low while the card programs.
k_sd_crc_len	Trailing CRC16 bytes after a data block.
k_sd_label_cap	Volume-label field: 11 chars + NUL.
k_sd_r1_idle	R1 with IDLE set.
k_sd_r1_ready	R1, card ready.
k_sd_r1_param_err	R1 parameter/backend range error.
k_sd_byte_mask	Low byte mask.
k_sd_byte_bits	Bits per byte (shift amount).
k_sd_r7_len	R1 + 4-byte tail.
k_sd_arg_sh0	Arg byte 0 (MSB) shift.
k_sd_arg_sh1	Arg byte 1 shift.
k_sd_cmd8_echo	CMD8 check pattern echo.
k_sd_ocr_pwrccs	OCR byte 0: power-up done + CCS.
k_sd_ocr_volt	OCR byte 2: voltage window.
k_sd_csd_v2	CSD_STRUCTURE = 01b (v2.0 / SDHC).
k_sd_csd_csize	C_SIZE byte (=> 8 MiB modelled card).
k_sd_csd_len	CSD register length.
k_sd_csd_csize_b7	C_SIZE high byte offset in the CSD.
k_sd_csd_csize_b8	C_SIZE mid byte offset in the CSD.
k_sd_csd_off	C_SIZE LSB byte offset in the CSD.
k_sd_csize_b7_mask	C_SIZE field spans only 6 bits in b7.
k_sd_crc_poly	CRC16-CCITT polynomial.
k_sd_crc_msb	Top bit of the 16-bit CRC register.

Definition at line 33 of file board_periph_sd_internal.h.

board_sd_wr_phase_t

enum board_sd_wr_phase_t : uint8_t

Block-write sub-state once a CMD24/CMD25 has been accepted.

Enumerator
k_sd_wr_idle	Not in a write transaction.
k_sd_wr_token	Awaiting the data-start (or stop-tran) token.
k_sd_wr_data	Collecting the 512 payload bytes.
k_sd_wr_crc	Collecting the trailing 2 CRC bytes.

Definition at line 76 of file board_periph_sd_internal.h.

sd_fat_bits_t

enum sd_fat_bits_t : uint32_t

FAT flavour selectors shared by the formatter and the card model.

Enumerator
k_fat32_bits	FAT32 selector / label width.
k_fat16_bits	FAT16 selector.

Definition at line 124 of file board_periph_sd_internal.h.

sd_fmt_const_t

enum sd_fmt_const_t : uint32_t

FAT BPB field offsets + format constants.

Enumerator
k_fmt_sec_bytes	Bytes per sector.
k_fmt_fat16_max	Max FAT16 data clusters.
k_fmt_fat16_min	Min FAT16 data clusters.
k_fmt_spc_max	Largest sectors-per-cluster we pick.
k_fmt_fat32_pref	FAT32: preferred max clusters (bumps spc).
k_fmt_root_ents	FAT16 root-directory entries.
k_fmt_volid	Arbitrary volume serial base.
k_fmt_resv_f16	FAT16 reserved sectors (boot).
k_fmt_resv_f32	FAT32 reserved sectors.
k_fmt_label_len	8.3 volume-label field width.
k_fmt_totsec16_max	Above this, use the 32-bit TotSec.

Definition at line 130 of file board_periph_sd_internal.h.

Function Documentation

priv_board_sd_format_fat16()

bool priv_board_sd_format_fat16 ( int image_fd, uint32_t total_sectors, const char * label, uint32_t * out_spc )

nodiscard

Format the attached sparse backend as a FAT16 volume.

Writes a complete BPB (boot frame, geometry, label, volume id), the signature bytes and the FAT[0]/FAT[1] reserved entries – enough to satisfy a host fsck_msdos and the firmware's ra8_fs mount alike.

Parameters

[in]	image_fd	Sized sparse backing descriptor to format.
[in]	total_sectors	Card capacity in 512-byte sectors.
[in]	label	Volume label (space-padded to 11 chars).
[out]	out_spc	Receives the selected sectors per cluster.

Returns

Whether every required sector was written exactly.

Return values

true	The empty FAT16 volume was serialized.
false	A positioned backend write failed.

Precondition

image_fd is writable and sized for total_sectors sectors.

total_sectors fits FAT16 cluster limits (caller picked FAT16).

Postcondition

The image mounts as an empty FAT16 volume.

Note

Uses only fixed one-sector buffers; not thread-safe.

Since

0.1.0

Definition at line 306 of file board_periph_sd_format.c.

References internal_fat16_solve_geometry(), internal_fat16_write_bpb(), internal_sd_put16(), internal_write_sector(), k_bpb_dir_ent_size, k_bpb_num_fats_val, k_fat16_eoc_clus0, k_fat16_eoc_clus1, k_fat_ent1_off, k_fmt_resv_f16, k_fmt_root_ents, k_fmt_sec_bytes, and k_le_byte0.

Referenced by board_sd_attach_blank().

priv_board_sd_format_fat32()

bool priv_board_sd_format_fat32 ( int image_fd, uint32_t total_sectors, const char * label, uint32_t * out_spc )

nodiscard

Format the attached sparse backend as a FAT32 volume.

Writes the FAT32 BPB (with FSInfo + backup boot sectors), the root-directory cluster chain and both FAT copies' reserved entries.

Parameters

[in]	image_fd	Sized sparse backing descriptor to format.
[in]	total_sectors	Card capacity in 512-byte sectors.
[in]	label	Volume label (space-padded to 11 chars).
[out]	out_spc	Receives the selected sectors per cluster.

Returns

Whether every required sector was written exactly.

Return values

true	The empty FAT32 volume was serialized.
false	A positioned backend write failed.

Precondition

image_fd is writable and sized for total_sectors sectors.

total_sectors warrants FAT32 (caller picked FAT32).

Postcondition

The image mounts as an empty FAT32 volume.

Note

Uses only fixed one-sector buffers; not thread-safe.

Since

0.1.0

Definition at line 435 of file board_periph_sd_format.c.

References internal_fat32_write_bpb(), internal_sd_fat32_geometry(), internal_sd_put32(), internal_write_sector(), k_bpb_num_fats_val, k_fat32_bkboot_sec, k_fat32_ent1_off, k_fat32_ent2_off, k_fat32_eoc, k_fat32_eoc_media, k_fat32_fsinfo_sec, k_fmt_resv_f32, k_fmt_sec_bytes, k_fsi_free_unknown, k_fsi_lead_sig, k_fsi_nxt_free, k_fsi_off_free, k_fsi_off_lead, k_fsi_off_nxtfree, k_fsi_off_struc, k_fsi_off_trail, k_fsi_struc_sig, k_fsi_trail_sig, and k_le_byte0.

Referenced by board_sd_attach_blank().

priv_board_sd_label_field()

void priv_board_sd_label_field	(	uint8_t *	dst,
		const char *	label )

Copy a volume label into an 11-char space-padded 8.3 field.

Reads at most 11 input bytes, stops at the first NUL, and fills every remaining on-disk field byte with an ASCII space.

Parameters

[out]	dst	Destination 11-byte label field.
[in]	label	NUL-terminated label (truncated to 11 chars).

Returns

Nothing.

Precondition

dst holds at least 11 bytes.

label is NUL-terminated.

Postcondition

dst is space-padded to the full field width.

No byte beyond the fixed 11-byte destination field is changed.

Note

Pure buffer transform; thread-safe on distinct buffers.

Since

0.1.0

Copy a volume label into an 11-char space-padded 8.3 field.

Definition at line 176 of file board_periph_sd_format.c.

References k_fmt_label_len.

Referenced by board_sd_attach_blank(), internal_fat16_write_bpb(), and internal_fat32_write_bpb().

priv_board_sd_storage_read()

bool priv_board_sd_storage_read ( uint64_t offset, void * dst, size_t count )

nodiscard

Read exactly from the current sparse backend at a checked byte offset.

Definition at line 193 of file board_periph_sd_image.c.

References g_board_sd, internal_range_valid(), k_emu_io_ok, priv_emu_io_pread_exact(), and emu_io_result_t::status.

Referenced by internal_board_sd_fill_block().

priv_board_sd_storage_write()

bool priv_board_sd_storage_write ( uint64_t offset, const void * src, size_t count )

nodiscard

Write exactly to the current sparse backend at a checked byte offset.

Definition at line 203 of file board_periph_sd_image.c.

References g_board_sd, internal_range_valid(), k_emu_io_ok, priv_emu_io_pwrite_exact(), and emu_io_result_t::status.

Referenced by board_sd_write_block(), internal_sd_write_crc(), and internal_write_zeros().

priv_board_sd_storage_zero()

bool priv_board_sd_storage_zero ( uint64_t offset, uint64_t count )

nodiscard

Make a checked byte range read as zero while preserving sparse storage.

Definition at line 243 of file board_periph_sd_image.c.

References g_board_sd, and internal_write_zeros().

Referenced by internal_board_sd_cmd_erase().

Variable Documentation

g_board_sd

board_sd_state_t g_board_sd

extern

The single modelled SD card (defined in board_periph_sd.c).

The single modelled SD card (defined in board_periph_sd.c).

Definition at line 81 of file board_periph_sd.c.

Referenced by board_sd_attach(), board_sd_attach_blank(), board_sd_attached(), board_sd_exchange(), board_sd_info(), board_sd_read_block(), board_sd_reset(), board_sd_save(), board_sd_write_block(), internal_adopt_image(), internal_range_valid(), internal_release_image(), priv_board_sd_storage_read(), priv_board_sd_storage_write(), and priv_board_sd_storage_zero().