ra8_cache_store_internal.h File Reference

Internal on-media format + cross-TU helpers for ra8_cache_store (#201). More...

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

Include dependency graph for ra8_cache_store_internal.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_cs_super_t
	On-flash superblock at logical sector 0 (also the checkpoint commit). More...
struct	ra8_cs_entry_hdr_t
	On-flash entry header at a run's first logical sector. More...
struct	ra8_cs_dir_ent_t
	One serialized directory entry in the checkpoint region (16 bytes). More...

Enumerations
enum	ra8_cs_media_const_t : uint32_t {   k_ra8_cs_super_magic = 0x52435331U ,   k_ra8_cs_entry_magic = 0x52435345U ,   k_ra8_cs_format_version = 1U ,   k_ra8_cs_dir_ent_bytes = 16U ,   k_ra8_cs_dir_per_sector = 32U ,   k_ra8_cs_crc32_poly = 0xEDB88320U ,   k_ra8_cs_crc32_seed = 0xFFFFFFFFU }
	Magics + serialization sizing for the on-flash records. More...
enum	ra8_cs_clean_t : uint32_t {   k_ra8_cs_dirty = 0U ,   k_ra8_cs_clean = 1U }
	Values of ra8_cs_super_t::clean (the shutdown marker). More...

Functions
uint32_t	priv_cache_store_crc32 (const uint8_t *data, uint32_t len)
	Fold a byte block into a CRC-32/ISO-HDLC value (seeded + finalised).
ra8_err_t	priv_cache_store_sector_read (const ra8_cache_store_t *store, uint32_t sector, uint8_t *out512)
	Read one LevelX logical sector into the store staging buffer region.
ra8_err_t	priv_cache_store_sector_write (ra8_cache_store_t *store, uint32_t sector, const uint8_t *in512)
	Write one LevelX logical sector from a one-sector source buffer.
ra8_err_t	priv_cache_store_sector_release (ra8_cache_store_t *store, uint32_t sector)
	Release a LevelX logical sector back to the free pool.
int32_t	priv_cache_store_index_find (const ra8_cache_store_t *store, uint32_t key)
	Find the index slot holding key.
int32_t	priv_cache_store_index_add (ra8_cache_store_t *store, uint32_t key, uint32_t start_sector, uint16_t sector_count, uint32_t byte_len, bool pinned)
	Claim a free index slot and populate it for key.
ra8_err_t	priv_cache_store_super_write (ra8_cache_store_t *store, uint32_t clean)
	Write the superblock (sector 0) with the given clean marker.
ra8_err_t	priv_cache_store_dir_save (ra8_cache_store_t *store, uint32_t *out_entry_count)
	Serialize the live index into the on-flash checkpoint directory.

Detailed Description

Internal on-media format + cross-TU helpers for ra8_cache_store (#201).

Private to libs/ra8_cache_store/src/. Declares the three fixed-width on-flash records (superblock, entry header, directory entry) and the helpers shared between the runtime TU (ra8_cache_store.c) and the mount/recovery TU (ra8_cache_store_mount.c). Not a public interface – consumers use ra8_cache_store.h.

On-flash layout over the LevelX logical-sector space:

Logical sector(s)	Contents
0	ra8_cs_super_t (superblock + clean marker)
[1, log_start)	directory checkpoint (ra8_cs_dir_ent_t run)
[log_start, logical)	append log: ra8_cs_entry_hdr_t + payload

Records are written little-endian and consumed only by the same firmware build/platform that wrote them (host tests read back on the host; the target reads back on the target), so no byte-order translation is performed. Each record's trailing CRC-32 covers all preceding fields.

Note

Not thread-safe; the store serialises access.

Copyright

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

Since

0.1.0

Tag

[Ring 4 / Storage] {World: NS}

Definition in file ra8_cache_store_internal.h.

Enumeration Type Documentation

ra8_cs_clean_t

enum ra8_cs_clean_t : uint32_t

Values of ra8_cs_super_t::clean (the shutdown marker).

Since

0.1.0

Enumerator
k_ra8_cs_dirty	Session open or crashed -> mount must replay the log.
k_ra8_cs_clean	Clean shutdown -> the checkpoint directory is valid.

Definition at line 67 of file ra8_cache_store_internal.h.

ra8_cs_media_const_t

enum ra8_cs_media_const_t : uint32_t

Magics + serialization sizing for the on-flash records.

Since

0.1.0

Enumerator
k_ra8_cs_super_magic	Superblock tag 'R','C','S','1'.
k_ra8_cs_entry_magic	Entry-header tag 'R','C','S','E'.
k_ra8_cs_format_version	On-flash layout revision.
k_ra8_cs_dir_ent_bytes	Serialized ra8_cs_dir_ent_t size.
k_ra8_cs_dir_per_sector	Directory entries per 512-byte sector.
k_ra8_cs_crc32_poly	Reflected CRC-32/ISO-HDLC polynomial.
k_ra8_cs_crc32_seed	CRC-32 pre/post conditioning.

Definition at line 52 of file ra8_cache_store_internal.h.

Function Documentation

priv_cache_store_crc32()

uint32_t priv_cache_store_crc32	(	const uint8_t *	data,
		uint32_t	len )

Fold a byte block into a CRC-32/ISO-HDLC value (seeded + finalised).

Standalone bitwise reflected CRC over one contiguous block: seeds and XOR-finalises with k_ra8_cs_crc32_seed internally, so the caller passes raw bytes and gets the final CRC. Used to seal every on-flash record.

Parameters

[in]	data	Bytes to fold (may be NULL only when len is 0).
[in]	len	Byte count.

Returns

The finalised CRC-32 over data.

Return values

uint32_t

CRC over the len bytes; the empty-input CRC when len==0.

Precondition

data covers len readable bytes, or len is 0.

The caller wants ISO-HDLC (zlib-compatible) conditioning.

Postcondition

data is unmodified.

The result depends only on the input bytes (pure function).

Note

Thread-safe: pure over its arguments.

Since

0.1.0

Definition at line 55 of file ra8_cache_store_mount.c.

References k_ra8_cs_crc32_poly, k_ra8_cs_crc32_seed, k_ra8_cs_crc_bits, and RA8_PRIV.

Referenced by internal_hdr_read(), internal_super_is_clean(), internal_write_entry(), and priv_cache_store_super_write().

priv_cache_store_dir_save()

ra8_err_t priv_cache_store_dir_save	(	ra8_cache_store_t *	store,
		uint32_t *	out_entry_count )

Serialize the live index into the on-flash checkpoint directory.

Packs every in-use slot as an ra8_cs_dir_ent_t across the directory region [1, log_start), then returns the count so the caller can put it in the superblock. Does not touch sector 0.

Parameters

[in,out]	store	Store whose index is serialized.
[out]	out_entry_count	Receives the number of entries written.

Returns

Error code.

Return values

k_ra8_ok	Directory written.
k_ra8_err_hw_init_failed	LevelX write error.

Precondition

store->checkpoint_dirs directory sectors were reserved at init.

out_entry_count is writable.

Postcondition

On k_ra8_ok, *out_entry_count in-use entries are on flash.

The superblock is untouched (caller commits it).

Note

Not thread-safe; shares the store staging buffer.

Since

0.1.0

Definition at line 320 of file ra8_cache_store_mount.c.

References ra8_cache_store_t::checkpoint_dirs, internal_dir_pack_sector(), k_ra8_ok, priv_cache_store_sector_write(), RA8_CHECK_NULL_PTR, RA8_PRIV, RA8_RETURN_ON_ERROR, s_tag, and ra8_cache_store_t::staging.

Referenced by internal_checkpoint().

priv_cache_store_index_add()

int32_t priv_cache_store_index_add	(	ra8_cache_store_t *	store,
		uint32_t	key,
		uint32_t	start_sector,
		uint16_t	sector_count,
		uint32_t	byte_len,
		bool	pinned )

Claim a free index slot and populate it for key.

Claims the first free slot and records the entry's location, run length, and flags.

Parameters

[in,out]	store	Store whose index gains an entry.
[in]	key	Content key.
[in]	start_sector	Entry header logical sector.
[in]	sector_count	Run length (header + payload).
[in]	byte_len	Payload length in bytes.
[in]	pinned	Persist the pinned flag.

Returns

Slot index, or -1 when the index is full.

Return values

-1	No free slot.

Precondition

store->index covers store->index_cap slots.

key is not already present (caller checked).

Postcondition

On success the slot is in-use with the given fields.

On failure the index is unchanged.

Note

Not thread-safe; the store serialises access.

Since

0.1.0

Definition at line 138 of file ra8_cache_store_mount.c.

References ra8_cache_store_entry_t::flags, ra8_cache_store_t::index, ra8_cache_store_t::index_cap, k_ra8_cache_store_flag_in_use, k_ra8_cache_store_flag_pinned, and RA8_PRIV.

Referenced by internal_dir_unpack_sector(), internal_scan_accept(), and ra8_cache_store_put().

priv_cache_store_index_find()

int32_t priv_cache_store_index_find	(	const ra8_cache_store_t *	store,
		uint32_t	key )

Find the index slot holding key.

Linear scan of the in-use index slots for a matching key.

Parameters

[in]	store	Store to search.
[in]	key	Content key.

Returns

Slot index, or -1 when key is not present.

Return values

-1	No in-use slot matches key.

Precondition

store->index covers store->index_cap slots.

The index reflects the live set.

Postcondition

The store is unmodified (pure lookup).

A non-negative result indexes an in-use slot with key == @p key.

Note

Thread-safe with respect to a quiescent store (pure read).

Since

0.1.0

Definition at line 118 of file ra8_cache_store_mount.c.

References ra8_cache_store_entry_t::flags, ra8_cache_store_t::index, ra8_cache_store_t::index_cap, k_ra8_cache_store_flag_in_use, ra8_cache_store_entry_t::key, and RA8_PRIV.

Referenced by internal_put_check(), internal_scan_accept(), ra8_cache_store_evict(), ra8_cache_store_get(), and ra8_cache_store_pin().

priv_cache_store_sector_read()

ra8_err_t priv_cache_store_sector_read	(	const ra8_cache_store_t *	store,
		uint32_t	sector,
		uint8_t *	out512 )

Read one LevelX logical sector into the store staging buffer region.

Wraps lx_nor_flash_sector_read, mapping the LevelX status onto an ra8_err_t.

Parameters

[in]	store	Store whose LevelX flash is read.
[in]	sector	Logical sector index.
[out]	out512	Destination of at least one sector.

Returns

Error code.

Return values

k_ra8_ok	Sector read.
k_ra8_err_not_found	Sector is unmapped/released (LevelX miss).
k_ra8_err_hw_init_failed	LevelX read error.

Precondition

store->flash is an open LevelX NOR partition.

out512 covers one sector.

Postcondition

On k_ra8_ok, out512 holds the sector bytes.

On any error out512 content is unspecified.

Note

Not thread-safe; the store serialises access.

Since

0.1.0

Definition at line 77 of file ra8_cache_store_mount.c.

References ra8_cache_store_t::flash, k_ra8_err_hw_init_failed, k_ra8_err_not_found, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_PRIV, and s_tag.

Referenced by internal_dir_load(), internal_hdr_read(), internal_read_at(), and internal_super_read().

priv_cache_store_sector_release()

ra8_err_t priv_cache_store_sector_release	(	ra8_cache_store_t *	store,
		uint32_t	sector )

Release a LevelX logical sector back to the free pool.

Wraps lx_nor_flash_sector_release, returning the logical sector to the free pool.

Parameters

[in,out]	store	Store whose LevelX flash is released.
[in]	sector	Logical sector index.

Returns

Error code.

Return values

k_ra8_ok	Sector released (or already free).
k_ra8_err_hw_init_failed	LevelX release error.

Precondition

store->flash is an open LevelX NOR partition.

sector is within the partition.

Postcondition

On k_ra8_ok, a later read of sector misses until rewritten.

The sector becomes available for a future allocation.

Note

Not thread-safe; the store serialises access.

Since

0.1.0

Definition at line 107 of file ra8_cache_store_mount.c.

References ra8_cache_store_t::flash, k_ra8_err_hw_init_failed, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_PRIV, and s_tag.

Referenced by internal_release_run().

priv_cache_store_sector_write()

ra8_err_t priv_cache_store_sector_write	(	ra8_cache_store_t *	store,
		uint32_t	sector,
		const uint8_t *	in512 )

Write one LevelX logical sector from a one-sector source buffer.

Wraps lx_nor_flash_sector_write, mapping a LevelX failure onto a hardware error.

Parameters

[in,out]	store	Store whose LevelX flash is written.
[in]	sector	Logical sector index.
[in]	in512	Source of exactly one sector.

Returns

Error code.

Return values

k_ra8_ok	Sector written.
k_ra8_err_hw_init_failed	LevelX write error (e.g. no free sectors).

Precondition

store->flash is an open LevelX NOR partition.

in512 covers one sector.

Postcondition

On k_ra8_ok, a later priv_cache_store_sector_read returns in512.

On any error the sector mapping is unchanged.

Note

Not thread-safe; the store serialises access.

Since

0.1.0

Definition at line 93 of file ra8_cache_store_mount.c.

References ra8_cache_store_t::flash, k_ra8_err_hw_init_failed, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_PRIV, and s_tag.

Referenced by internal_write_entry(), priv_cache_store_dir_save(), and priv_cache_store_super_write().

priv_cache_store_super_write()

ra8_err_t priv_cache_store_super_write	(	ra8_cache_store_t *	store,
		uint32_t	clean )

Write the superblock (sector 0) with the given clean marker.

Snapshots the store's live geometry (entry_count, live_sectors, next_seq, ...) plus clean into ra8_cs_super_t, seals it with a CRC, and writes sector 0 – the commit point of a checkpoint.

Parameters

[in,out]	store	Store to snapshot.
[in]	clean	ra8_cs_clean_t marker to stamp.

Returns

Error code.

Return values

k_ra8_ok	Superblock written.
k_ra8_err_hw_init_failed	LevelX write error.

Precondition

store->inited is true (or mid-init with geometry set).

store->staging covers one sector.

Postcondition

On k_ra8_ok, sector 0 holds a valid superblock with clean.

On any error sector 0 is unchanged.

Note

Not thread-safe; shares the store staging buffer.

Since

0.1.0

Definition at line 175 of file ra8_cache_store_mount.c.

References ra8_cs_super_t::crc, ra8_cache_store_t::data_capacity, ra8_cs_super_t::entry_count, ra8_cache_store_entry_t::flags, ra8_cache_store_t::index, ra8_cache_store_t::index_cap, k_ra8_cache_store_flag_in_use, k_ra8_cache_store_sector_bytes, k_ra8_cs_format_version, k_ra8_cs_super_magic, ra8_cache_store_t::live_sectors, ra8_cache_store_t::log_start, ra8_cache_store_t::logical_sectors, memcpy(), memset(), ra8_cache_store_t::next_seq, priv_cache_store_crc32(), priv_cache_store_sector_write(), RA8_CHECK_NULL_PTR, RA8_PRIV, s_tag, and ra8_cache_store_t::staging.

Referenced by internal_checkpoint(), internal_mark_dirty(), and internal_open_levelx().