Prove the ra8_io fabric's swappable backend (#155/#156) over native SDHI. 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_fs.h"
#include "ra8_io.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_DEMO_PUTS(lit)
	Emit a NUL-terminated literal (length via sizeof at the call site).

Enumerations
enum	sdhi_demo_config_t : uint32_t { k_sdhi_demo_uart_baud = 115200U , k_sdhi_demo_instance = 0U , k_sdhi_demo_payload_bytes = 512U , k_sdhi_demo_prng_seed = 0xA5F00DadUL , k_sdhi_demo_prng_mul = 1664525UL , k_sdhi_demo_prng_add = 1013904223UL , k_sdhi_demo_prng_byte_shift = 16U , k_sdhi_demo_byte_mask = 0xFFU }
	Compile-time settings for the ra8_io native-SDHI backend demo. More...

Functions
static void	sdhi_demo_print (const uint8_t *msg, uint32_t len)
	Write a byte run on the J-Link OB VCOM console.
static void	sdhi_demo_panic_halt (void)
	Halt forever in WFI – panic stop on irrecoverable failure.
static void	sdhi_demo_setup_or_halt (void)
	Bring up CGC + SysTick + the board console + SDHI bus pins; panic on fail.
static void	sdhi_demo_init_card_or_halt (void)
	Init the SD card over native SDHI, panic-halt on failure.
static void	sdhi_demo_fill_payload (void)
	Fill the payload buffer with a deterministic LCG byte sequence.
static ra8_err_t	sdhi_demo_mount_via_io (void)
	Bind the native-SDHI block device, bridge it to ra8_fs, format + mount FAT16, and register it in the VFS under "sd".
static ra8_err_t	sdhi_demo_write_payload (const char *path)
	Write s_payload to the VFS path through ra8_io_vfs_open + ra8_fs_write.
static ra8_err_t	sdhi_demo_read_and_verify (const char *path)
	Read the VFS file back and byte-compare against s_payload.
static ra8_err_t	sdhi_demo_roundtrip (void)
	Run the full ra8_io round-trip: mount, mkdir, write, read-back, verify.
void	main (void)
	App entry: bring up the bus + card, run the ra8_io round-trip, print PASS.

Variables
static const uint8_t	k_msg_boot [] = "ra8_io_sdhi_demo: boot\r\n"
static const uint8_t	k_msg_card_ok [] = "ra8_io_sdhi_demo: card ready\r\n"
static const uint8_t	k_msg_init_fail [] = "ra8_io_sdhi_demo: FAIL init\r\n"
static const uint8_t	k_msg_pass [] = "ra8_io_sdhi_demo: sd:/LOGS/A.TXT 512 bytes PASS\r\n"
static const uint8_t	k_msg_fail [] = "ra8_io_sdhi_demo: FAIL\r\n"
static const char	k_mount_name [] = "sd"
	VFS mount name and target path for the round-trip file.
static const char	k_dir_path [] = "sd:/LOGS"
static const char	k_file_path [] = "sd:/LOGS/A.TXT"
static const char *const	s_tag = "ra8_io_sdhi_demo"
	Module log tag.
static uint8_t	s_payload [k_sdhi_demo_payload_bytes]
	Static payload + read-back buffers (no heap; NASA Rule 3).
static uint8_t	s_readback [k_sdhi_demo_payload_bytes]
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

Detailed Description

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

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

The native-SDHI sibling of ra8_io_sd_demo. That app runs the ra8_io VFS over a micro-SD card clocked byte-by-byte through an SCI Simple-SPI bus; this app runs the IDENTICAL ra8_io VFS API over the SAME card but reached through the dedicated 4-bit SDHI controller. Only the block-device backend changes: instead of ra8_io_blockdev_sdspi_init it binds the native-SDHI block device (ra8_io_blockdev_sdhi_init) on top of the ra8_sdcard + ra8_sdhi HAL drivers. The data path above the block device is pure ra8_io:

