ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
ra8_io_roundtrip.c File Reference

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

#include "ra8_io_roundtrip.h"
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
Include dependency graph for ra8_io_roundtrip.c:

Go to the source code of this file.

Enumerations

enum  ra8_io_roundtrip_const_t : uint32_t {
  k_ra8_io_roundtrip_max_payload = 512U ,
  k_ra8_io_roundtrip_seed_mul = 7U ,
  k_ra8_io_roundtrip_seed_add = 1U ,
  k_ra8_io_roundtrip_note_base = 65U ,
  k_ra8_io_roundtrip_note_mod = 26U
}
 Fixed sizing + payload-pattern knobs (no magic numbers). More...

Functions

static void internal_ra8_io_roundtrip_fill_linear (uint32_t len)
 Fill s_payload with a deterministic linear byte pattern.
static void internal_ra8_io_roundtrip_fill_alpha (uint32_t len)
 Fill s_payload with a deterministic rolling-alphabet pattern.
static ra8_err_t internal_ra8_io_roundtrip_read_verify (const char *path, uint32_t len, const char *tag)
 Read a VFS file back into s_readback and compare against s_payload.
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.

Variables

static uint8_t s_payload [k_ra8_io_roundtrip_max_payload]
 Shared payload + read-back scratch (no heap; NASA Rule 3).
static uint8_t s_readback [k_ra8_io_roundtrip_max_payload]

Detailed Description

