cache_store_demo.c File Reference

Hardware-free ra8_cache_store on-media cache demo – implementation (#257). More...

#include "cache_store_demo.h"
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_cache_store.h"
#include "ra8_check.h"
#include "ra8_err.h"

Include dependency graph for cache_store_demo.c:

Go to the source code of this file.

Enumerations
enum	demo_key_t : uint32_t {   k_demo_key_cover = 0xC07E5001U ,   k_demo_key_tile_a = 0x11E0A002U ,   k_demo_key_tile_b = 0x11E0B003U ,   k_demo_key_tile_c = 0x11E0C004U ,   k_demo_key_tile_d = 0x11E0D005U }
	Content keys for the demo's cached blobs (source CRC-32 stand-ins). More...
enum	demo_len_t : uint32_t {   k_demo_len_cover = 1400U ,   k_demo_len_tile_a = 300U ,   k_demo_len_tile_b = 900U ,   k_demo_len_tile_c = 1100U ,   k_demo_len_tile_d = 400U }
	Payload lengths (bytes) for the demo blobs; several cross a sector. More...
enum	demo_seed_t : uint8_t {   k_demo_seed_cover = 0x40U ,   k_demo_seed_tile_a = 0x11U ,   k_demo_seed_tile_b = 0x22U ,   k_demo_seed_tile_c = 0x33U ,   k_demo_seed_tile_d = 0x55U }
	Per-blob deterministic fill seeds (a distinct byte ramp per key). More...
enum	demo_count_t : uint32_t { k_demo_survivors = 4U }
	Expected live-entry count after the remount. More...

Functions
static void	internal_demo_fill (uint8_t *buf, uint32_t len, uint8_t seed)
	Fill buf with the demo's deterministic byte ramp.
static bool	internal_demo_matches (const uint8_t *buf, uint32_t len, uint8_t seed)
	Test whether buf holds the demo's deterministic byte ramp.
static ra8_err_t	internal_demo_build_cfg (const cache_store_demo_cfg_t *in, bool format, ra8_cache_store_cfg_t *out)
	Build an ra8_cache_store init config from the demo config.
static ra8_err_t	internal_demo_put_and_verify (ra8_cache_store_t *st, uint32_t key, uint8_t seed, uint32_t len, const cache_store_demo_cfg_t *cfg)
	Put a blob, then read it back whole and verify it byte-identical.
static ra8_err_t	internal_demo_get_and_verify (const ra8_cache_store_t *st, uint32_t key, uint8_t seed, uint32_t len, const cache_store_demo_cfg_t *cfg)
	Read a sealed blob back and verify it byte-identical (no put).
static ra8_err_t	internal_demo_phase_seed (ra8_cache_store_t *st, const cache_store_demo_cfg_t *cfg)
	Seed the store: put + read-verify the four demo blobs.
static ra8_err_t	internal_demo_phase_evict (ra8_cache_store_t *st)
	Pin one entry, force an eviction, and prove the invariants hold.
static ra8_err_t	internal_demo_verify_survivors (const ra8_cache_store_t *st, const cache_store_demo_cfg_t *cfg)
	Read-verify the four entries expected to survive the remount.
static ra8_err_t	internal_demo_phase_remount (const cache_store_demo_cfg_t *cfg, cache_store_demo_result_t *out)
	Simulate a reboot: re-mount over the same media and confirm survival.
ra8_err_t	cache_store_demo_run (const cache_store_demo_cfg_t *cfg, cache_store_demo_result_t *out)
	Run the full ra8_cache_store on-media cache demonstration, end to end.

Detailed Description

Hardware-free ra8_cache_store on-media cache demo – implementation (#257).

Tag

[Ring 6 / APP] {World: S}

Drives ra8_cache_store end to end over an injected LevelX NOR driver: mount, put/get four keyed "render/glyph cache" blobs, pin one, force an eviction, re-put into the reclaimed sectors, checkpoint-close, then remount over the same media and confirm the survivors + the pin persisted. Touches no peripheral register, so the emulator and silicon runs are identical.

Copyright

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

Definition in file cache_store_demo.c.

Enumeration Type Documentation

demo_count_t

enum demo_count_t : uint32_t

Expected live-entry count after the remount.

cover + tile_a + tile_c + tile_d survive; tile_b was evicted.

Since

0.1.0

Enumerator
k_demo_survivors	Entries expected live after the remount.

Definition at line 76 of file cache_store_demo.c.

demo_key_t

enum demo_key_t : uint32_t

Content keys for the demo's cached blobs (source CRC-32 stand-ins).

The cover atlas is the pinned entry; tile_b is the one forcibly evicted; tile_d is re-put into the space tile_b freed.

Since

0.1.0

Enumerator
k_demo_key_cover	Open-book cover glyph atlas (pinned).
k_demo_key_tile_a	Render tile A (survivor).
k_demo_key_tile_b	Render tile B (forcibly evicted).
k_demo_key_tile_c	Render tile C (survivor).
k_demo_key_tile_d	Render tile D (re-put after eviction).

Definition at line 36 of file cache_store_demo.c.

demo_len_t

enum demo_len_t : uint32_t

Payload lengths (bytes) for the demo blobs; several cross a sector.

Since

0.1.0

Enumerator
k_demo_len_cover	Cover atlas length.
k_demo_len_tile_a	Tile A length.
k_demo_len_tile_b	Tile B length.
k_demo_len_tile_c	Tile C length.
k_demo_len_tile_d	Tile D length.

Definition at line 49 of file cache_store_demo.c.

demo_seed_t

enum demo_seed_t : uint8_t

Per-blob deterministic fill seeds (a distinct byte ramp per key).

Since

0.1.0

Enumerator
k_demo_seed_cover	Cover atlas seed.
k_demo_seed_tile_a	Tile A seed.
k_demo_seed_tile_b	Tile B seed.
k_demo_seed_tile_c	Tile C seed.
k_demo_seed_tile_d	Tile D seed.

Definition at line 62 of file cache_store_demo.c.

Function Documentation

cache_store_demo_run()

ra8_err_t cache_store_demo_run ( const cache_store_demo_cfg_t * cfg, cache_store_demo_result_t * out )

nodiscard

Run the full ra8_cache_store on-media cache demonstration, end to end.

Executes, in order, over the injected NOR driver:

1. Format + mount a fresh cache_store.
2. Put four keyed "render/glyph cache" blobs and read each back byte-identical (whole + sliced reads).
3. Pin one entry (the open-book cover atlas – never evict), then force an eviction of an un-pinned entry; confirm it is now a miss, the survivors still read, and evicting the pinned entry is refused (busy).
4. Re-put a new blob, proving the evicted entry's sectors were reclaimed.
5. Checkpoint + clean-close the store.
6. Re-mount over the same media with a fresh (zeroed) control block – a simulated reboot – and confirm the survivors (including the pinned one) come back byte-identical, the evicted key stays gone, and the pin persisted across the checkpoint.

Parameters

[in]	cfg	Injected dependencies + buffers (see the struct).
[out]	out	Receives the verdict + observable facts.

Returns

Error code.

Return values

k_ra8_ok	Every stage passed (out->status == ok).
k_ra8_err_null_ptr	cfg, out, or a required buffer was NULL.
k_ra8_err_invalid_state	A stage failed; out->status / out->last_stage name it.

Precondition

cfg and out are non-NULL.

Every non-optional cfg member is non-NULL and correctly sized.

Postcondition

out->status and out->last_stage reflect how far the run got.

On k_ra8_ok, out->survivors counts the entries that survived the remount and both survival flags are true.

Note

Not thread-safe.

See also

cache_store_demo_result_t

Since

0.1.0

Definition at line 479 of file cache_store_demo.c.

References internal_demo_build_cfg(), internal_demo_phase_evict(), internal_demo_phase_remount(), internal_demo_phase_seed(), internal_demo_put_and_verify(), k_cache_store_demo_err_arg, k_cache_store_demo_err_close, k_cache_store_demo_err_evict, k_cache_store_demo_err_mount, k_cache_store_demo_err_reuse, k_cache_store_demo_err_seed, k_cache_store_demo_ok, k_cache_store_demo_stage_closed, k_cache_store_demo_stage_evicted, k_cache_store_demo_stage_mounted, k_cache_store_demo_stage_none, k_cache_store_demo_stage_persisted, k_cache_store_demo_stage_reused, k_cache_store_demo_stage_seeded, k_demo_key_tile_b, k_demo_key_tile_d, k_demo_len_tile_d, k_demo_seed_tile_d, k_ra8_err_invalid_state, k_ra8_ok, cache_store_demo_result_t::last_stage, ra8_cache_store_close(), ra8_cache_store_init(), RA8_CHECK_NULL_PTR, and cache_store_demo_result_t::status.

Referenced by main().

internal_demo_build_cfg()

ra8_err_t internal_demo_build_cfg ( const cache_store_demo_cfg_t * in, bool format, ra8_cache_store_cfg_t * out )

static

Build an ra8_cache_store init config from the demo config.

Copies every injected dependency and storage seam into the public store configuration while selecting whether this mount formats the media.

Parameters

[in]	in	Demo config (injected deps + buffers).
[in]	format	True to format (wipe) before open, false to remount.
[out]	out	Receives the populated store config.

Returns

Error code.

Return values

k_ra8_ok	Config populated.
k_ra8_err_null_ptr	in or out was NULL.

Precondition

in and out are non-NULL.

in's buffers out-live the store built from the config.

Postcondition

On success out references in's buffers.

No global state changes.

Note

Not thread-safe; operates only on the caller's structs.

Since

0.1.0

Definition at line 159 of file cache_store_demo.c.

References cache_store_demo_cfg_t::index, cache_store_demo_cfg_t::index_cap, k_ra8_ok, cache_store_demo_cfg_t::logical_sectors, cache_store_demo_cfg_t::nor_driver_init, cache_store_demo_cfg_t::nor_flash, RA8_CHECK_NULL_PTR, cache_store_demo_cfg_t::staging, and cache_store_demo_cfg_t::staging_bytes.

Referenced by cache_store_demo_run(), and internal_demo_phase_remount().

internal_demo_fill()

void internal_demo_fill ( uint8_t * buf, uint32_t len, uint8_t seed )

static

Fill buf with the demo's deterministic byte ramp.

Writes a wrapping seed-plus-index pattern over exactly len bytes, returning without modification when the destination is NULL or empty.

Parameters

[out]	buf	Destination buffer.
[in]	len	Byte count.
[in]	seed	Ramp seed (buf[i] == (seed + i) & 0xFF).

Returns

Nothing.

Precondition

buf is non-NULL, or len is 0.

len is the intended pattern length.

Postcondition

On a non-NULL buffer, buf[i] == (uint8_t)(seed + i) for every i.

No state outside buf changes.

Note

Pure over its arguments (thread-safe).

Since

0.1.0

Definition at line 95 of file cache_store_demo.c.

References RA8_INTERNAL.

Referenced by internal_demo_put_and_verify().

internal_demo_get_and_verify()

ra8_err_t internal_demo_get_and_verify ( const ra8_cache_store_t * st, uint32_t key, uint8_t seed, uint32_t len, const cache_store_demo_cfg_t * cfg )

static

Read a sealed blob back and verify it byte-identical (no put).

Opens the keyed reader, validates the sealed length, reads into the shared scratch buffer, and checks the deterministic expected pattern.

Parameters

[in]	st	Initialised store.
[in]	key	Content key to open.
[in]	seed	Deterministic fill seed the blob was written with.
[in]	len	Expected blob length in bytes.
[in]	cfg	Demo config (supplies the read scratch buffer).

Returns

Error code.

Return values

k_ra8_ok	Present and byte-identical.
k_ra8_err_null_ptr	st or cfg was NULL.
k_ra8_err_invalid_state	Read-back diverged or wrong length.
other	A store get/read error, propagated.

Precondition

st is mounted and cfg is non-NULL.

cfg->scratch_bytes >= len.

Postcondition

On k_ra8_ok, key held exactly the expected blob.

cfg->scratch holds the read-back bytes.

Note

Not thread-safe; reuses the single scratch buffer.

Since

0.1.0

Definition at line 256 of file cache_store_demo.c.

References ra8_cache_store_reader_t::byte_len, internal_demo_matches(), k_ra8_err_invalid_state, k_ra8_ok, memset(), ra8_cache_store_get(), ra8_cache_store_read(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, and cache_store_demo_cfg_t::scratch.

Referenced by internal_demo_verify_survivors().

internal_demo_matches()

bool internal_demo_matches ( const uint8_t * buf, uint32_t len, uint8_t seed )

static

Test whether buf holds the demo's deterministic byte ramp.

Compares every requested byte with the same wrapping seed-plus-index rule used by internal_demo_fill and stops at the first mismatch.

Parameters

[in]	buf	Buffer to check.
[in]	len	Byte count.
[in]	seed	Expected ramp seed.

Returns

True iff every byte matches (seed + i) & 0xFF.

Return values

true	Every byte matches (or len is 0).
false	buf is NULL, or a byte diverges.

Precondition

buf is non-NULL, or len is 0.

seed matches the seed the buffer was filled with.

Postcondition

buf is unmodified (pure read).

The result depends only on the arguments.

Note

Pure over its arguments (thread-safe).

Since

0.1.0

Definition at line 125 of file cache_store_demo.c.

References RA8_INTERNAL.

Referenced by internal_demo_get_and_verify(), and internal_demo_put_and_verify().

internal_demo_phase_evict()

ra8_err_t internal_demo_phase_evict ( ra8_cache_store_t * st )

static

Pin one entry, force an eviction, and prove the invariants hold.

Pins the cover atlas (never evict the open book), evicts tile_b, then checks: tile_b is now a miss; the survivors (tile_a, tile_c) still resolve; and evicting the pinned cover is refused with busy.

Parameters

[in,out]

st

Initialised, seeded store.

Returns

Error code.

Return values

k_ra8_ok	Eviction + all guards behaved.
k_ra8_err_null_ptr	st was NULL.
k_ra8_err_invalid_state	An expected guard result did not hold.
other	A store pin/evict/get error, propagated.

Precondition

st is mounted with all four seed entries live.

The cover key is present (to pin it).

Postcondition

On k_ra8_ok, tile_b is evicted and the cover is pinned.

On k_ra8_ok, the pinned cover cannot be evicted.

Note

Not thread-safe.

Since

0.1.0

Definition at line 347 of file cache_store_demo.c.

References k_demo_key_cover, k_demo_key_tile_a, k_demo_key_tile_b, k_demo_key_tile_c, k_ra8_err_busy, k_ra8_err_invalid_state, k_ra8_err_not_found, k_ra8_ok, ra8_cache_store_evict(), ra8_cache_store_get(), ra8_cache_store_pin(), RA8_CHECK_NULL_PTR, and RA8_INTERNAL.

Referenced by cache_store_demo_run().

internal_demo_phase_remount()

ra8_err_t internal_demo_phase_remount ( const cache_store_demo_cfg_t * cfg, cache_store_demo_result_t * out )

static

Simulate a reboot: re-mount over the same media and confirm survival.

Zeroes the control RAM (index + staging + a fresh handle) to model a power cycle – the on-media content in the injected NOR backing survives, the RAM does not – then re-mounts with format=false and verifies the survivors byte-identical, the evicted key still gone, and the pin persisted across the checkpoint.

Parameters

[in]	cfg	Demo config.
[out]	out	Result to update (survivors, flags, status on failure).

Returns

Error code.

Return values

k_ra8_ok	Every survivor + invariant held.
k_ra8_err_null_ptr	cfg or out was NULL.
k_ra8_err_invalid_state	A survivor / eviction / pin did not persist.

Precondition

cfg and out are non-NULL.

A prior run closed the store cleanly over the same media.

Postcondition

On k_ra8_ok, out->survivors == k_demo_survivors and both flags set.

On failure out->status == k_cache_store_demo_err_remount/_persist.

Note

Not thread-safe.

Since

0.1.0

Definition at line 440 of file cache_store_demo.c.

References cache_store_demo_result_t::evicted_stayed_gone, cache_store_demo_cfg_t::index, cache_store_demo_cfg_t::index_cap, internal_demo_build_cfg(), internal_demo_verify_survivors(), k_cache_store_demo_err_persist, k_cache_store_demo_err_remount, k_cache_store_demo_stage_remounted, k_demo_key_cover, k_demo_key_tile_b, k_demo_survivors, k_ra8_err_busy, k_ra8_err_invalid_state, k_ra8_err_not_found, k_ra8_ok, cache_store_demo_result_t::last_stage, memset(), cache_store_demo_result_t::pin_survived, ra8_cache_store_close(), ra8_cache_store_evict(), ra8_cache_store_get(), ra8_cache_store_init(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, cache_store_demo_cfg_t::staging, cache_store_demo_cfg_t::staging_bytes, cache_store_demo_result_t::status, and cache_store_demo_result_t::survivors.

Referenced by cache_store_demo_run().

internal_demo_phase_seed()

ra8_err_t internal_demo_phase_seed ( ra8_cache_store_t * st, const cache_store_demo_cfg_t * cfg )

static

Seed the store: put + read-verify the four demo blobs.

Inserts cover and tile blobs in deterministic order, short-circuiting after the first failed seal or read-back verification.

Parameters

[in,out]	st	Initialised store.
[in]	cfg	Demo config.

Returns

Error code (first failure short-circuits).

Return values

k_ra8_ok	All four sealed + verified.
k_ra8_err_null_ptr	st or cfg was NULL.
other	The first failing put/verify's error.

Precondition

st is mounted and empty.

cfg is non-NULL with a large-enough scratch buffer.

Postcondition

On k_ra8_ok, four keyed entries are live.

On any error no further blob is put.

Note

Not thread-safe.

Since

0.1.0

Definition at line 300 of file cache_store_demo.c.

References internal_demo_put_and_verify(), k_demo_key_cover, k_demo_key_tile_a, k_demo_key_tile_b, k_demo_key_tile_c, k_demo_len_cover, k_demo_len_tile_a, k_demo_len_tile_b, k_demo_len_tile_c, k_demo_seed_cover, k_demo_seed_tile_a, k_demo_seed_tile_b, k_demo_seed_tile_c, k_ra8_ok, RA8_CHECK_NULL_PTR, and RA8_INTERNAL.

Referenced by cache_store_demo_run().

internal_demo_put_and_verify()

ra8_err_t internal_demo_put_and_verify ( ra8_cache_store_t * st, uint32_t key, uint8_t seed, uint32_t len, const cache_store_demo_cfg_t * cfg )

static

Put a blob, then read it back whole and verify it byte-identical.

Fills the shared scratch buffer, seals the keyed blob, reopens it, validates its length, reads it back, and verifies the deterministic pattern.

Parameters

[in,out]	st	Initialised store.
[in]	key	Content key.
[in]	seed	Deterministic fill seed for the blob.
[in]	len	Blob length in bytes.
[in]	cfg	Demo config (supplies the read/write scratch buffer).

Returns

Error code.

Return values

k_ra8_ok	Sealed and verified.
k_ra8_err_null_ptr	st or cfg was NULL.
k_ra8_err_invalid_size	Scratch too small for len.
k_ra8_err_invalid_state	Read-back diverged or wrong length.
other	A store put/get/read error, propagated.

Precondition

st is mounted and cfg is non-NULL.

cfg->scratch_bytes >= len.

Postcondition

On k_ra8_ok, key streams back exactly the written blob.

On any error the store is left as ra8_cache_store defines.

Note

Not thread-safe; reuses the single scratch buffer.

Since

0.1.0

Definition at line 200 of file cache_store_demo.c.

References ra8_cache_store_reader_t::byte_len, internal_demo_fill(), internal_demo_matches(), k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, memset(), ra8_cache_store_get(), ra8_cache_store_put(), ra8_cache_store_read(), RA8_CHECK_NULL_PTR, RA8_INTERNAL, cache_store_demo_cfg_t::scratch, and cache_store_demo_cfg_t::scratch_bytes.

Referenced by cache_store_demo_run(), and internal_demo_phase_seed().

internal_demo_verify_survivors()

ra8_err_t internal_demo_verify_survivors ( const ra8_cache_store_t * st, const cache_store_demo_cfg_t * cfg )

static

Read-verify the four entries expected to survive the remount.

Single-condition sequential checks (no compound decision) over the cover atlas plus tiles A, C, and the re-put tile D.

Parameters

[in]	st	Re-mounted store.
[in]	cfg	Demo config (scratch buffer).

Returns

Error code (first failure short-circuits).

Return values

k_ra8_ok	All four survivors present + byte-identical.
k_ra8_err_null_ptr	st or cfg was NULL.
other	The first failing survivor's error.

Precondition

st is a store re-mounted over the persisted media.

cfg is non-NULL with a large-enough scratch buffer.

Postcondition

On k_ra8_ok, every survivor held exactly its written blob.

On any error no further survivor is read.

Note

Not thread-safe; reuses the single scratch buffer.

Since

0.1.0

Definition at line 391 of file cache_store_demo.c.

References internal_demo_get_and_verify(), k_demo_key_cover, k_demo_key_tile_a, k_demo_key_tile_c, k_demo_key_tile_d, k_demo_len_cover, k_demo_len_tile_a, k_demo_len_tile_c, k_demo_len_tile_d, k_demo_seed_cover, k_demo_seed_tile_a, k_demo_seed_tile_c, k_demo_seed_tile_d, k_ra8_ok, RA8_CHECK_NULL_PTR, and RA8_INTERNAL.

Referenced by internal_demo_phase_remount().