Prove the ra8_io fabric's swappable backend (#155/#156) over a microSD. More...

#include <stdint.h>
#include "ra8_attributes.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_io.h"
#include "ra8_io_roundtrip.h"
#include "ra8_isr.h"
#include "ra8_log.h"
#include "ra8_port_utils.h"
#include "ra8_sdmmc_spi.h"
#include "ra8_time.h"

Include dependency graph for main.c:

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

Enumerations
enum	sd_demo_config_t : uint32_t { k_sd_demo_uart_baud = 115200U , k_sd_demo_spi_channel = 0U , k_sd_demo_payload_bytes = 512U }
	Compile-time settings for the ra8_io SD-backend demo. More...

Functions
static void	internal_sd_demo_print (const uint8_t *msg, uint32_t len)
	Write a byte run on the SCI8 console.
static void	internal_sd_demo_panic_halt (void)
	Halt forever in WFI – panic stop on irrecoverable failure.
static void	internal_sd_demo_setup_or_halt (uint32_t *out_pclka_hz)
	Bring up CGC + SysTick + console SCI; panic on fail.
static void	internal_sd_demo_init_card_or_halt (uint32_t pclka_hz)
	Build the SCI-SPI transport, init the SD driver, panic-halt on failure.
static ra8_err_t	internal_sd_demo_roundtrip (void)
	Bind the SD-SPI block device and run the shared ra8_io round-trip.
void	main (void)
	App entry: bring up the bus + card, run the ra8_io round-trip, print PASS.

Variables
static const ra8_port_pin_t	s_sd_demo_pin_sck = (ra8_port_pin_t)k_ra8_board_pmod2_spi_sck
	Pmod2 SCI0 clock pin used by the SD-SPI transport.
static const ra8_port_pin_t	s_sd_demo_pin_cipo = (ra8_port_pin_t)k_ra8_board_pmod2_spi_cipo
	Pmod2 SCI0 controller-input pin used by the SD-SPI transport.
static const ra8_port_pin_t	s_sd_demo_pin_copi = (ra8_port_pin_t)k_ra8_board_pmod2_spi_copi
	Pmod2 SCI0 controller-output pin used by the SD-SPI transport.
static const ra8_port_pin_t	s_sd_demo_pin_cs = (ra8_port_pin_t)k_ra8_board_pmod2_spi_cs
	Pmod2 GPIO chip-select pin used by the SD-SPI transport.
static const uint8_t	s_msg_boot [] = "ra8_io_sd_demo: boot\r\n"
	HIL banner emitted before SD initialization starts.
static const uint8_t	s_msg_card_ok [] = "ra8_io_sd_demo: card ready\r\n"
	HIL banner emitted after the SD card enters SPI mode.
static const uint8_t	s_msg_init_fail [] = "ra8_io_sd_demo: FAIL init\r\n"
	Diagnostic emitted when transport or card initialization fails.
static const uint8_t	s_msg_pass [] = "ra8_io_sd_demo: sd:/LOGS/A.TXT 512 bytes PASS\r\n"
	HIL success banner emitted after the verified file round-trip.
static const uint8_t	s_msg_fail [] = "ra8_io_sd_demo: FAIL\r\n"
	Diagnostic emitted when the VFS round-trip fails.
static const char *const	s_tag = "ra8_io_sd_demo"
	Module log tag.
static ra8_io_blockdev_t	s_bd
	ra8_io block device + ra8_fs backend bridged onto the SD card.
static ra8_fs_backend_t	s_be
static const ra8_io_roundtrip_params_t	s_params
	Shared round-trip parameters for this SD-backed FAT32 volume.

Detailed Description

Prove the ra8_io fabric's swappable backend (#155/#156) over a microSD.

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

Companion to ra8_io_demo, which runs the ra8_io VFS over a RAM disk. This app runs the IDENTICAL ra8_io VFS API over a real micro-SD card by swapping only the block-device backend: instead of the RAM backend it binds the ra8_io SD-over-SPI block device (ra8_io_blockdev_sdspi_init) on top of the ra8_sdmmc_spi driver. The Pmod2 / SCI0 Simple-SPI bus comes up in one library call – ra8_sdmmc_spi_transport_sci routes the four pins, claims CS, brings up SCI0 Simple-SPI, and fills the transport vtable – matching the SDHI demo's one-line ra8_sdcard_init ergonomics. The data path above the block device is this app's self-contained ra8_io_roundtrip.{h,c} helper (the SDRAM / OSPI / SD demos under hw_pending carry their own copy) – this app differs only by the SD-SPI transport factory call plus the ONE backend bind line and its own PASS banner.