Route the eight SDHI pins (port 4, pins 0..7) via ra8_board_sdhi_pins_init.
ra8_sdcard_init({.instance = 0}) – full SD identification + clock step-up.
ra8_io_blockdev_sdhi_init – native-SDHI block-device vtable over the card.
ra8_io_blockdev_as_fs_backend – bridge the block device to ra8_fs.
ra8_fs_format (FAT16) + ra8_fs_mount, then ra8_io_vfs_mount("sd", ...).
ra8_io_vfs_mkdir("sd:/LOGS") – exercises the VFS mkdir path.
ra8_io_vfs_open("sd:/LOGS/A.TXT", write) + ra8_fs_write – write payload.
ra8_io_vfs_open("sd:/LOGS/A.TXT", read) + ra8_fs_read – read it back.
byte-compare the read-back against the deterministic payload.

On a clean round-trip it prints exactly ra8_io_sdhi_demo: sd:/LOGS/A.TXT 512 bytes PASS; any failed step prints ra8_io_sdhi_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): a microSD card in the on-board SDHI slot. THIS APP ERASES THE CARD. Under ra8_emulator attach a blank card with --sd-new 64:fat16; the native-SDHI host-controller model serves it.

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

Since: 0.1.0

Definition in file main.c.

Macro Definition Documentation

◆ SDHI_DEMO_PUTS

#define SDHI_DEMO_PUTS ( lit )

Value:

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

sdhi_demo_print

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

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

Definition main.c:121

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

Definition at line 127 of file main.c.

Referenced by main(), and sdhi_demo_init_card_or_halt().

Enumeration Type Documentation

◆ sdhi_demo_config_t

enum sdhi_demo_config_t : uint32_t

Compile-time settings for the ra8_io native-SDHI backend demo.

Enumerator
k_sdhi_demo_uart_baud	J-Link OB CDC console baud.
k_sdhi_demo_instance	SDHI0 drives the micro-SD bus.
k_sdhi_demo_payload_bytes	One-sector deterministic test payload.
k_sdhi_demo_prng_seed	Deterministic payload seed.
k_sdhi_demo_prng_mul	Numerical Recipes LCG multiplier.
k_sdhi_demo_prng_add	Numerical Recipes LCG increment.
k_sdhi_demo_prng_byte_shift	Bit shift selecting the PRNG byte.
k_sdhi_demo_byte_mask	Low-byte mask.

Definition at line 66 of file main.c.

Function Documentation

◆ 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, and SDHI bus pins, runs the native SD card identification, fills the payload, then runs the full ra8_io VFS round-trip over the native-SDHI 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 427 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_demo_fill_payload(), sdhi_demo_init_card_or_halt(), sdhi_demo_panic_halt(), SDHI_DEMO_PUTS, sdhi_demo_roundtrip(), and sdhi_demo_setup_or_halt().

◆ sdhi_demo_fill_payload()

void sdhi_demo_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 whole stack.

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 254 of file main.c.

References k_sdhi_demo_byte_mask, k_sdhi_demo_payload_bytes, k_sdhi_demo_prng_add, k_sdhi_demo_prng_byte_shift, k_sdhi_demo_prng_mul, k_sdhi_demo_prng_seed, and s_payload.

Referenced by main().

◆ sdhi_demo_init_card_or_halt()

void sdhi_demo_init_card_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 214 of file main.c.

References k_msg_card_ok, k_msg_init_fail, k_ra8_ok, k_sdhi_demo_instance, ra8_sdcard_init(), sdhi_demo_panic_halt(), and SDHI_DEMO_PUTS.

Referenced by main().

◆ sdhi_demo_mount_via_io()

ra8_err_t sdhi_demo_mount_via_io ( void )

staticnodiscard

Bind the native-SDHI block device, bridge it to ra8_fs, format + mount FAT16, and register it in the VFS under "sd".