Shared ra8_io VFS round-trip implementation for the FAT demos (#155).

Implements ra8_io_roundtrip_mount, ra8_io_roundtrip_root_file, and ra8_io_roundtrip_subdir_file – the backend-agnostic core that the RAM, SDRAM, OSPI/xSPI NOR, and SD-over-SPI demos all share. The block device is bound by the caller (its ra8_io_blockdev_*_init already ran); everything above the block-device seam is identical, so it lives here once. The helpers are silent: each demo's main.c owns its PASS banner so the existing ra8_emulator smoke expectations stay byte-identical.

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

Definition in file ra8_io_roundtrip.c.

Enumeration Type Documentation

◆ ra8_io_roundtrip_const_t

enum ra8_io_roundtrip_const_t : uint32_t

Fixed sizing + payload-pattern knobs (no magic numbers).

The scratch buffers are sized to the largest payload any demo round-trips (the SD demo's 512-byte sector); a payload longer than this is rejected at runtime. The pattern constants make the written bytes deterministic so the read-back compare is a strong end-to-end check of the whole stack.

Invariant
k_ra8_io_roundtrip_max_payload >= every demo's payload length.
Enumerator
k_ra8_io_roundtrip_max_payload 

Largest payload (SD sector).

k_ra8_io_roundtrip_seed_mul 

Root payload pattern multiplier.

k_ra8_io_roundtrip_seed_add 

Root payload pattern additive bias.

k_ra8_io_roundtrip_note_base 

Subdir note alphabet base ('A').

k_ra8_io_roundtrip_note_mod 

Subdir note alphabet size.

Definition at line 37 of file ra8_io_roundtrip.c.

Function Documentation

◆ internal_ra8_io_roundtrip_fill_alpha()

void internal_ra8_io_roundtrip_fill_alpha ( uint32_t len)
static

Fill s_payload with a deterministic rolling-alphabet pattern.

Writes byte[i] = 'A' + (i % 26) over the first len bytes of the shared payload buffer – the same note pattern the original per-demo subdir round-trips used, kept distinct from the linear root pattern so a swapped buffer would be caught.

Parameters
[in]lenNumber of bytes to fill (must be <= the buffer capacity).
Returns
None.
Precondition
len is at most k_ra8_io_roundtrip_max_payload.
s_payload is file-scope storage (always allocated).
Postcondition
The first len bytes of s_payload hold the alphabet pattern.
No other state is modified.
Note
Not thread-safe; mutates the shared payload buffer.
Since
0.1.0

Definition at line 97 of file ra8_io_roundtrip.c.

References k_ra8_io_roundtrip_note_base, k_ra8_io_roundtrip_note_mod, RA8_INTERNAL, and s_payload.

Referenced by ra8_io_roundtrip_subdir_file().

◆ internal_ra8_io_roundtrip_fill_linear()

void internal_ra8_io_roundtrip_fill_linear ( uint32_t len)
static

Fill s_payload with a deterministic linear byte pattern.

Writes byte[i] = i * mul + add over the first len bytes of the shared payload buffer, giving a reproducible content whose read-back compare validates the whole fabric path. The pattern is the same one the original per-demo main.c files used for their root payloads.

Parameters
[in]lenNumber of bytes to fill (must be <= the buffer capacity).
Returns
None.
Precondition
len is at most k_ra8_io_roundtrip_max_payload.
s_payload is file-scope storage (always allocated).
Postcondition
The first len bytes of s_payload hold the reproducible pattern.
No other state is modified.
Note
Not thread-safe; mutates the shared payload buffer.
Since
0.1.0

Definition at line 69 of file ra8_io_roundtrip.c.

References k_ra8_io_roundtrip_seed_add, k_ra8_io_roundtrip_seed_mul, RA8_INTERNAL, and s_payload.

Referenced by ra8_io_roundtrip_root_file().

◆ internal_ra8_io_roundtrip_read_verify()

ra8_err_t internal_ra8_io_roundtrip_read_verify ( const char * path,
uint32_t len,
const char * tag )
static

Read a VFS file back into s_readback and compare against s_payload.

Opens path for reading through the VFS, reads up to len bytes into the shared read-back buffer, closes the handle on every path, then verifies both the returned length and every byte match the payload most recently written by a fill helper.

Parameters
[in]pathFull <prefix>:/... VFS path to read.
[in]lenExpected byte count (the payload length just written).
[in]tagra8_log tag for the open/read step diagnostics.
Returns
ra8_err_t Error code.
Return values
k_ra8_okLength and content both matched.
k_ra8_err_invalid_sizeThe returned length differed from len.
k_ra8_err_checksum_mismatchThe byte content differed.
(other)The first failing VFS / ra8_fs step's code.
Precondition
path and tag are non-NULL.
len is at most k_ra8_io_roundtrip_max_payload.
Postcondition
s_readback holds the bytes read from path.
No file handle is left open on any return path.
Note
Not thread-safe; mutates the shared read-back buffer.
Since
0.1.0

Definition at line 132 of file ra8_io_roundtrip.c.

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

Referenced by ra8_io_roundtrip_root_file(), and ra8_io_roundtrip_subdir_file().

◆ 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]bdBound block device (its ra8_io_blockdev_*_init already ran).
[in]pPer-demo parameters (prefix, FAT type, label, log tag).
[out]beCaller-owned backend storage populated by the bridge; it out-lives the mount (the VFS keeps pointers into it).
[out]out_mountReceives the mount handle on success, nullptr on error.
Returns
ra8_err_t Error code.
Return values
k_ra8_okThe volume is formatted, mounted, and registered.
k_ra8_err_null_ptrbd, 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 152 of file ra8_io_roundtrip.c.

References ra8_io_roundtrip_params_t::fat_type, 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]mntThe mount handle returned by ra8_io_roundtrip_mount.
[in]pPer-demo parameters (root file name, path, payload length).
Returns
ra8_err_t Error code.
Return values
k_ra8_okThe payload round-tripped intact.
k_ra8_err_null_ptrmnt or p was NULL.
k_ra8_err_invalid_sizeThe read-back length differed.
k_ra8_err_checksum_mismatchThe 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 175 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_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]pPer-demo parameters (subdir path, nested file path, length).
Returns
ra8_err_t Error code.
Return values
k_ra8_okThe note round-tripped intact.
k_ra8_err_null_ptrp was NULL.
k_ra8_err_invalid_sizeThe read-back length differed.
k_ra8_err_checksum_mismatchThe 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 190 of file ra8_io_roundtrip.c.

References internal_ra8_io_roundtrip_fill_alpha(), internal_ra8_io_roundtrip_read_verify(), 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_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.

Variable Documentation

◆ s_payload

uint8_t s_payload[k_ra8_io_roundtrip_max_payload]
static

Shared payload + read-back scratch (no heap; NASA Rule 3).

Definition at line 46 of file ra8_io_roundtrip.c.

◆ s_readback

uint8_t s_readback[k_ra8_io_roundtrip_max_payload]
static

Definition at line 47 of file ra8_io_roundtrip.c.