Demand-paged .rabook backing: chunk reader + page cache + source bind. More...

#include <string.h>
#include "book_chunked.h"
#include "ra8_check.h"
#include "ra8_vmem.h"
#include "ra8_vsource.h"
#include "sh_app.h"

Include dependency graph for sh_paged.c:

Data Structures
struct	sh_paged_mram_t
	Memory-mapped container backing (baked books). More...

Enumerations
enum	sh_paged_dim_t : uint32_t { k_shp_frame_bytes = 64U * 1024U , k_shp_frame_count = 384U , k_shp_bucket_count = 512U , k_shp_table_entries = 1025U , k_shp_staging_bytes = 72U * 1024U }
	Paged-stack buffer budgets. More...

Functions
static ra8_err_t	sh_paged_mram_read (void ctx, uint64_t offset, uint8_t buf, uint32_t len)
	ra8_vsource_read_fn over a memory-mapped (MRAM) container blob.
static bool	sh_paged_extent_ok (uint32_t off, uint32_t count, uint32_t elem, uint32_t total)
	Does the header extent [off, off + count*elem) fit inside `total`?
static bool	sh_paged_hdr_ok (const book_header_t *hdr, uint64_t inflated_total)
	Validate the paged source's header copy (no whole-blob CRC).
static bool	sh_paged_bind (void)
	Register the bound chunk reader, init the cache, bind g_sh.book_src.
bool	sh_paged_open (ra8_vsource_read_fn file_read, void *file_ctx, uint64_t file_len)
	Open a chunked .rabook container as the demand-paged book source.
bool	sh_paged_open_mram (const uint8_t *blob, uint32_t blob_len)
	Open a memory-mapped (baked MRAM) RBKC container as the paged source.
void	sh_paged_close (void)
	Unbind the paged book source and release its SD backing (idempotent).

Variables
static uint8_t	s_shp_frames [k_shp_frame_count *k_shp_frame_bytes]
	SDRAM page-frame pool (the old inflate-scratch budget, repurposed).
static uint8_t	s_shp_staging [k_shp_staging_bytes]
	SDRAM staging buffer for one compressed chunk's zlib stream.
static uint64_t	s_shp_table [k_shp_table_entries]
	Resident chunk table (chunk_count + 1 stream offsets).
static ra8_vmem_frame_t	s_shp_meta [k_shp_frame_count]
	Per-frame cache metadata (parallel to the frame pool).
static ra8_vmem_key_t	s_shp_keys [k_shp_frame_count]
	Per-frame cache key storage (parallel to the frame pool).
static int32_t	s_shp_buckets [k_shp_bucket_count]
	Cache hash-bucket heads.
static book_chunked_t	s_shp_rd
	The open book's chunk reader (unbound when no rabook is open).
static ra8_vsource_obj_t	s_shp_obj
	Single-slot object registry: object 0 is the open book.
static ra8_vsource_t	s_shp_vs
	Source registry fronting s_shp_obj.
static ra8_vmem_t	s_shp_vm
	The page cache the bound book_src_t reads through.
static sh_paged_mram_t	s_shp_mram
	Backing context while an MRAM (baked) book is open.
static const char *const	s_shp_tag = "sh_paged"
	Log tag for paged-open diagnostics.

Detailed Description

Demand-paged .rabook backing: chunk reader + page cache + source bind.

The #204/#205 open path. Every .rabook book – baked MRAM blob or SD file – is opened through the chunked "RBKC" reader (book_chunked) and bound as an book_src_paged source over an ::ra8_vmem page cache. There is deliberately NO resident/paged size threshold: a small book simply never evicts anything from the generously-sized frame pool (so it behaves like the old resident fast path), while a book far larger than the pool evicts normally through the same code. One code path, no threshold tuning.

This module owns every static buffer the paged stack needs:

the SDRAM frame pool (the budget the old whole-book inflate scratch used),
the compressed-chunk staging buffer,
the resident chunk table, the cache metadata + hash buckets,
the single-slot ::ra8_vsource registry and the ::ra8_vmem cache.

The container's chunk_bytes is validated at open to equal the cache's frame_bytes (one chunk == one frame == one inflate; the contract book_chunked_read relies on).

[Ring 6 / App] {World: NS}

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

Since: 0.1.0

Definition in file sh_paged.c.

Enumeration Type Documentation

◆ sh_paged_dim_t

enum sh_paged_dim_t : uint32_t

Paged-stack buffer budgets.

k_shp_frame_bytes MUST equal the RBKC chunk_bytes the book compiler emits (tools/epub_compile --chunk-bytes, default 64 KiB); a container compiled with any other chunk size is rejected at open. The frame pool repurposes the 24 MiB SDRAM budget the retired whole-book inflate scratch (s_scratch in main.c) used to hold: 384 frames x 64 KiB = 24 MiB. The chunk-table budget caps the largest openable book at 1024 chunks = 64 MiB inflated (1025 entries; a bigger book fails book_chunked_open honestly). The staging buffer must cover the largest compressed chunk; 72 KiB exceeds both zlib's compressBound(64 KiB) (~65.6 KiB) and miniz's more conservative mz_compressBound(64 KiB) (~70.6 KiB).

Since: 0.1.0

Enumerator
k_shp_frame_bytes	ra8_vmem frame size == container chunk_bytes.
k_shp_frame_count	384 x 64 KiB = 24 MiB SDRAM frame pool.
k_shp_bucket_count	Cache hash buckets (~1.3x frames, pow2).
k_shp_table_entries	chunk_count+1 budget: 64 MiB inflated cap.
k_shp_staging_bytes	>= compressBound(chunk) for zlib and miniz.

Definition at line 55 of file sh_paged.c.

Function Documentation

◆ sh_paged_bind()

bool sh_paged_bind ( void )

static

Register the bound chunk reader, init the cache, bind g_sh.book_src.

Definition at line 183 of file sh_paged.c.

References book_chunked_read(), book_src_paged(), g_sh, k_ra8_ok, k_shp_bucket_count, k_shp_frame_bytes, k_shp_frame_count, ra8_vmem_init(), ra8_vsource_add_paged(), ra8_vsource_init(), ra8_vsource_loader(), s_shp_buckets, s_shp_frames, s_shp_keys, s_shp_meta, s_shp_obj, s_shp_rd, s_shp_vm, s_shp_vs, and sh_paged_hdr_ok().

Referenced by sh_paged_open().

◆ sh_paged_close()

void sh_paged_close ( void )

Unbind the paged book source and release its SD backing (idempotent).

Definition at line 279 of file sh_paged.c.

References g_sh, s_shp_mram, s_shp_rd, and sh_sd_book_close().

Referenced by sh_book_open(), and sh_paged_open().

◆ sh_paged_extent_ok()

bool sh_paged_extent_ok	(	uint32_t	off,
		uint32_t	count,
		uint32_t	elem,
		uint32_t	total )

static

Does the header extent [off, off + count*elem) fit inside total?

Definition at line 124 of file sh_paged.c.

Referenced by sh_paged_hdr_ok().

◆ sh_paged_hdr_ok()

bool sh_paged_hdr_ok	(	const book_header_t *	hdr,
		uint64_t	inflated_total )

static

Validate the paged source's header copy (no whole-blob CRC).

Checks the magic, format version, that the header's total_size equals the container's inflated total, and that every table/pool extent lies inside the blob – the same shape checks book_validate() runs, minus its body CRC-32. Verifying that CRC here would fault every chunk in (a full-book read), which is exactly what always-paging avoids, so it is honestly NOT checked in this mode: integrity is instead carried by the RBKC geometry checks at open, the zlib Adler-32 that sh_inflate/tinfl verifies on EVERY chunk as it faults in, and the exact inflated-span check in book_chunked_read.