On a clean round-trip it prints exactly ra8_io_sd_demo: sd:/LOGS/A.TXT 512 bytes PASS; any failed step prints ra8_io_sd_demo: FAIL and parks the CPU. The HIL runner and the ra8_emulator smoke gate scrape for that PASS line.

Required external hardware (on-bench): Digilent PMOD MicroSD (part 410-380) in Pmod2 (J25) with any microSD card inserted. THIS APP ERASES THE CARD: it self-formats a fresh FAT32 volume, so any blank card works (FAT32 handles the multi-GB cards a real SD slot sees – FAT16's 2 GB ceiling does not). Under ra8_emulator attach a blank card with --sd-new 64:fat16 (the firmware reformats it FAT32 regardless of the seed type; only the capacity matters).

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

Since: 0.1.0

Definition in file main.c.

Macro Definition Documentation

◆ SD_DEMO_PUTS

#define SD_DEMO_PUTS ( lit )

Value:

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

internal_sd_demo_print

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

Write a byte run on the SCI8 console.

Definition main.c:152

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

Definition at line 158 of file main.c.

Referenced by internal_sd_demo_init_card_or_halt(), and main().

Enumeration Type Documentation

◆ sd_demo_config_t

enum sd_demo_config_t : uint32_t

Compile-time settings for the ra8_io SD-backend demo.

Enumerator
k_sd_demo_uart_baud	J-Link OB CDC console baud.
k_sd_demo_spi_channel	Pmod2 / J25 SCI0 Simple-SPI.
k_sd_demo_payload_bytes	One-sector deterministic test payload.

Definition at line 63 of file main.c.

Function Documentation

◆ internal_sd_demo_init_card_or_halt()

void internal_sd_demo_init_card_or_halt ( uint32_t pclka_hz )

static

Build the SCI-SPI transport, init the SD driver, panic-halt on failure.

The whole SD-SPI bring-up now collapses to two library calls: the ra8_sdmmc_spi SCI transport factory routes the four Pmod2 pins, claims CS, brings up SCI0 Simple-SPI, and fills the transport vtable; ra8_sdmmc_spi_init then runs the SD identification sequence. Prints card ready on success or a FAIL init diagnostic before parking.

Parameters

[in] pclka_hz Live PCLKA rate (Hz) feeding the SCI baud divider.

Returns: Nothing (panic-halts on failure).

Precondition: ra8_cgc_init has run and the console SCI is up.; pclka_hz is the live PCLKA rate.

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

Note: Not thread-safe; call once after the clocks + console are up.

Since: 0.1.0

Definition at line 256 of file main.c.

References internal_sd_demo_panic_halt(), k_ra8_ok, k_sd_demo_spi_channel, RA8_INTERNAL, ra8_sdmmc_spi_init(), ra8_sdmmc_spi_transport_sci(), s_msg_card_ok, s_msg_init_fail, s_sd_demo_pin_cipo, s_sd_demo_pin_copi, s_sd_demo_pin_cs, s_sd_demo_pin_sck, and SD_DEMO_PUTS.

Referenced by main().

◆ internal_sd_demo_panic_halt()

void internal_sd_demo_panic_halt ( void )

static

Halt forever in WFI – panic stop on irrecoverable failure.

Used after a fatal bring-up or round-trip error has already been reported on the console; it parks the core so a debugger or the HIL runner can observe the final 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 177 of file main.c.

References RA8_INTERNAL.

Referenced by internal_sd_demo_init_card_or_halt(), internal_sd_demo_setup_or_halt(), and main().

◆ internal_sd_demo_print()

void internal_sd_demo_print	(	const uint8_t *	msg,
		uint32_t	len )

static

Write a byte run on the SCI8 console.

Thin wrapper over ra8_board_uart_console_write so the demo's print sites stay terse; 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: SCI8 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 152 of file main.c.

References ra8_board_uart_console_write(), and RA8_INTERNAL.

◆ internal_sd_demo_roundtrip()

ra8_err_t internal_sd_demo_roundtrip ( void )

staticnodiscard

Bind the SD-SPI block device and run the shared ra8_io round-trip.

This is the "swappable backend" core: the only difference from the RAM / SDRAM / OSPI demos is that the block device bound here is the SD-over-SPI backend. After binding, the shared helper formats + mounts a FAT32 volume under "sd" and runs the mkdir + nested round-trip into sd:/LOGS/A.TXT. The VFS is initialised first because this app does not rely on an earlier mount having done so.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Backend bound, FAT32 formatted + mounted, round-trip passed.
k_ra8_err_*	The first failing fabric step's code.

Precondition: The SD card is initialised (ra8_sdmmc_spi_init succeeded).; The VFS mount table has a free slot named distinctly from "sd".

Postcondition: On success sd:/LOGS/A.TXT holds the verified payload.; No file handle is left open on any return path.

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

Since: 0.1.0

Definition at line 304 of file main.c.

References RA8_INTERNAL, ra8_io_blockdev_sdspi_init(), ra8_io_roundtrip_mount(), ra8_io_roundtrip_subdir_file(), ra8_io_vfs_init(), RA8_RETURN_ON_ERROR, s_bd, s_be, s_params, and s_tag.

Referenced by main().

◆ internal_sd_demo_setup_or_halt()

void internal_sd_demo_setup_or_halt ( uint32_t * out_pclka_hz )

static

Bring up CGC + SysTick + console SCI; panic on fail.

Initialises the clock generator, caches CPUCLK0 and PCLKA, starts the SysTick time base, and brings up the SCI8 J-Link console via the board-support package (ra8_board_uart_console_init), which routes PD02 TXD / PD03 RXD and configures SCI8 async at the given baud. The Pmod2 SD SPI bus is brought up later by the ra8_sdmmc_spi SCI transport factory, so this routine only owns the clocks + console. Any failing step panic-halts so a misconfigured console never reaches the SD bring-up.

Parameters

[out] out_pclka_hz Cached PCLKA rate (Hz) handed to the transport factory.

Returns: Nothing (panic-halts on failure).

Precondition: Reset_Handler initialised .data/.bss.; out_pclka_hz is writable.

Postcondition: On success the console prints and *out_pclka_hz holds the PCLKA rate.; On any failure the CPU is parked in WFI.

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

Since: 0.1.0

Definition at line 213 of file main.c.

References internal_sd_demo_panic_halt(), k_ra8_clock_id_cpuclk0, k_ra8_clock_id_pclka, k_ra8_ok, k_sd_demo_uart_baud, ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), RA8_INTERNAL, and ra8_time_init().

