ra8_io caching block device demo (Phase 5, #160). More...

#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_board_ek_ra8d2_console_stream.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_io_blockdev_cache.h"
#include "ra8_log.h"
#include "ra8_time.h"

Include dependency graph for main.c:

Enumerations
enum	demo_const_t : uint32_t { k_demo_uart_baud = 115200U , k_demo_disk_blocks = 512U , k_demo_cache_slots = 32U , k_demo_payload = 128U , k_demo_reads = 8U , k_demo_seed_mul = 7U }
	Console + volume + cache knobs (no magic numbers). More...

Functions
static void	internal_demo_print (const char *msg)
	Print a NUL-terminated string on the UART stream.
static void	internal_demo_setup_or_halt (void)
	Bring up CGC, SysTick, and the board console; halt on failure.
static ra8_err_t	internal_demo_mount (ra8_fs_mount_t **out_mnt)
	Bridge the cached device to ra8_fs, format FAT12, and register the VFS.
static ra8_err_t	internal_demo_read_once (const uint8_t *expect)
	Read ram:/HELLO.TXT once and compare it against `expect`.
static ra8_err_t	internal_demo_run (uint32_t out_hits, uint32_t out_misses)
	Write the file once and re-read it repeatedly through the cache.
void	main (void)
	Firmware entry point.

Variables
static uint8_t	s_disk [(size_t) k_demo_disk_blocks *(size_t) k_ra8_io_block_size_bytes]
	256 KiB RAM-disk backing buffer for the slow backend (in SRAM .bss).
static ra8_io_blockdev_t	s_under
	Slow backend block-device handle + its RAM backend state.
static ra8_io_blockdev_ram_state_t	s_ustate
static ra8_io_blockdev_t	s_cached
	Caching decorator over the backend + its caller-owned cache storage.
static ra8_io_blockdev_cache_state_t	s_cstate
static uint8_t	s_cache_data [(size_t) k_demo_cache_slots *(size_t) k_ra8_io_block_size_bytes]
static ra8_io_blockdev_cache_slot_t	s_cache_slots [(size_t) k_demo_cache_slots]
static ra8_fs_backend_t	s_be
	ra8_fs backend bridged onto the cached block device.
static ra8_io_stream_t	s_uart
	Console output stream; the board owns the sink behind it.
static const char *const	s_tag = "ra8_io_cache_demo"
	Module log tag.

Detailed Description

ra8_io caching block device demo (Phase 5, #160).

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

Exercises the caching block device – an LRU sector cache decorator that wraps any backend so repeated reads of the same blocks (filesystem metadata, a re-read page) skip the slow medium. The cache sits between the filesystem/VFS and the media:

Build a RAM block device as the slow backend (Phase 1, #156).
Wrap it with ra8_io_blockdev_cache_init over a fixed set of cached sectors (Phase 5, #160).
Bridge the cached device to ra8_fs, format/mount a FAT12 volume, and register it in the VFS as "ram" (Phase 3, #158) – so every FAT access now flows through the cache.
Write a file, then read it back repeatedly through "ram:/HELLO.TXT". The first pass fills the cache; the re-reads touch the same metadata and data sectors and are served as cache hits.
Read the hit/miss counters with ra8_io_blockdev_cache_stats and require a non-zero hit count, proving the cache served repeated reads.
Report progress on the SCI8 console through a ra8_io UART stream sink.

The ra8_emulator captures the SCI8 console, so the PASS line and the hit/miss counts are observable headlessly: a successful run prints ra8_io_cache_demo: re-read x8 hits=H misses=M ram:/HELLO.TXT PASS.

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

Definition in file main.c.

Enumeration Type Documentation

◆ demo_const_t

enum demo_const_t : uint32_t

Console + volume + cache knobs (no magic numbers).

Enumerator
k_demo_uart_baud	Console baud.
k_demo_disk_blocks	256 KiB RAM-disk (FAT12).
k_demo_cache_slots	Cached 512-byte sectors (16 KiB).
k_demo_payload	Bytes written + read back.
k_demo_reads	Re-read passes over the same file.
k_demo_seed_mul	Test-pattern multiplier.

Definition at line 51 of file main.c.

Function Documentation

◆ internal_demo_mount()

ra8_err_t internal_demo_mount ( ra8_fs_mount_t ** out_mnt )

static

Bridge the cached device to ra8_fs, format FAT12, and register the VFS.

Constructs the RAM backend and cache decorator in caller-owned storage, formats a FAT12 volume, mounts it, and registers the ram prefix.

Parameters

[out] out_mnt Receives the mounted FAT filesystem on success.

Returns: Error from the first block-device, format, mount, or VFS operation.

Return values

k_ra8_ok The cached FAT12 volume was mounted and registered.

Precondition: out_mnt addresses writable pointer storage.; The static RAM disk and cache buffers retain their full declared capacity.

Postcondition: On success, out_mnt identifies the VFS-registered mount.; On failure, later construction stages are not attempted.

Note: The backing storage and cache lifetime equal the firmware lifetime.

Since: 0.1.0

Definition at line 142 of file main.c.

References k_demo_cache_slots, k_demo_disk_blocks, k_ra8_fs_type_fat12, k_ra8_ok, ra8_fs_format_opts_t::label, RA8_CHECK_NULL_PTR, ra8_fs_format(), ra8_fs_mount(), RA8_INTERNAL, ra8_io_blockdev_as_fs_backend(), ra8_io_blockdev_cache_init(), ra8_io_blockdev_ram_init(), ra8_io_vfs_mount(), RA8_RETURN_ON_ERROR, s_be, s_cache_data, s_cache_slots, s_cached, s_cstate, s_disk, s_tag, s_under, s_ustate, and ra8_fs_format_opts_t::type.

◆ internal_demo_print()

void internal_demo_print ( const char * msg )

static

Print a NUL-terminated string on the UART stream.

Delegates bounded string emission to the initialized stream and intentionally ignores diagnostic-output errors in this terminal demo.

Parameters

[in] msg NUL-terminated message to emit.

Precondition: msg is non-NULL and readable through its terminator.; s_uart has been initialized with its caller-owned UART state.

Postcondition: The stream has accepted the message or reported an ignored sink error.; Cache, filesystem, and block-device state remain unchanged.

Note: This single-threaded diagnostic helper performs no retry.

Since: 0.1.0

Definition at line 92 of file main.c.

References RA8_INTERNAL, ra8_io_stream_puts(), and s_uart.

◆ internal_demo_read_once()

ra8_err_t internal_demo_read_once ( const uint8_t * expect )

static

Read ram:/HELLO.TXT once and compare it against expect.

Opens the file through VFS, reads exactly the configured payload, closes the handle, then validates both length and contents.

Parameters

[in] expect Expected payload bytes for the comparison.

Returns: Filesystem error or the explicit length/content verdict.

Return values

k_ra8_ok	The complete payload matched `expect`.
k_ra8_err_invalid_size	The file length differed from the payload size.
k_ra8_err_checksum_mismatch	At least one byte differed.

Precondition: expect addresses at least k_demo_payload readable bytes.; The ram VFS mount and HELLO.TXT file already exist.

Postcondition: The read handle is closed after a successful read operation.; Cache statistics reflect the block accesses performed by this read.

Note: The comparison buffer is bounded on the stack by the payload constant.

Since: 0.1.0

Definition at line 185 of file main.c.

References k_demo_payload, k_ra8_err_checksum_mismatch, k_ra8_err_invalid_size, k_ra8_fs_mode_read, k_ra8_ok, memcmp(), RA8_CHECK_NULL_PTR, ra8_fs_close(), ra8_fs_read(), RA8_INTERNAL, ra8_io_vfs_open(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_demo_run().

◆ internal_demo_run()

ra8_err_t internal_demo_run	(	uint32_t *	out_hits,
		uint32_t *	out_misses )

static

Write the file once and re-read it repeatedly through the cache.

Mounts the cached volume, creates a deterministic payload, writes it, verifies every configured read pass, and returns cache hit/miss counters.

Parameters

[out]	out_hits	Receives the cache-hit count.
[out]	out_misses	Receives the cache-miss count.

Returns: Error from the first mount, write, read, or stats operation.

Return values

k_ra8_ok	Every read matched and at least one cache hit was observed.
k_ra8_err_checksum_mismatch	Data differed or no hit was recorded.

Precondition: Both output pointers address writable 32-bit storage.; The VFS mount table has room for the ram prefix.

Postcondition: On success, both output counters contain the final cache statistics.; The verified file remains present on the mounted FAT12 volume.

Note: The deterministic payload makes repeated cache reads byte-comparable.

Since: 0.1.0

Definition at line 221 of file main.c.

References internal_demo_mount(), internal_demo_read_once(), k_demo_payload, k_demo_reads, k_demo_seed_mul, k_ra8_err_checksum_mismatch, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_fs_write_file(), RA8_INTERNAL, ra8_io_blockdev_cache_stats(), RA8_RETURN_ON_ERROR, s_cstate, and s_tag.

◆ internal_demo_setup_or_halt()

void internal_demo_setup_or_halt ( void )

static

Bring up CGC, SysTick, and the board console; halt on failure.

Resolves CPUCLK0, initializes the time base, then hands the console over to the BSP – which owns the channel, the PD02 / PD03 routing and the live-PCLKA bit-rate solve – and binds it as an ra8_io stream.

Precondition: Reset startup has initialized data and BSS storage.; Peripheral register mappings for clocks, pins, and the console are accessible.

Postcondition: On return, the board console is configured for the requested diagnostic baud and bound into s_uart.; Any required setup failure parks the application before returning.