< Extent start offset.

< Element count (or bytes).

< Element size (1 for pools).

Definition at line 146 of file sh_paged.c.

References book_header_t::attr_count, book_header_t::attr_off, book_header_t::chapter_count, book_header_t::chapter_off, book_header_t::format_version, book_header_t::image_count, book_header_t::image_off, book_header_t::image_pool_off, book_header_t::image_pool_size, k_book_format_version, book_header_t::magic, memcmp(), book_header_t::node_count, book_header_t::node_off, sh_paged_extent_ok(), book_header_t::string_off, book_header_t::string_size, book_header_t::stylesheet_count, book_header_t::stylesheet_off, and book_header_t::total_size.

Referenced by sh_paged_bind().

◆ sh_paged_mram_read()

ra8_err_t sh_paged_mram_read	(	void *	ctx,
		uint64_t	offset,
		uint8_t *	buf,
		uint32_t	len )

static

ra8_vsource_read_fn over a memory-mapped (MRAM) container blob.

Definition at line 111 of file sh_paged.c.

References sh_paged_mram_t::data, k_ra8_err_out_of_range, k_ra8_ok, sh_paged_mram_t::len, memcpy(), RA8_CHECK_NULL_PTR, and s_shp_tag.

Referenced by sh_paged_open_mram().

◆ sh_paged_open()

bool sh_paged_open	(	ra8_vsource_read_fn	file_read,
		void *	file_ctx,
		uint64_t	file_len )

Open a chunked .rabook container as the demand-paged book source.

Binds the RBKC chunk reader over file_read, registers it as a paged ::ra8_vsource object, (re)initialises the ra8_vmem frame cache, and binds g_sh.book_src in paged mode. Always paged – there is deliberately no resident/paged size threshold (#205).

Parameters

[in]	file_read	Byte reader over the container file bytes.
[in]	file_ctx	Context for `file_read`.
[in]	file_len	Container file length in bytes.

Returns: true on success; false leaves no book bound (and the SD backing, if any, closed).

Precondition: Any previously open book was torn down via sh_paged_close (the backing file_read reads from must be live when this is called).

Since: 0.1.0

Definition at line 223 of file sh_paged.c.

References book_chunked_open(), g_sh, k_ra8_ok, k_shp_frame_bytes, k_shp_staging_bytes, k_shp_table_entries, s_shp_rd, s_shp_staging, s_shp_table, sh_inflate(), sh_paged_bind(), and sh_paged_close().

Referenced by sh_book_open_rabook(), and sh_paged_open_mram().

◆ sh_paged_open_mram()

bool sh_paged_open_mram	(	const uint8_t *	blob,
		uint32_t	blob_len )

Open a memory-mapped (baked MRAM) RBKC container as the paged source.

The file-read callback is a bounds-checked memcpy from blob; the container bytes are already addressable, but chunks still inflate on demand into cache frames – same path as SD books.

Parameters

[in]	blob	First container byte (MRAM).
[in]	blob_len	Container length in bytes.

Returns: true on success; false leaves no book bound.

Since: 0.1.0

static

Source registry fronting s_shp_obj.

Definition at line 89 of file sh_paged.c.

Referenced by sh_paged_bind().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ sh_paged_dim_t

Function Documentation

◆ sh_paged_bind()

◆ sh_paged_close()

◆ sh_paged_extent_ok()

◆ sh_paged_hdr_ok()

◆ sh_paged_mram_read()

◆ sh_paged_open()

◆ sh_paged_open_mram()

Variable Documentation

◆ s_shp_buckets

◆ s_shp_frames

◆ s_shp_keys

◆ s_shp_meta

◆ s_shp_mram

◆ s_shp_obj

◆ s_shp_rd

◆ s_shp_staging

◆ s_shp_table

◆ s_shp_tag

◆ s_shp_vm

◆ s_shp_vs