This is the "swappable backend" core: the only difference from ra8_io_sd_demo is that the block device here is the native-SDHI backend rather than the SD-over-SPI backend. Everything above (ra8_fs + VFS) is the identical API. The mount produced by ra8_fs_mount is handed to the VFS, which keeps the pointer, so the local is intentionally not returned.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Backend bound, FAT16 formatted + mounted + VFS-registered.
k_ra8_err_*	The first failing fabric step's code.

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

Postcondition: On success "sd:/..." paths resolve to the SD volume.; On any non-ok return the partial state is abandoned (caller halts).

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

Since: 0.1.0

Definition at line 286 of file main.c.

References k_mount_name, k_ra8_fs_type_fat16, k_ra8_ok, ra8_fs_format_opts_t::label, ra8_fs_format(), ra8_fs_mount(), ra8_io_blockdev_as_fs_backend(), ra8_io_blockdev_sdhi_init(), ra8_io_vfs_init(), ra8_io_vfs_mount(), RA8_RETURN_ON_ERROR, s_bd, s_be, s_tag, and ra8_fs_format_opts_t::type.

Referenced by sdhi_demo_roundtrip().

◆ sdhi_demo_panic_halt()

void sdhi_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 146 of file main.c.

Referenced by main(), sdhi_demo_init_card_or_halt(), and sdhi_demo_setup_or_halt().

◆ sdhi_demo_print()

void sdhi_demo_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 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: 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 121 of file main.c.

References ra8_board_uart_console_write().

◆ sdhi_demo_read_and_verify()

ra8_err_t sdhi_demo_read_and_verify ( const char * path )

staticnodiscard

Read the VFS file back and byte-compare against s_payload.

Opens the file for reading via the named VFS path, reads up to the payload length, closes it, then verifies both the returned length and the full byte content match the written payload.

Parameters

[in] path "sd:/..." VFS file path to read.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Read-back length and content both matched.
k_ra8_err_invalid_size	The returned length differed.
k_ra8_err_checksum_mismatch	The byte content differed.
k_ra8_err_*	ra8_io open / read / close failure.

Precondition: The "sd" volume is mounted and path was written with s_payload.; path is a valid "name:/path" string.

Postcondition: s_readback holds the bytes read from path.; The file handle is released on every path.

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

Since: 0.1.0

Definition at line 357 of file main.c.

References k_ra8_err_checksum_mismatch, k_ra8_err_invalid_size, k_ra8_fs_mode_read, k_ra8_ok, k_sdhi_demo_payload_bytes, memcmp(), memset(), ra8_fs_close(), ra8_fs_read(), ra8_io_vfs_open(), RA8_RETURN_ON_ERROR, s_payload, s_readback, and s_tag.

Referenced by sdhi_demo_roundtrip().

◆ sdhi_demo_roundtrip()

ra8_err_t sdhi_demo_roundtrip ( void )

staticnodiscard

Run the full ra8_io round-trip: mount, mkdir, write, read-back, verify.

Composes the helpers in order so the success path is a single line per step and the first failing step short-circuits with its code. The VFS mkdir exercises the new directory-creation path on the SD volume.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Mount + mkdir + write + read-back + verify all passed.
k_ra8_err_*	The first failing step's code.

Precondition: The SD card is initialised and s_payload is filled.; The VFS mount table is empty or has a free slot.

Postcondition: On success the SD card holds the verified file under sd:/LOGS.; 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 396 of file main.c.

References k_dir_path, k_file_path, k_ra8_ok, ra8_io_vfs_mkdir(), RA8_RETURN_ON_ERROR, s_tag, sdhi_demo_mount_via_io(), sdhi_demo_read_and_verify(), and sdhi_demo_write_payload().

Referenced by main().

◆ sdhi_demo_setup_or_halt()

void sdhi_demo_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 so a misconfigured bus never reaches the SD bring-up.

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 177 of file main.c.

References k_ra8_clock_id_cpuclk0, k_ra8_ok, k_sdhi_demo_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_demo_panic_halt().

