Shared, backend-agnostic ra8_io VFS round-trip for the FAT demos (#155). More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_io.h"

Include dependency graph for ra8_io_roundtrip.h:

Data Structures
struct	ra8_io_roundtrip_params_t
	Per-demo knobs for the shared ra8_io round-trip. More...

Functions
ra8_err_t	ra8_io_roundtrip_mount (ra8_io_blockdev_t bd, const ra8_io_roundtrip_params_t p, ra8_fs_backend_t be, ra8_fs_mount_t *out_mount)
	Bridge a bound block device to ra8_fs, format + mount FAT, VFS-register.
ra8_err_t	ra8_io_roundtrip_root_file (ra8_fs_mount_t mnt, const ra8_io_roundtrip_params_t p)
	Whole-file write at the volume root, VFS read-back, and byte-compare.
ra8_err_t	ra8_io_roundtrip_subdir_file (const ra8_io_roundtrip_params_t *p)
	mkdir a subdirectory via the VFS, then round-trip a nested file.

Detailed Description

Shared, backend-agnostic ra8_io VFS round-trip for the FAT demos (#155).

The four ra8_io_*_demo apps (RAM, SDRAM, OSPI/xSPI NOR, SD-over-SPI) all run the IDENTICAL fabric round-trip above the block-device seam: bridge the bound block device to ra8_fs, format + mount a FAT volume, register it in the VFS under a short name, then write a file / read it back / byte-compare, and mkdir a subdirectory and round-trip a second file two levels deep. The ONLY thing that differs per demo is the backend bind line (ra8_io_blockdev_*_init) plus the unavoidable peripheral bring-up (OSPI controller, SD-SPI transport).

This module factors that shared round-trip out of the four main.c files so each demo collapses to: boot the console, bind ONE backend, hand the bound ra8_io_blockdev_t to the helpers below, and print its own PASS banner. The helpers never print – the per-demo main.c owns its banner string so the existing ra8_emulator smoke expectations stay byte-identical.

Two phases are exposed so a demo can drive either or both:

ra8_io_roundtrip_mount – bridge + format + mount + VFS register.
ra8_io_roundtrip_root_file – whole-file write at the volume root + VFS read-back + byte-compare.
ra8_io_roundtrip_subdir_file – mkdir + nested open/write/read/compare.

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

Since: 0.1.0

Definition in file ra8_io_roundtrip.h.

Function Documentation

◆ ra8_io_roundtrip_mount()

ra8_err_t ra8_io_roundtrip_mount	(	ra8_io_blockdev_t *	bd,
		const ra8_io_roundtrip_params_t *	p,
		ra8_fs_backend_t *	be,
		ra8_fs_mount_t **	out_mount )

nodiscard

Bridge a bound block device to ra8_fs, format + mount FAT, VFS-register.

The backend-agnostic mount core shared by every FAT demo. The caller has already bound bd with the appropriate ra8_io_blockdev_*_init; this function bridges it to an ra8_fs_backend_t, formats it to p->fat_type with p->volume_label, mounts it, and registers the mount in the VFS under p->vfs_prefix. The first failing step short-circuits with its error code (logged under p->log_tag).

Parameters

[in]	bd	Bound block device (its ra8_io_blockdev_*_init already ran).
[in]	p	Per-demo parameters (prefix, FAT type, label, log tag).
[out]	be	Caller-owned backend storage populated by the bridge; it out-lives the mount (the VFS keeps pointers into it).
[out]	out_mount	Receives the mount handle on success, nullptr on error.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The volume is formatted, mounted, and registered.
k_ra8_err_null_ptr	`bd`, `p`, `be`, or `out_mount` was NULL.
(other)	The first failing fabric step's code.

Precondition: bd, p, be, and out_mount are all non-NULL.; The block device backing bd is initialised and reachable.

Postcondition: On success <prefix>:/... paths resolve to the new FAT volume.; On any non-ok return *out_mount is nullptr.

Note: Not thread-safe; single-threaded init / boot context only.

Since: 0.1.0

Definition at line 150 of file ra8_io_roundtrip.c.

References ra8_io_roundtrip_params_t::fat_type, internal_ra8_io_roundtrip_format_mount(), internal_ra8_io_roundtrip_mount_check(), k_ra8_ok, ra8_fs_format_opts_t::label, ra8_io_roundtrip_params_t::log_tag, RA8_CHECK_NULL_PTR, ra8_fs_format(), ra8_fs_mount(), ra8_io_blockdev_as_fs_backend(), ra8_io_vfs_mount(), RA8_RETURN_ON_ERROR, ra8_fs_format_opts_t::type, ra8_io_roundtrip_params_t::vfs_prefix, and ra8_io_roundtrip_params_t::volume_label.

◆ ra8_io_roundtrip_root_file()

ra8_err_t ra8_io_roundtrip_root_file	(	ra8_fs_mount_t *	mnt,
		const ra8_io_roundtrip_params_t *	p )

nodiscard

Whole-file write at the volume root, VFS read-back, and byte-compare.

Builds a deterministic p->root_bytes payload, writes it to p->root_file with the whole-file ra8_fs_write_file API (supported by every backend), reads it back through the VFS name p->root_path, and compares both the length and every byte.

Parameters

[in]	mnt	The mount handle returned by ra8_io_roundtrip_mount.
[in]	p	Per-demo parameters (root file name, path, payload length).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The payload round-tripped intact.
k_ra8_err_null_ptr	`mnt` or `p` was NULL.
k_ra8_err_invalid_size	The read-back length differed.
k_ra8_err_checksum_mismatch	The read-back bytes differed.
(other)	The first failing fabric step's code.

Precondition: mnt and p are non-NULL and the volume is mounted.; p->root_bytes <= k_ra8_io_roundtrip_max_payload.

Postcondition: On success p->root_file holds the verified payload.; No file handle is left open on any return path.

Note: Not thread-safe; single-caller boot context.

Since: 0.1.0

Definition at line 173 of file ra8_io_roundtrip.c.

References internal_ra8_io_roundtrip_fill_linear(), internal_ra8_io_roundtrip_read_verify(), k_ra8_err_invalid_size, k_ra8_io_roundtrip_max_payload, ra8_io_roundtrip_params_t::log_tag, RA8_CHECK_NULL_PTR, ra8_fs_write_file(), ra8_io_roundtrip_fill_linear(), ra8_io_roundtrip_read_verify(), RA8_RETURN_ON_ERROR, ra8_io_roundtrip_params_t::root_bytes, ra8_io_roundtrip_params_t::root_file, ra8_io_roundtrip_params_t::root_path, and s_payload.

◆ ra8_io_roundtrip_subdir_file()

ra8_err_t ra8_io_roundtrip_subdir_file ( const ra8_io_roundtrip_params_t * p )

nodiscard

mkdir a subdirectory via the VFS, then round-trip a nested file.

Creates p->subdir_path through the VFS, builds a deterministic p->subdir_bytes note, writes it to p->subdir_file via VFS open(write) + ra8_fs_write + close, reads it back via VFS open(read) + ra8_fs_read + close, and byte-compares – exercising mkdir + nested-path resolution over the mounted FAT volume.

Parameters

[in] p Per-demo parameters (subdir path, nested file path, length).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	The note round-tripped intact.
k_ra8_err_null_ptr	`p` was NULL.
k_ra8_err_invalid_size	The read-back length differed.
k_ra8_err_checksum_mismatch	The read-back bytes differed.
(other)	The first failing VFS / ra8_fs step's code.

Precondition: p is non-NULL and its volume is mounted (see ra8_io_roundtrip_mount).; p->subdir_bytes <= k_ra8_io_roundtrip_max_payload.

Postcondition: On success p->subdir_file holds the verified note.; No file handle is left open on any return path.

Note: Not thread-safe; single-caller boot context.

Since: 0.1.0

Definition at line 188 of file ra8_io_roundtrip.c.

References internal_ra8_io_roundtrip_fill_alpha(), internal_ra8_io_roundtrip_read_verify(), internal_ra8_io_roundtrip_write_subdir(), k_ra8_err_invalid_size, k_ra8_fs_mode_write, k_ra8_io_roundtrip_max_payload, ra8_io_roundtrip_params_t::log_tag, RA8_CHECK_NULL_PTR, ra8_fs_close(), ra8_fs_write(), ra8_io_roundtrip_fill_alpha(), ra8_io_roundtrip_read_verify(), ra8_io_vfs_mkdir(), ra8_io_vfs_open(), RA8_RETURN_ON_ERROR, s_payload, ra8_io_roundtrip_params_t::subdir_bytes, ra8_io_roundtrip_params_t::subdir_file, and ra8_io_roundtrip_params_t::subdir_path.

Data Structures

Functions

Detailed Description

Function Documentation

◆ ra8_io_roundtrip_mount()

◆ ra8_io_roundtrip_root_file()

◆ ra8_io_roundtrip_subdir_file()