Referenced by main().

◆ main()

void main ( void )

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

The application entry point Reset_Handler hands control to.

Brings up the clocks, console, SPI, and SD card, then runs the shared ra8_io VFS round-trip over the SD-over-SPI block device. On success it prints the exact PASS banner the HIL runner and ra8_emulator smoke gate scrape for; 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 334 of file main.c.

References internal_sd_demo_init_card_or_halt(), internal_sd_demo_panic_halt(), internal_sd_demo_roundtrip(), internal_sd_demo_setup_or_halt(), k_ra8_ok, ra8_board_uart_console_flush(), ra8_isr_globals_enable(), ra8_log_init(), s_msg_boot, s_msg_fail, s_msg_pass, and SD_DEMO_PUTS.

Variable Documentation

◆ s_bd

ra8_io_blockdev_t s_bd

static

ra8_io block device + ra8_fs backend bridged onto the SD card.

Definition at line 110 of file main.c.

◆ s_be

ra8_fs_backend_t s_be

static

Definition at line 111 of file main.c.

◆ s_msg_boot

const uint8_t s_msg_boot[] = "ra8_io_sd_demo: boot\r\n"

static

HIL banner emitted before SD initialization starts.

Definition at line 92 of file main.c.

◆ s_msg_card_ok

const uint8_t s_msg_card_ok[] = "ra8_io_sd_demo: card ready\r\n"

