Native 4-bit SDHI raw-block round-trip on the EK-RA8D2 microSD (#123). More...

#include <stdint.h>
#include <string.h>
#include "ra8_board_ek_ra8d2.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_isr.h"
#include "ra8_log.h"
#include "ra8_sdcard.h"
#include "ra8_sdhi.h"
#include "ra8_time.h"

Include dependency graph for main.c:

Macros
#define	SDHI_CARD_PUTS(lit)
	Emit a NUL-terminated literal (length via sizeof at the call site).

Enumerations
enum	sdhi_card_config_t : uint32_t { k_sdhi_card_uart_baud = 115200U , k_sdhi_card_instance = 0U , k_sdhi_card_block_bytes = 512U , k_sdhi_card_test_lba = 64U , k_sdhi_card_block_count = 1U , k_sdhi_card_prng_seed = 0xC0FFEE11UL , k_sdhi_card_prng_mul = 1664525UL , k_sdhi_card_prng_add = 1013904223UL , k_sdhi_card_prng_byte_shift = 16U , k_sdhi_card_byte_mask = 0xFFU }
	Compile-time settings for the native-SDHI raw-block round-trip. More...

Functions
static void	sdhi_card_print (const uint8_t *msg, uint32_t len)
	Write a byte run on the J-Link OB VCOM console.
static void	sdhi_card_panic_halt (void)
	Halt forever in WFI – panic stop on irrecoverable failure.
static void	sdhi_card_setup_or_halt (void)
	Bring up CGC + SysTick + the board console + SDHI bus pins; panic on fail.
static void	sdhi_card_init_or_halt (void)
	Init the SD card over native SDHI, panic-halt on failure.
static void	sdhi_card_fill_payload (void)
	Fill the payload buffer with a deterministic LCG byte sequence.
static ra8_err_t	sdhi_card_check_capacity (void)
	Confirm the card capacity covers the test block, then check it is sane.
static ra8_err_t	sdhi_card_block_roundtrip (void)
	Write the payload, read it back, and byte-compare (raw SDHI blocks).
static ra8_err_t	sdhi_card_roundtrip (void)
	Run the capacity check + raw-block round-trip in order.
void	main (void)
	App entry: bring up the bus + card, raw-block round-trip, print PASS.

Variables
static const uint8_t	k_msg_boot [] = "ra8_sdhi_card_demo: boot\r\n"
static const uint8_t	k_msg_card_ok [] = "ra8_sdhi_card_demo: card ready\r\n"
static const uint8_t	k_msg_init_fail [] = "ra8_sdhi_card_demo: FAIL init\r\n"
static const uint8_t	k_msg_pass [] = "ra8_sdhi_card_demo: native SDHI block round-trip PASS\r\n"
static const uint8_t	k_msg_fail [] = "ra8_sdhi_card_demo: FAIL\r\n"
static const char *const	s_tag = "ra8_sdhi_card_demo"
	Module log tag.
static uint8_t	s_payload [k_sdhi_card_block_bytes]
	Static payload + read-back buffers (no heap; NASA Rule 3).
static uint8_t	s_readback [k_sdhi_card_block_bytes]

Detailed Description

Native 4-bit SDHI raw-block round-trip on the EK-RA8D2 microSD (#123).

Tag: [Ring 6 / APP] {World: S}

The minimal #123 deliverable: bring up the on-board microSD through the dedicated SDHI 4-bit host controller and prove a raw 512-byte block round-trip straight against the ra8_sdcard HAL – no ra8_io, no ra8_fs, no file system. The SD Physical Layer identification (CMD0 -> CMD8 -> ACMD41 -> CMD2 -> CMD3 -> CMD9 -> CMD7) and the polled 512-byte block read / write over the SD_BUF0 FIFO live in ra8_sdcard + ra8_sdhi; this app only routes the bus, runs init, then:

ra8_sdcard_get_capacity – confirm the card reports a non-zero size.
fill a 512-byte buffer with a deterministic LCG pattern.
ra8_sdcard_write_blocks(lba, payload, 1) – write one block.
ra8_sdcard_read_blocks(lba, readback, 1) – read it back.
byte-compare the read-back against the written payload.

On a clean round-trip it prints exactly ra8_sdhi_card_demo: native SDHI block round-trip PASS; any failed step prints ra8_sdhi_card_demo: FAIL and parks the CPU.

Under ra8_emulator the native-SDHI host-controller model (board_periph_sdhi.c) serves a card attached with --sd-new 64:fat16. On the bench a real microSD is wired to the port-4 SDHI bus. THIS APP OVERWRITES ONE BLOCK of the card.

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

Since: 0.1.0

Definition in file main.c.

Macro Definition Documentation

◆ SDHI_CARD_PUTS

#define SDHI_CARD_PUTS ( lit )

Value:

sdhi_card_print((lit), (uint32_t)sizeof(lit) - 1U)

sdhi_card_print

static void sdhi_card_print(const uint8_t *msg, uint32_t len)

Write a byte run on the J-Link OB VCOM console.

Definition main.c:116

Emit a NUL-terminated literal (length via sizeof at the call site).

Definition at line 122 of file main.c.

Referenced by main(), and sdhi_card_init_or_halt().

Enumeration Type Documentation

◆ sdhi_card_config_t

enum sdhi_card_config_t : uint32_t

Compile-time settings for the native-SDHI raw-block round-trip.

Enumerator
k_sdhi_card_uart_baud	J-Link OB CDC console baud.
k_sdhi_card_instance	SDHI0 drives the micro-SD bus.
k_sdhi_card_block_bytes	One SD block.
k_sdhi_card_test_lba	Block to round-trip (clear of the BPB).
k_sdhi_card_block_count	Round-trip one block.
k_sdhi_card_prng_seed	Deterministic payload seed.
k_sdhi_card_prng_mul	Numerical Recipes LCG multiplier.
k_sdhi_card_prng_add	Numerical Recipes LCG increment.
k_sdhi_card_prng_byte_shift	Bit shift selecting the PRNG byte.
k_sdhi_card_byte_mask	Low-byte mask.

Definition at line 59 of file main.c.

Function Documentation

◆ main()

void main ( void )

App entry: bring up the bus + card, raw-block round-trip, print PASS.

The application entry point Reset_Handler hands control to.

Brings up the clocks, console, and SDHI bus pins, runs the native SD card identification, fills the payload, then writes + reads + compares one raw 512-byte block straight against ra8_sdcard. On success it prints the exact PASS banner; on any failure it prints FAIL and parks the core.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On a clean run the CPU loops forever after the PASS banner.; On any failure the function prints FAIL and halts in WFI.

Note: Not thread-safe; this is the single-threaded app entry.

Since: 0.1.0

Definition at line 373 of file main.c.

References k_msg_boot, k_msg_fail, k_msg_pass, k_ra8_ok, ra8_board_uart_console_flush(), ra8_isr_globals_enable(), ra8_log_init(), sdhi_card_fill_payload(), sdhi_card_init_or_halt(), sdhi_card_panic_halt(), SDHI_CARD_PUTS, sdhi_card_roundtrip(), and sdhi_card_setup_or_halt().

◆ sdhi_card_block_roundtrip()

ra8_err_t sdhi_card_block_roundtrip ( void )

staticnodiscard

Write the payload, read it back, and byte-compare (raw SDHI blocks).

Calls ra8_sdcard_write_blocks then ra8_sdcard_read_blocks for one 512-byte block at k_sdhi_card_test_lba, then verifies the read-back equals the written payload. No file system is involved – this is the native-SDHI block primitive end-to-end.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Read-back matched the written payload.
k_ra8_err_checksum_mismatch	The read-back differed.
k_ra8_err_*	ra8_sdcard read / write failure.

Precondition: ra8_sdcard_init returned k_ra8_ok and s_payload is filled.; The test LBA is within the card capacity.

Postcondition: On k_ra8_ok the block at the test LBA holds s_payload.; s_readback holds the bytes read back from the card.

Note: Not thread-safe; mutates one card block + the read-back buffer.

Since: 0.1.0

Definition at line 307 of file main.c.

References k_ra8_err_checksum_mismatch, k_ra8_ok, k_sdhi_card_block_bytes, k_sdhi_card_block_count, k_sdhi_card_test_lba, memcmp(), memset(), RA8_RETURN_ON_ERROR, ra8_sdcard_read_blocks(), ra8_sdcard_write_blocks(), s_payload, s_readback, and s_tag.

Referenced by sdhi_card_roundtrip().

◆ sdhi_card_check_capacity()

ra8_err_t sdhi_card_check_capacity ( void )

staticnodiscard

Confirm the card capacity covers the test block, then check it is sane.

Queries ra8_sdcard_get_capacity and verifies the reported block count is non-zero and leaves room for the single test block at k_sdhi_card_test_lba, so the write / read below stay in range.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Capacity covers the test block.
k_ra8_err_out_of_range	The card is too small for the test block.
k_ra8_err_*	ra8_sdcard_get_capacity failure.

Precondition: ra8_sdcard_init returned k_ra8_ok.; The test LBA is a compile-time constant.

Postcondition: Card state is unchanged (pure query).; On k_ra8_ok the test LBA is within the card.

Note: Not thread-safe; single-threaded path.

Since: 0.1.0

Definition at line 276 of file main.c.

References k_ra8_err_out_of_range, k_ra8_ok, k_sdhi_card_test_lba, RA8_RETURN_ON_ERROR, ra8_sdcard_get_capacity(), and s_tag.

Referenced by sdhi_card_roundtrip().

◆ sdhi_card_fill_payload()

void sdhi_card_fill_payload ( void )

static

Fill the payload buffer with a deterministic LCG byte sequence.

Runs a Numerical-Recipes LCG over s_payload, selecting one byte per step, so the written content is reproducible and the read-back compare is a strong end-to-end check of the SDHI block path.

Returns: Nothing.

Precondition: s_payload is allocated (file-scope, always true).; The LCG constants are non-zero.

Postcondition: s_payload holds a reproducible byte pattern.; No other state is modified.

Note: Not thread-safe; mutates the shared payload buffer.

Since: 0.1.0

Definition at line 247 of file main.c.

References k_sdhi_card_block_bytes, k_sdhi_card_byte_mask, k_sdhi_card_prng_add, k_sdhi_card_prng_byte_shift, k_sdhi_card_prng_mul, k_sdhi_card_prng_seed, and s_payload.

Referenced by main().

◆ sdhi_card_init_or_halt()

void sdhi_card_init_or_halt ( void )

static

Init the SD card over native SDHI, panic-halt on failure.

Runs the full SD Physical Layer identification through ra8_sdcard_init on SDHI0 (which itself brings up the SDHI block), printing card ready on success or a FAIL init diagnostic before parking on failure.

Returns: Nothing (panic-halts on failure).

Precondition: The eight SDHI bus pins are routed.; A card is present in the SDHI slot.

Postcondition: On success the card is in TRAN state at default speed.; On failure a diagnostic is printed and the CPU is parked.

Note: Not thread-safe; call once after the SDHI pins are routed.

Since: 0.1.0

Definition at line 207 of file main.c.

References k_msg_card_ok, k_msg_init_fail, k_ra8_ok, k_ra8_sdhi_bus_width_4bit, k_sdhi_card_instance, ra8_sdcard_init(), sdhi_card_panic_halt(), and SDHI_CARD_PUTS.

Referenced by main().

◆ sdhi_card_panic_halt()

void sdhi_card_panic_halt ( void )

static

Halt forever in WFI – panic stop on irrecoverable failure.

Used after a fatal error has already been reported on the console; it parks the core so a debugger or the HIL runner can observe the state.

Returns: Never returns.

Precondition: A fatal error has been reported to the console.; The console output has been queued.

Postcondition: The CPU spins in WFI and never returns.; No further application code runs.

Note: Not thread-safe; this is a terminal panic path.

Since: 0.1.0

Definition at line 140 of file main.c.

Referenced by main(), sdhi_card_init_or_halt(), and sdhi_card_setup_or_halt().

◆ sdhi_card_print()

void sdhi_card_print	(	const uint8_t *	msg,
		uint32_t	len )

static

Write a byte run on the J-Link OB VCOM console.

Thin wrapper over ra8_board_uart_console_write; the return value is intentionally discarded because a diagnostic-print failure has no useful recovery on a panic path.

Parameters

[in]	msg	Bytes to emit (non-NULL, length `len`).
[in]	len	Byte count to emit.

Returns: Nothing.

Precondition: The board console is initialised.; msg points to at least len readable bytes.

Postcondition: The bytes are queued to the console.; No other state is modified.

Note: Not thread-safe; call from the single-threaded app context.

Since: 0.1.0

Definition at line 116 of file main.c.

References ra8_board_uart_console_write().

◆ sdhi_card_roundtrip()

ra8_err_t sdhi_card_roundtrip ( void )

staticnodiscard

Run the capacity check + raw-block round-trip in order.

Composes the two helpers so the first failing step short-circuits with its code; the success path is a single line per step.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Capacity ok and the block round-trip matched.
k_ra8_err_*	The first failing step's code.

Precondition: ra8_sdcard_init returned k_ra8_ok and s_payload is filled.; The test LBA is a compile-time constant.

Postcondition: On k_ra8_ok the card block at the test LBA holds the verified payload.; On any non-ok return the partial state is abandoned (caller halts).

Note: Not thread-safe; single-threaded round-trip.

Since: 0.1.0

Definition at line 344 of file main.c.

References k_ra8_ok, RA8_RETURN_ON_ERROR, s_tag, sdhi_card_block_roundtrip(), and sdhi_card_check_capacity().

Referenced by main().

◆ sdhi_card_setup_or_halt()

void sdhi_card_setup_or_halt ( void )

static

Bring up CGC + SysTick + the board console + SDHI bus pins; panic on fail.

Initialises the clock generator, caches CPUCLK0, starts the SysTick time base, brings the J-Link OB VCOM console up at 115200 8N1 via the BSP, then routes the eight SDHI0 bus pins via ra8_board_sdhi_pins_init. Any failing step panic-halts.

Returns: Nothing (panic-halts on failure).

Precondition: Reset_Handler initialised .data/.bss.; No other consumer owns the port-4 SDHI pins.

Postcondition: On success the console prints and the SDHI pins are routed.; On any failing step the core is parked in WFI.

Note: Not thread-safe; call once from the single-threaded init path.

Since: 0.1.0

Definition at line 170 of file main.c.

References k_ra8_clock_id_cpuclk0, k_ra8_ok, k_sdhi_card_uart_baud, ra8_board_sdhi_pins_init(), ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), ra8_time_init(), and sdhi_card_panic_halt().

Referenced by main().

Variable Documentation

◆ k_msg_boot

const uint8_t k_msg_boot[] = "ra8_sdhi_card_demo: boot\r\n"

static

Definition at line 82 of file main.c.

◆ k_msg_card_ok

const uint8_t k_msg_card_ok[] = "ra8_sdhi_card_demo: card ready\r\n"

static

Definition at line 83 of file main.c.

◆ k_msg_fail

const uint8_t k_msg_fail[] = "ra8_sdhi_card_demo: FAIL\r\n"

static

Definition at line 86 of file main.c.

◆ k_msg_init_fail

const uint8_t k_msg_init_fail[] = "ra8_sdhi_card_demo: FAIL init\r\n"

static

Definition at line 84 of file main.c.

◆ k_msg_pass

const uint8_t k_msg_pass[] = "ra8_sdhi_card_demo: native SDHI block round-trip PASS\r\n"

static

Definition at line 85 of file main.c.

◆ s_payload

uint8_t s_payload[k_sdhi_card_block_bytes]

static

Static payload + read-back buffers (no heap; NASA Rule 3).

Definition at line 227 of file main.c.

◆ s_readback

uint8_t s_readback[k_sdhi_card_block_bytes]

static

Definition at line 228 of file main.c.

◆ s_tag

const char* const s_tag = "ra8_sdhi_card_demo"

static

Module log tag.

Definition at line 89 of file main.c.

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SDHI_CARD_PUTS

Enumeration Type Documentation

◆ sdhi_card_config_t

Function Documentation

◆ main()

◆ sdhi_card_block_roundtrip()

◆ sdhi_card_check_capacity()

◆ sdhi_card_fill_payload()

◆ sdhi_card_init_or_halt()

◆ sdhi_card_panic_halt()

◆ sdhi_card_print()

◆ sdhi_card_roundtrip()

◆ sdhi_card_setup_or_halt()

Variable Documentation

◆ k_msg_boot

◆ k_msg_card_ok

◆ k_msg_fail

◆ k_msg_init_fail

◆ k_msg_pass

◆ s_payload

◆ s_readback

◆ s_tag