ra8_io_blockdev_cache.h File Reference

ra8_io caching block device – an LRU sector cache over any backend. More...

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

Include dependency graph for ra8_io_blockdev_cache.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_io_blockdev_cache_slot_t
	Per-sector cache metadata (one caller-owned array entry per slot). More...
struct	ra8_io_blockdev_cache_state_t
	Caller-owned private state for a caching block device. More...

Functions
ra8_err_t	ra8_io_blockdev_cache_init (ra8_io_blockdev_t *bd, ra8_io_blockdev_cache_state_t *state, const ra8_io_blockdev_t *under, uint8_t *data, ra8_io_blockdev_cache_slot_t *slots, uint32_t n_slots)
	Bind a caching block device over an existing backend.
ra8_err_t	ra8_io_blockdev_cache_stats (const ra8_io_blockdev_cache_state_t *state, uint32_t *out_hits, uint32_t *out_misses)
	Report the cache hit/miss counters.

Detailed Description

ra8_io caching block device – an LRU sector cache over any backend.

Tag

[Ring 4 / PAL] {World: NS}

A decorator block device: it wraps another ra8_io_blockdev_t and keeps a fixed set of recently-used 512-byte sectors in a caller-owned cache, so repeated reads of the same blocks (filesystem metadata, a re-read EPUB page, a glyph atlas) skip the slow medium. Reads are served from the cache on a hit and fill it on a miss; writes are write-through (committed to the backend immediately and reflected in the cache). Eviction is least-recently-used.

This is the cache layer between the filesystem/VFS and the media. It composes with the unified page-cache design of issue #147 (and the SLRU policy chosen by tools/cache_bench); this first cut uses straightforward write-through LRU and exposes hit/miss counters for observability.

Zero allocation: the caller provides the sector data buffer and the slot metadata array, sized to the chosen number of cached sectors.

static uint8_t                     s_cache_data[32U * 512U];
static ra8_io_blockdev_cache_slot_t s_cache_slots[32U];
static ra8_io_blockdev_cache_state_t s_cache_state;
ra8_io_blockdev_t cached = {};
(void)ra8_io_blockdev_cache_init(&cached, &s_cache_state, &sd_bd,
                                s_cache_data, s_cache_slots, 32U);
// `cached` now behaves like sd_bd but caches 32 sectors.

Copyright

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

Since

0.1.0

Definition in file ra8_io_blockdev_cache.h.

Function Documentation

ra8_io_blockdev_cache_init()

ra8_err_t ra8_io_blockdev_cache_init ( ra8_io_blockdev_t * bd, ra8_io_blockdev_cache_state_t * state, const ra8_io_blockdev_t * under, uint8_t * data, ra8_io_blockdev_cache_slot_t * slots, uint32_t n_slots )

nodiscard

Bind a caching block device over an existing backend.

Parameters

[out]	bd	Handle to bind (zero-initialised by the caller).
[out]	state	Caller-owned cache state to populate.
[in]	under	Backend to wrap (must out-live the cache).
[in]	data	Cache data buffer of n_slots * 512 bytes.
[in]	slots	Cache metadata array of n_slots entries.
[in]	n_slots	Number of cached sectors (>= 1).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Cache bound; bd is usable.
k_ra8_err_null_ptr	bd, state, under, data, or slots NULL.
k_ra8_err_invalid_size	n_slots was zero.

Precondition

data covers n_slots * 512 bytes and slots holds n_slots entries.

under, bd, state, data, slots out-live every cached access.

Postcondition

On success bd reads/writes through an LRU cache over under.

On any non-ok return bd and state are left unbound/untouched.

Note

Not thread-safe with respect to the same cache.

Since

0.1.0

Definition at line 461 of file ra8_io_blockdev_cache.c.

References ra8_io_blockdev_t::ctx, ra8_io_blockdev_t::iface, internal_cache_reset_slots(), internal_cache_state_init(), k_ra8_err_invalid_size, k_ra8_ok, RA8_CHECK_NULL_PTR, s_cache_iface, and s_tag.

Referenced by internal_demo_mount().

ra8_io_blockdev_cache_stats()

ra8_err_t ra8_io_blockdev_cache_stats ( const ra8_io_blockdev_cache_state_t * state, uint32_t * out_hits, uint32_t * out_misses )

nodiscard

Report the cache hit/miss counters.

Parameters

[in]	state	Bound cache state.
[out]	out_hits	Read hits so far (may be NULL).
[out]	out_misses	Read misses so far (may be NULL).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Counters reported.
k_ra8_err_null_ptr	state was NULL.

Precondition

state was populated by ra8_io_blockdev_cache_init.

At least one of the output pointers is non-NULL to be useful.

Postcondition

On success the requested counters are written.

No state is mutated.

Note

Thread-safe (pure read).

Since

0.1.0

Definition at line 483 of file ra8_io_blockdev_cache.c.

References ra8_io_blockdev_cache_state_t::hits, k_ra8_ok, ra8_io_blockdev_cache_state_t::misses, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_demo_run().