Transparent compress-on-write / decompress-on-read over the VFS (#161). More...

#include <stdint.h>
#include <string.h>
#include "ra8_attributes.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_log.h"
#include "ra8_port_constants.h"
#include "ra8_port_utils.h"
#include "ra8_sci.h"
#include "ra8_time.h"
#include "ra8_vfs_compress.h"

Include dependency graph for main.c:

Enumerations
enum	demo_const_t : uint32_t { k_demo_uart_chan = 8U , k_demo_uart_baud = 115200U , k_demo_disk_blocks = 512U , k_demo_payload = 4096U , k_demo_blob_cap = 8192U , k_demo_pin_shift = 8U , k_demo_seed_mul = 31U , k_demo_pattern_mod = 7U }
	Console + volume + payload knobs (no magic numbers). More...

Functions
static void	internal_demo_print (const char *msg)
	Print a NUL-terminated string on the demo's UART stream.
static void	internal_demo_setup_or_halt (void)
	Bring up CGC + SysTick + the SCI8 console; halt forever on any failure.
static ra8_err_t	internal_demo_mount (ra8_io_blockdev_t bd, ra8_fs_backend_t be, const char *name)
	Format + mount a fresh FAT12 volume and register it in the VFS.
static ra8_err_t	internal_demo_roundtrip (const char prefix, uint32_t out_blob_len)
	Run the transparent compressed round-trip on one mounted volume.
static ra8_err_t	internal_demo_run (uint32_t *out_blob_len)
	Bind both backends and run the transparent round-trip on each.
void	main (void)
	Firmware entry point.

Variables
static const ra8_port_pin_t	s_demo_txd
	SCI8 console TXD = PD02.
static const ra8_port_pin_t	s_demo_rxd
	SCI8 console RXD = PD03.
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 (in SRAM .bss) for the "ram" mount.
static ra8_io_blockdev_t	s_bd_ram
	RAM block-device handle + its backend state.
static ra8_io_blockdev_ram_state_t	s_bstate_ram
static ra8_io_blockdev_t	s_bd_dr
	SDRAM block-device handle + its (reused RAM-backend) state.
static ra8_io_blockdev_ram_state_t	s_bstate_dr
static ra8_fs_backend_t	s_be_ram
	ra8_fs backends bridged onto each block device.
static ra8_fs_backend_t	s_be_dr
static ra8_io_stream_t	s_uart
	UART output stream + its sink state.
static ra8_io_stream_uart_state_t	s_ust
static uint8_t	s_payload [(size_t) k_demo_payload]
	Original payload, compressed-blob staging, and the inflated copy.
static uint8_t	s_blob [(size_t) k_demo_blob_cap]
static uint8_t	s_restored [(size_t) k_demo_payload]
static uint8_t	s_scratch [(size_t) k_ra8_compress_scratch_bytes]
	Compressor scratch (one miniz tdefl_compressor) in SRAM.
static const char *const	s_tag = "compress_demo"
	Module log tag.

Detailed Description

Transparent compress-on-write / decompress-on-read over the VFS (#161).

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

Demonstrates that DEFLATE compression is a TRANSPARENT property of the fabric: the app hands a plain payload to ra8_vfs_compress_write and reads it back with ra8_vfs_compress_read – it NEVER touches the codec (ra8_compress / ra8_decompress) or ra8_fs_write_file directly. The bytes on the backing store are the compressed blob; the API hides the codec.

Because the compression seam sits ABOVE the VFS, it composes over WHATEVER backend is mounted. To prove that, this demo mounts TWO backends and runs the SAME compressed round-trip through the fabric on each:

A RAM block device over an in-SRAM buffer, registered as "ram".
The external 64 MiB SDRAM as a volatile ramdisk, registered as "dr". The only per-backend difference is the block-device bind line and the VFS prefix – the write/read/verify code is identical and backend-agnostic.

For each backend the demo: a. Formats + mounts a FAT12 volume and registers it in the VFS. b. ra8_vfs_compress_write – compresses + stores STORY.RBK. c. ra8_vfs_compress_read – reads + inflates the blob. d. memcmp against the original payload.

This mirrors the firmware's real .rabook RBKC compress-on-write path. The ra8_emulator captures the SCI8 console, so the PASS line is observable headlessly: a successful run ends with compress_demo: ram+dr 4096 -> N bytes -> 4096 round-trip 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 + payload knobs (no magic numbers).

Enumerator
k_demo_uart_chan	SCI8 J-Link OB console.
k_demo_uart_baud	Console baud.
k_demo_disk_blocks	256 KiB per volume (FAT12).
k_demo_payload	Source bytes (compressible).
k_demo_blob_cap	Compressed-blob staging capacity.
k_demo_pin_shift	Port byte position in ra8_port_pin_t.
k_demo_seed_mul	Test-pattern multiplier.
k_demo_pattern_mod	Small alphabet -> highly compressible.

Definition at line 56 of file main.c.

Function Documentation

◆ internal_demo_mount()

ra8_err_t internal_demo_mount	(	ra8_io_blockdev_t *	bd,
		ra8_fs_backend_t *	be,
		const char *	name )

static

Format + mount a fresh FAT12 volume and register it in the VFS.

Bridges an already-bound block device to ra8_fs, formats a FAT12 volume, mounts it, and registers the mount under name in the VFS. The block device and backend storage are caller-owned.

Parameters

[in]	bd	Bound block device (RAM or SDRAM).
[out]	be	Caller-owned ra8_fs backend to populate.
[in]	name	VFS mount name (e.g. "ram" or "dr").

Returns: ra8_err_t Error code.

Return values

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

Precondition: bd was bound by a block-device init call.; be and name out-live the registration.

Postcondition: On success "<name>:/..." paths resolve to the new volume.; On any non-ok return no volume is registered under name.

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

Since: 0.1.0

Definition at line 190 of file main.c.

References 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_io_blockdev_as_fs_backend(), ra8_io_vfs_mount(), RA8_RETURN_ON_ERROR, s_tag, and ra8_fs_format_opts_t::type.

Referenced by internal_demo_run(), and internal_demo_run().

◆ internal_demo_print()

void internal_demo_print ( const char * msg )

static

Print a NUL-terminated string on the demo's UART stream.

Thin wrapper over ra8_io_stream_puts bound to s_uart so call sites do not repeat the sink handle.

Parameters

[in] msg NUL-terminated ASCII string (CR/LF supplied by the caller).

Returns: None.

Precondition: s_uart was initialised by ra8_io_stream_uart_init.; msg is non-NULL and NUL-terminated.

Postcondition: The bytes of msg are queued on the UART stream.; No other state changes.

Note: Blocking polled TX; not interrupt-safe.

Since: 0.1.0

Definition at line 119 of file main.c.

References RA8_INTERNAL, ra8_io_stream_puts(), and s_uart.

◆ internal_demo_roundtrip()

ra8_err_t internal_demo_roundtrip	(	const char *	prefix,
		uint32_t *	out_blob_len )

static

Run the transparent compressed round-trip on one mounted volume.

Calls ONLY the fabric's transparent compression API: it writes the shared payload to "<prefix>STORY.RBK" with ra8_vfs_compress_write (compress-on-write), reads it back with ra8_vfs_compress_read (decompress-on-read), and byte-compares against the original. The codec is never invoked directly. This body is backend-agnostic: the only thing that varies between volumes is prefix.

Parameters

[in]	prefix	VFS path prefix incl. the trailing slash ("ram:/").
[out]	out_blob_len	Compressed blob length stored on success.

Returns: ra8_err_t Error code.

Return values

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

Precondition: The volume named by prefix is mounted in the VFS.; s_payload holds the deterministic source pattern.

Postcondition: On success "<prefix>STORY.RBK" holds the compressed blob.; 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 235 of file main.c.

References k_demo_blob_cap, k_demo_payload, k_ra8_compress_scratch_bytes, k_ra8_err_checksum_mismatch, k_ra8_err_invalid_size, k_ra8_io_vfs_name_max, k_ra8_ok, memcmp(), memcpy(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, RA8_RETURN_ON_ERROR, ra8_vfs_compress_read(), ra8_vfs_compress_write(), s_blob, s_payload, s_restored, s_scratch, s_tag, and strnlen().

◆ internal_demo_run()

ra8_err_t internal_demo_run ( uint32_t * out_blob_len )

static

Bind both backends and run the transparent round-trip on each.

Builds the deterministic compressible payload once, then for each backend (RAM then SDRAM) binds the block device, mounts a FAT12 volume in the VFS, and runs internal_demo_roundtrip through the fabric. The per-backend difference is exactly the bind line plus the VFS prefix.

Parameters

[out] out_blob_len Compressed blob length from the RAM round-trip.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Both backends round-tripped intact.
k_ra8_err_null_ptr	`out_blob_len` was NULL.
(other)	The first failing backend's failing-step code.

Precondition: internal_demo_setup_or_halt has run (clocks + console up).; The SDRAM pins/clocks allow ra8_io_blockdev_sdram_init to succeed.

Postcondition: On success both ram:/STORY.RBK and dr:/STORY.RBK hold the blob.; 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 303 of file main.c.

References internal_demo_mount(), internal_demo_roundtrip(), k_demo_disk_blocks, k_demo_pattern_mod, k_demo_payload, k_demo_seed_mul, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_INTERNAL, ra8_io_blockdev_ram_init(), ra8_io_blockdev_sdram_init(), RA8_RETURN_ON_ERROR, s_bd_dr, s_bd_ram, s_be_dr, s_be_ram, s_bstate_dr, s_bstate_ram, s_disk, s_payload, and s_tag.

Referenced by main().

◆ internal_demo_setup_or_halt()

void internal_demo_setup_or_halt ( void )

static

Bring up CGC + SysTick + the SCI8 console; halt forever on any failure.

Initialises clocks, reads CPU/PCLKA rates, starts the millisecond time base, routes the SCI8 console pins, and opens the SCI8 UART. Any failure spins forever so a debugger can inspect the halt.

Returns: None.

Precondition: SystemInit configured VTOR / FPU / priority grouping.; Runs single-threaded during early boot.

Postcondition: On success SCI8 is open at k_demo_uart_baud and the time base runs.; On any failure the function never returns (infinite halt loop).