Referenced by main().

◆ sdhi_demo_write_payload()

ra8_err_t sdhi_demo_write_payload ( const char * path )

staticnodiscard

Write s_payload to the VFS path through ra8_io_vfs_open + ra8_fs_write.

Opens the file for writing via the named VFS path, streams the full payload, and closes it. The whole-file content is the deterministic LCG pattern, so a later read-back compare validates the path.

Parameters

[in] path "sd:/..." VFS file path to create.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Payload written and the file closed.
k_ra8_err_*	ra8_io open / write / close failure.

Precondition: The "sd" volume is mounted and s_payload is filled.; path is a valid "name:/path" string.

Postcondition: On success path holds s_payload.; The file handle is released on every path.

Note: Not thread-safe; mutates the shared SD volume.

Since: 0.1.0

Definition at line 322 of file main.c.

References k_ra8_fs_mode_write, k_ra8_ok, k_sdhi_demo_payload_bytes, ra8_fs_close(), ra8_fs_write(), ra8_io_vfs_open(), RA8_RETURN_ON_ERROR, s_payload, and s_tag.

Referenced by sdhi_demo_roundtrip().

Variable Documentation

◆ k_dir_path

const char k_dir_path[] = "sd:/LOGS"

static

Definition at line 90 of file main.c.

Referenced by sdhi_demo_roundtrip().

◆ k_file_path

const char k_file_path[] = "sd:/LOGS/A.TXT"

static

Definition at line 91 of file main.c.

Referenced by sdhi_demo_roundtrip().

◆ k_mount_name

const char k_mount_name[] = "sd"

static

VFS mount name and target path for the round-trip file.

Definition at line 89 of file main.c.

Referenced by sdhi_demo_mount_via_io().

◆ k_msg_boot

const uint8_t k_msg_boot[] = "ra8_io_sdhi_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_io_sdhi_demo: card ready\r\n"

static

Definition at line 83 of file main.c.

◆ k_msg_fail

const uint8_t k_msg_fail[] = "ra8_io_sdhi_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_io_sdhi_demo: FAIL init\r\n"

static

Definition at line 84 of file main.c.

Referenced by fs_fmt_init_card_or_halt(), sdhi_card_init_or_halt(), and sdhi_demo_init_card_or_halt().

◆ k_msg_pass

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

static

Definition at line 85 of file main.c.

◆ s_bd

ra8_io_blockdev_t s_bd

static

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

Definition at line 234 of file main.c.

◆ s_be

ra8_fs_backend_t s_be

static

Definition at line 235 of file main.c.

◆ s_payload

uint8_t s_payload[k_sdhi_demo_payload_bytes]

static

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

Definition at line 230 of file main.c.

◆ s_readback

uint8_t s_readback[k_sdhi_demo_payload_bytes]

static

Definition at line 231 of file main.c.

◆ s_tag

const char* const s_tag = "ra8_io_sdhi_demo"

static

Module log tag.

Definition at line 94 of file main.c.

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SDHI_DEMO_PUTS

Enumeration Type Documentation

◆ sdhi_demo_config_t

Function Documentation

◆ main()

◆ sdhi_demo_fill_payload()

◆ sdhi_demo_init_card_or_halt()

◆ sdhi_demo_mount_via_io()

◆ sdhi_demo_panic_halt()

◆ sdhi_demo_print()

◆ sdhi_demo_read_and_verify()

◆ sdhi_demo_roundtrip()

◆ sdhi_demo_setup_or_halt()

◆ sdhi_demo_write_payload()

Variable Documentation

◆ k_dir_path

◆ k_file_path

◆ k_mount_name

◆ k_msg_boot

◆ k_msg_card_ok

◆ k_msg_fail

◆ k_msg_init_fail

◆ k_msg_pass

◆ s_bd

◆ s_be

◆ s_payload

◆ s_readback

◆ s_tag