static

HIL banner emitted after the SD card enters SPI mode.

Definition at line 95 of file main.c.

Referenced by internal_sd_demo_init_card_or_halt().

◆ s_msg_fail

const uint8_t s_msg_fail[] = "ra8_io_sd_demo: FAIL\r\n"

static

Diagnostic emitted when the VFS round-trip fails.

Definition at line 104 of file main.c.

Referenced by internal_rc_setup_or_halt(), internal_setup_or_halt(), internal_td_setup_or_halt(), and main().

◆ s_msg_init_fail

const uint8_t s_msg_init_fail[] = "ra8_io_sd_demo: FAIL init\r\n"

static

Diagnostic emitted when transport or card initialization fails.

Definition at line 98 of file main.c.

Referenced by internal_sd_demo_init_card_or_halt().

◆ s_msg_pass

const uint8_t s_msg_pass[] = "ra8_io_sd_demo: sd:/LOGS/A.TXT 512 bytes PASS\r\n"

static

HIL success banner emitted after the verified file round-trip.

Definition at line 101 of file main.c.

◆ s_params

const ra8_io_roundtrip_params_t s_params

static

Initial value:

                                                = {
  .vfs_prefix   = "sd",
  .fat_type     = k_ra8_fs_type_fat32,
  .volume_label = "RAIOSD",
  .log_tag      = s_tag,
  .root_file    = "",
  .root_path    = "",
  .root_bytes   = 0U,
  .subdir_path  = "sd:/LOGS",
  .subdir_file  = "sd:/LOGS/A.TXT",
  .subdir_bytes = (uint32_t)k_sd_demo_payload_bytes,
}

Shared round-trip parameters for this SD-backed FAT32 volume.

Definition at line 114 of file main.c.

◆ s_sd_demo_pin_cipo

const ra8_port_pin_t s_sd_demo_pin_cipo = (ra8_port_pin_t)k_ra8_board_pmod2_spi_cipo

static

Pmod2 SCI0 controller-input pin used by the SD-SPI transport.

Definition at line 78 of file main.c.

Referenced by internal_sd_demo_init_card_or_halt().

◆ s_sd_demo_pin_copi

const ra8_port_pin_t s_sd_demo_pin_copi = (ra8_port_pin_t)k_ra8_board_pmod2_spi_copi

static

Pmod2 SCI0 controller-output pin used by the SD-SPI transport.

Definition at line 81 of file main.c.

Referenced by internal_sd_demo_init_card_or_halt().

◆ s_sd_demo_pin_cs

const ra8_port_pin_t s_sd_demo_pin_cs = (ra8_port_pin_t)k_ra8_board_pmod2_spi_cs

static

Pmod2 GPIO chip-select pin used by the SD-SPI transport.

Definition at line 84 of file main.c.

Referenced by internal_sd_demo_init_card_or_halt().

◆ s_sd_demo_pin_sck

const ra8_port_pin_t s_sd_demo_pin_sck = (ra8_port_pin_t)k_ra8_board_pmod2_spi_sck

static

Pmod2 SCI0 clock pin used by the SD-SPI transport.

Definition at line 75 of file main.c.

Referenced by internal_sd_demo_init_card_or_halt().

◆ s_tag

const char* const s_tag = "ra8_io_sd_demo"

static

Module log tag.

Definition at line 107 of file main.c.

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SD_DEMO_PUTS

Enumeration Type Documentation

◆ sd_demo_config_t

Function Documentation

◆ internal_sd_demo_init_card_or_halt()

◆ internal_sd_demo_panic_halt()

◆ internal_sd_demo_print()

◆ internal_sd_demo_roundtrip()

◆ internal_sd_demo_setup_or_halt()

◆ main()

Variable Documentation

◆ s_bd

◆ s_be

◆ s_msg_boot

◆ s_msg_card_ok

◆ s_msg_fail

◆ s_msg_init_fail

◆ s_msg_pass

◆ s_params

◆ s_sd_demo_pin_cipo

◆ s_sd_demo_pin_copi

◆ s_sd_demo_pin_cs

◆ s_sd_demo_pin_sck

◆ s_tag