sweep_block.h File Reference

#208 block/frame-size sweep: the byte-size axis the capacity sweep never touches, so the chunked .rabook chunk size and the ra8_vmem frame_bytes constant are picked from measurement, not intuition. More...

#include <stddef.h>
#include <stdint.h>
#include "cache_bench_io.h"

Include dependency graph for sweep_block.h:

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

Go to the source code of this file.

Data Structures
struct	cb_sweep_config_t
	Caller-owned bindings for the block sweep. More...

Functions
int	cb_sweep_block (cb_sweep_config_t *config)
	Run the #208 block/frame-size sweep and print the report.

Detailed Description

#208 block/frame-size sweep: the byte-size axis the capacity sweep never touches, so the chunked .rabook chunk size and the ra8_vmem frame_bytes constant are picked from measurement, not intuition.

cache_bench's default mode sweeps cache CAPACITY (frames) only; every frame is an abstract (object, page) key with no size in bytes. This mode sweeps the missing axis – the block/frame size itself – using the methodology of Memory Systems Ch 23.2.1/23.2.2:

(a) Sequential whole-object scan at each block size, which isolates where per-request overhead stops dominating and sustained streaming throughput takes over (the knee names the chunk size). (b) Repeated same-block reads, which isolate the pure cache-hit path and show it is independent of the block size.

Unlike the capacity sweep (a re-modelled policy harness), this mode drives the REAL firmware stack: ::ra8_vmem (SLRU page cache, Layer 2) over ::ra8_vsource (Layer 1) with the swept size as frame_bytes, fed through the cbs_backend_t seam (declared in inc/sweep_block_internal.h, implemented in src/sweep_block_backends.c). Two synthetic host backends ship in-tree:

• mem – plain memcpy from a resident blob (the harness floor).
• rbkc-z9 – a real "RBKC" chunked .rabook container built in memory with zlib level-9 streams (mirroring tools/epub_compile), read through book_chunked_read, so every miss pays a genuine staged read + tinfl inflate of one chunk. This is the decompress-per-miss number that picks the chunk size.

The SD-over-SPI hardware leg of #208 plugs in later as a third cbs_backend_t whose read issues real card reads; nothing in the sweep core changes.

[Ring 7 / Tooling] {World: NS}

Copyright

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

Since

0.1.0

Definition in file sweep_block.h.

Function Documentation

cb_sweep_block()

int cb_sweep_block

(

cb_sweep_config_t *

config

)

Run the #208 block/frame-size sweep and print the report.

For every registered backend and every swept block size (512 B .. 256 KiB), builds the backing, stands up a real ::ra8_vmem cache with frame_bytes equal to the swept size under a constant byte budget, and drives legs (a) sequential whole-object scan and (b) same-block re-read. Prints one machine-parseable sweep-block ... line per row, then a human summary with the measured knee and a chunk-size recommendation versus the current 64 KiB .rabook default (#204). Every returned byte is verified against the source blob, so a lying backend fails the run instead of skewing it.

Parameters

[in,out]

config

Caller-owned cache, workspace, scratch, and sinks.

Returns

int Process-style status.

Return values

0	Sweep completed; every row verified byte-identical.
1	Capacity, backend setup, I/O, or data-verification failure.

Precondition

config supplies exactly 1 MiB of aligned cache backing, bounded metadata workspace, a scratch transaction, and output/error sinks.

The scratch callbacks complete exact positional transfers.

Postcondition

On 0, one row per (backend, leg, size) was printed plus the summary.

No storage ownership changes; scratch and workspace remain caller-owned.

Note

Not thread-safe (single-threaded host tool; static backend state).

See also

cbs_backend_t The seam a future SD-over-SPI hardware leg implements.

Since

0.1.0

Definition at line 608 of file sweep_block.c.

References cb_sweep_config_t::cache_capacity, cb_sweep_config_t::cache_required, cb_sink_format(), cb_sweep_config_t::error, internal_align_size(), internal_execute(), internal_summary(), k_cb_io_ok, k_cbs_blob_bytes, k_cbs_cache_bytes, k_cbs_hot_reads, k_cbs_max_rows, k_cbs_req_bytes, k_cbs_seq_passes, cb_sweep_config_t::output, priv_backends(), priv_payload_init(), priv_payload_workspace_required(), cb_sweep_config_t::scratch, cb_sweep_config_t::workspace, cb_sweep_config_t::workspace_capacity, cb_sweep_config_t::workspace_floor, cb_sweep_config_t::workspace_required, and cb_sweep_config_t::workspace_used.

Referenced by internal_run_sweep().