Hardware-free driver for the ra8_cache_store on-media cache demo (#257). More...

#include <stdint.h>
#include "ra8_cache_store.h"
#include "ra8_err.h"

Include dependency graph for cache_store_demo.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	cache_store_demo_result_t
	Outcome + observable facts of one demo run (for the banner / asserts). More...
struct	cache_store_demo_cfg_t
	Injected dependencies + caller-owned buffers for cache_store_demo_run. More...

Enumerations
enum	cache_store_demo_stage_t : uint8_t { k_cache_store_demo_stage_none = 0U , k_cache_store_demo_stage_mounted = 1U , k_cache_store_demo_stage_seeded = 2U , k_cache_store_demo_stage_evicted = 3U , k_cache_store_demo_stage_reused = 4U , k_cache_store_demo_stage_closed = 5U , k_cache_store_demo_stage_remounted = 6U , k_cache_store_demo_stage_persisted = 7U }
	Furthest sequence stage the demo reached (for diagnostics on failure). More...
enum	cache_store_demo_status_t : uint8_t { k_cache_store_demo_ok = 0U , k_cache_store_demo_err_arg = 1U , k_cache_store_demo_err_mount = 2U , k_cache_store_demo_err_seed = 3U , k_cache_store_demo_err_evict = 4U , k_cache_store_demo_err_reuse = 5U , k_cache_store_demo_err_close = 6U , k_cache_store_demo_err_remount = 7U , k_cache_store_demo_err_persist = 8U }
	Granular verdict for one cache_store_demo_run. More...

Functions
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 driver for the ra8_cache_store on-media cache demo (#257).

Factors the whole ra8_cache_store demonstration – mount, put/get several keyed blobs, pin one, force an eviction, re-put into the reclaimed space, close, then remount and confirm on-media persistence – into a single pure function that touches NO hardware. It takes the injected LevelX NOR driver-initialise callback (ra8_cache_store_nor_init_fn) plus all caller-owned buffers, so the identical logic runs in two places: the ARM example's main.c binds a RAM-backed NOR driver over SRAM, and the host unit test binds the same driver on the x86_64 host. That shared core is what makes the ra8_emulator gate and the host test exercise byte-identical behaviour.

Note: Not thread-safe: ra8_cache_store serialises access (one reader core).

See also: cache_store_demo_run The single entry point.

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

Since: 0.1.0

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

Definition in file cache_store_demo.h.

Enumeration Type Documentation

◆ cache_store_demo_stage_t

enum cache_store_demo_stage_t : uint8_t

Furthest sequence stage the demo reached (for diagnostics on failure).

Recorded in cache_store_demo_result_t::last_stage so a failing run reports exactly which step broke.

Since: 0.1.0

Enumerator
k_cache_store_demo_stage_none	Nothing ran yet.
k_cache_store_demo_stage_mounted	Store formatted + mounted.
k_cache_store_demo_stage_seeded	Entries put + read-verified.
k_cache_store_demo_stage_evicted	Pinned one, forced an eviction.
k_cache_store_demo_stage_reused	Re-put into the reclaimed sectors.
k_cache_store_demo_stage_closed	Checkpointed + clean-closed.
k_cache_store_demo_stage_remounted	Re-opened over the same media.
k_cache_store_demo_stage_persisted	Survivors + pin confirmed on media.

Definition at line 44 of file cache_store_demo.h.

◆ cache_store_demo_status_t

enum cache_store_demo_status_t : uint8_t

Granular verdict for one cache_store_demo_run.

k_cache_store_demo_ok means every stage passed; any other value names the stage that failed.

Since: 0.1.0

Enumerator
k_cache_store_demo_ok	All stages passed.
k_cache_store_demo_err_arg	NULL config / result / buffer.
k_cache_store_demo_err_mount	Format + mount failed.
k_cache_store_demo_err_seed	A put or its read-back verify failed.
k_cache_store_demo_err_evict	Eviction / survivor / pin-guard failed.
k_cache_store_demo_err_reuse	Re-put into reclaimed sectors failed.
k_cache_store_demo_err_close	Checkpoint + close failed.
k_cache_store_demo_err_remount	Re-mount over the same media failed.
k_cache_store_demo_err_persist	A survivor / eviction / pin did not. survive the remount.

Definition at line 62 of file cache_store_demo.h.

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:

Format + mount a fresh cache_store.
Put four keyed "render/glyph cache" blobs and read each back byte-identical (whole + sliced reads).
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).
Re-put a new blob, proving the evicted entry's sectors were reclaimed.
Checkpoint + clean-close the store.
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.

Referenced by main().

Data Structures