Module-private seams shared by the #208 sweep translation units. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_vsource.h"
#include "sweep_block.h"

Include dependency graph for sweep_block_internal.h:

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

Data Structures
struct	cbs_backend
struct	cbs_row_t
	One measured (backend, leg, block size) result row. More...
struct	cbs_meter_t
	Counting shim around an ra8_vsource_read_fn. More...
struct	cbs_payload_state_t
	Serializable pseudo-text generator cursor. More...
struct	cbs_payload_t
	Resettable exact pseudo-text byte source with bounded checkpoints. More...

Typedefs
typedef struct cbs_backend	cbs_backend_t

Enumerations
enum	cbs_dim_t : uint32_t { k_cbs_blob_bytes = 8388608U , k_cbs_cache_bytes = 1048576U , k_cbs_req_bytes = 256U , k_cbs_seq_passes = 4U , k_cbs_hot_reads = 1048576U , k_cbs_bucket_min = 16U , k_cbs_default_chunk = 65536U , k_cbs_knee_pct = 90U , k_cbs_words_per_dot = 11U , k_cbs_kib = 1024U , k_cbs_ns_per_us = 1000U , k_cbs_ns_per_s = 1000000000U , k_cbs_max_rows = 24U }
	Workload geometry and fixed sweep parameters. More...

Functions
size_t	priv_payload_workspace_required (void)
	Return exact workspace bytes required by the pseudo-text source index.
int	priv_payload_init (cbs_payload_t payload, void workspace, size_t capacity)
	Build the payload source index into caller-owned storage.
ra8_err_t	priv_payload_read (void ctx, uint64_t offset, uint8_t buffer, uint32_t length)
	Read exact historical pseudo-text bytes at any bounded offset.
uint64_t	priv_now_ns (void)
	Monotonic wall-clock in nanoseconds.
ra8_err_t	priv_meter_read (void ctx, uint64_t offset, uint8_t buf, uint32_t len)
	ra8_vsource_read_fn forwarding through a cbs_meter_t.
cbs_backend_t *	priv_backends (uint32_t *out_count)
	Expose the registered sweep backends (the seam the HW leg extends).
int	priv_print_row (cb_sink_t sink, const cbs_row_t r)
	Print one machine-parseable result row (sweep-block key=value ...).
int	priv_print_seq_table (cb_sink_t sink, const cbs_row_t rows, uint32_t nrows, const char be, const uint32_t blocks, uint32_t nblocks)
	Print one backend's sequential-scan summary table (leg a).
int	priv_print_hot_table (cb_sink_t sink, const cbs_row_t rows, uint32_t nrows, const char be, const uint32_t blocks, uint32_t nblocks)
	Print one backend's same-block re-read summary table (leg b).
int	priv_print_crossover (cb_sink_t sink, const cbs_row_t rows, uint32_t nrows, const uint32_t *blocks, uint32_t nblocks)
	Name the measured crossover and print the chunk-size recommendation.

Detailed Description

Module-private seams shared by the #208 sweep translation units.

The --sweep-block mode is split across three translation units to keep each under the maintainability line cap:

src/sweep_block.c – the sweep core: the real ::ra8_vmem cache bundle, the timed drive loop, per-(backend, size) orchestration, and the cb_sweep_block() entry point.
src/sweep_block_backends.c – the two in-tree cbs_backend_t implementations (mem and rbkc-z9), the byte-counting meter shim, the deterministic text filler, and the wall-clock helper.
src/sweep_block_report.c – the machine-parseable row printer and the human summary (per-leg tables + the measured knee / crossover verdict).

This header carries the sweep geometry constants, the backend DIP seam (cbs_backend_t), the result-row type (cbs_row_t), the counting meter (cbs_meter_t), and the RA8_PRIV declarations of every helper shared across those translation units. Nothing here is part of the tool's public surface: src/cache_bench.c consumes only inc/sweep_block.h.

[Ring 7 / Tooling] {World: NS}

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

Since: 0.1.0

Definition in file sweep_block_internal.h.

Typedef Documentation

◆ cbs_backend_t

typedef struct cbs_backend cbs_backend_t

Definition at line 85 of file sweep_block_internal.h.

Enumeration Type Documentation

◆ cbs_dim_t

enum cbs_dim_t : uint32_t

Workload geometry and fixed sweep parameters.

The payload is a multiple of every swept block size and of the reader request grain, so no leg ever sees a partial-block edge; the cache byte budget is held constant across sizes (same RAM spend, different frame counts) for an honest comparison.

Since: 0.1.0

Enumerator
k_cbs_blob_bytes	8 MiB payload (2^23; all sizes divide it).
k_cbs_cache_bytes	1 MiB resident cache budget (constant).
k_cbs_req_bytes	Reader request grain (divides every size).
k_cbs_seq_passes	Whole-object passes in the seq leg.
k_cbs_hot_reads	Accesses in the same-block re-read leg.
k_cbs_bucket_min	Minimum hash-bucket count for tiny caches.
k_cbs_default_chunk	#204 .rabook chunk-size default.
k_cbs_knee_pct	%% of peak throughput that names the knee.
k_cbs_words_per_dot	Words per sentence in the text filler.
k_cbs_kib	Bytes per KiB (block-size labels).
k_cbs_ns_per_us	Nanoseconds per microsecond.
k_cbs_ns_per_s	Nanoseconds per second.
k_cbs_max_rows	2 backends x 6 sizes x 2 legs.

Definition at line 48 of file sweep_block_internal.h.

Function Documentation

◆ priv_backends()

cbs_backend_t * priv_backends ( uint32_t * out_count )

Expose the registered sweep backends (the seam the HW leg extends).

Returns the module's backend registry: mem first (the harness floor), then rbkc-z9. Entries are mutable because setup binds read/read_ctx/backing_bytes in place per (blob, size) pair.

Parameters

[out] out_count Receives the number of registered backends.

Returns: cbs_backend_t* The registry array (never NULL).

Precondition: out_count is non-NULL.

Postcondition: *out_count is the registry length (>= 2).

Note: Not thread-safe (the registry is written in place by setup).

Since: 0.1.0

Definition at line 589 of file sweep_block_backends.c.

References s_cbs_backends.

Referenced by cb_sweep_block().

◆ priv_meter_read()

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

ra8_vsource_read_fn forwarding through a cbs_meter_t.

Counts one call plus len bytes against the meter, then forwards to the wrapped reader. Registered at the vsource seam by the sweep core (counting storage commands == cache misses) and under the RBKC container file (counting raw compressed traffic).

Parameters

[in]	ctx	The cbs_meter_t to charge (as void*).
[in]	offset	Byte offset forwarded to the wrapped reader.
[out]	buf	Destination buffer forwarded to the wrapped reader.
[in]	len	Bytes requested.

Returns: ra8_err_t Forwarded result of the wrapped reader.

Return values

k_ra8_err_null_ptr ctx or its wrapped reader is NULL.

Precondition: ctx points at a cbs_meter_t with a live inner reader.; buf covers len writable bytes for the wrapped reader.

Postcondition: On success, calls grew by one and bytes by len.; The wrapped reader's result is returned unchanged to the caller.

Note: Not thread-safe (unsynchronized counters; single-threaded tool).

Since: 0.1.0

Definition at line 62 of file sweep_block_backends.c.

References cbs_meter_t::bytes, cbs_meter_t::calls, cbs_meter_t::inner, cbs_meter_t::inner_ctx, and k_ra8_err_null_ptr.

Referenced by internal_cache_open().

◆ priv_now_ns()

uint64_t priv_now_ns ( void )

Monotonic wall-clock in nanoseconds.

Reads CLOCK_MONOTONIC and folds seconds + nanoseconds into one 64-bit nanosecond count; the sweep core brackets each timed leg with two calls and reports the difference.

Returns: uint64_t Monotonic time in nanoseconds since an arbitrary epoch.

Return values

other The current CLOCK_MONOTONIC reading folded to nanoseconds.

Precondition: The host provides CLOCK_MONOTONIC (POSIX; true on macOS + Linux).; No argument is required; the call takes none.

Postcondition: The returned value never decreases across calls in one process.; No argument or global state is read or written.

Note: Thread-safe (stateless syscall wrapper).

Since: 0.1.0

Definition at line 54 of file sweep_block_backends.c.

References k_cbs_ns_per_s.

Referenced by internal_drive().

◆ priv_payload_init()

int priv_payload_init	(	cbs_payload_t *	payload,
		void *	workspace,
		size_t	capacity )

Build the payload source index into caller-owned storage.

Serializes deterministic generator state at each bounded seek span and initializes the sequential cursor at offset zero.

Parameters

[out]	payload	Payload binding to initialize.
[in,out]	workspace	Aligned caller-owned checkpoint storage.
[in]	capacity	Supplied workspace byte count.

Returns: Zero on success, otherwise one.

Return values

0	`payload` is ready for exact reads.
1	A binding, alignment, or capacity check failed.

Precondition: payload and workspace are non-NULL.; workspace is aligned for cbs_payload_state_t.

Postcondition: On success, every checkpoint is initialized deterministically.; Workspace ownership remains with the caller.

Note: Initialization is bounded by fixed payload geometry.

Since: 0.1.0

Definition at line 132 of file sweep_block_payload.c.

References internal_payload_next(), k_cbs_no_word, k_cbs_payload_checkpoint_bytes, k_cbs_payload_seed, and priv_payload_workspace_required().

Referenced by cb_sweep_block().

◆ priv_payload_read()

ra8_err_t priv_payload_read	(	void *	ctx,
		uint64_t	offset,
		uint8_t *	buffer,
		uint32_t	length )

Read exact historical pseudo-text bytes at any bounded offset.

Restores the nearest checkpoint when needed, regenerates at most one checkpoint span, and caches the resulting sequential cursor.

Parameters

[in,out]	ctx	Bound cbs_payload_t.
[in]	offset	Logical payload offset.
[out]	buffer	Destination buffer.
[in]	length	Exact byte count.

Returns: Repository error code.

Return values

k_ra8_ok	The complete range was generated.
k_ra8_err_null_ptr	A required binding is NULL.
k_ra8_err_out_of_range	The requested range exceeds the fixed payload.

Precondition: buffer is writable for length bytes.; ctx was initialized by priv_payload_init.

Postcondition: On success, buffer contains the deterministic historical bytes.; The cached cursor names the end of the completed read.

Note: Distinct payload bindings may be read independently.

Since: 0.1.0

Definition at line 158 of file sweep_block_payload.c.

References cbs_payload_t::checkpoint_count, cbs_payload_t::checkpoints, cbs_payload_t::cursor_offset, cbs_payload_t::cursor_state, internal_payload_next(), k_cbs_blob_bytes, k_cbs_payload_checkpoint_bytes, k_ra8_err_null_ptr, k_ra8_err_out_of_range, and k_ra8_ok.

Referenced by internal_execute().

◆ priv_payload_workspace_required()

size_t priv_payload_workspace_required ( void )

Return exact workspace bytes required by the pseudo-text source index.

Sizes one serialized generator checkpoint per bounded regeneration span.

Returns: Exact checkpoint-index byte count.

Return values

other Non-zero fixed payload-index requirement.

Precondition: Fixed payload and checkpoint geometries are internally consistent.; sizeof(cbs_payload_state_t) fits in size_t multiplication.

Postcondition: The result covers all checkpoints including offset zero.; No storage or global state is modified.

Note: Thread-safe: this is fixed-geometry arithmetic.

Since: 0.1.0

Definition at line 125 of file sweep_block_payload.c.

References k_cbs_blob_bytes, and k_cbs_payload_checkpoint_bytes.

Referenced by cb_sweep_block(), and priv_payload_init().

◆ priv_print_crossover()

int priv_print_crossover	(	cb_sink_t *	sink,
		const cbs_row_t *	rows,
		uint32_t	nrows,
		const uint32_t *	blocks,
		uint32_t	nblocks )

Name the measured crossover and print the chunk-size recommendation.

The knee is the smallest block size whose sequential throughput on the chunked (rbkc-z9) backend reaches k_cbs_knee_pct percent of the peak across all sizes – i.e. where per-request overhead has stopped dominating (Memory Systems Ch 23.2.1). The verdict names the knee against the current 64 KiB .rabook default and states the host-measurement caveat for the SD hardware leg.

Parameters

[in]	rows	All finished rows.
[in]	nrows	Number of rows.
[in]	blocks	The swept sizes, ascending.
[in]	nblocks	Number of swept sizes.
[in,out]	sink	Report destination.

Returns: 0 on success, or 1 when the sink rejects output.

Return values

0	The crossover summary was published.
1	The sink rejected a summary fragment.

Precondition: rbkc-z9 seq rows exist (the function prints nothing useful otherwise).; blocks is sorted ascending.

Postcondition: The crossover paragraph was written to sink.; No row data is modified.

Note: Not thread-safe: writes sink.

Since: 0.1.0

Name the measured crossover and print the chunk-size recommendation.

Definition at line 370 of file sweep_block_report.c.

References cb_sink_format(), internal_block_label(), internal_find_knee(), internal_print_verdict(), k_cb_io_ok, k_cbs_default_chunk, k_cbs_knee_pct, cbs_knee_t::knee_block, cbs_knee_t::knee_mibs, cbs_knee_t::peak_block, cbs_knee_t::peak_mibs, and s_cbs_pct_f.

Referenced by internal_summary().

◆ priv_print_hot_table()

int priv_print_hot_table	(	cb_sink_t *	sink,
		const cbs_row_t *	rows,
		uint32_t	nrows,
		const char *	be,
		const uint32_t *	blocks,
		uint32_t	nblocks )

Print one backend's same-block re-read summary table (leg b).

Shows the pure cache-hit path per block size; a flat ns/read column is the expected result (hit cost independent of the block size), with exactly one cold miss per row.

Parameters

[in]	rows	All finished rows.
[in]	nrows	Number of rows.
[in]	be	Backend name to summarise.
[in]	blocks	The swept sizes, ascending.
[in]	nblocks	Number of swept sizes.
[in,out]	sink	Report destination.

Returns: 0 on success, or 1 when the sink rejects output.

Return values

0	The complete hot-read table was published.
1	The sink rejected a table fragment.

Precondition: Hot rows for be exist at each size (missing rows are skipped).; sink is bound and writable.

Postcondition: One markdown table for be was printed.; No row data is modified.

Note: Not thread-safe: writes sink.

Since: 0.1.0

Print one backend's same-block re-read summary table (leg b).

Definition at line 204 of file sweep_block_report.c.

References cb_sink_format(), cbs_row_t::hits, internal_block_label(), internal_find_row(), k_cb_io_ok, cbs_row_t::misses, cbs_row_t::reads, and cbs_row_t::wall_ns.

Referenced by internal_summary().

◆ priv_print_row()

int priv_print_row	(	cb_sink_t *	sink,
		const cbs_row_t *	r )

Print one machine-parseable result row (sweep-block key=value ...).

Emits every counter of r on one line plus derived MiB/s and ns/read, clamping a zero wall time to 1 ns so the derived rates never divide by zero. Rows with zero reads print nothing.

Parameters

[in]	r	Finished row to print (NULL is tolerated as a no-op).
[in,out]	sink	Report destination.

Returns: 0 on success, or 1 when the sink rejects the row.

Return values

0	The row was empty or published completely.
1	The sink rejected a report fragment.

Precondition: sink is bound and writable.; r, when non-NULL, is a finished row (its counters are final).

Postcondition: One sweep-block ... line was printed for a non-empty row.; No row data is modified (pure reader).

Note: Not thread-safe: writes sink.

Since: 0.1.0

Print one machine-parseable result row (sweep-block key=value ...).

Definition at line 37 of file sweep_block_report.c.

References cbs_row_t::backend, cbs_row_t::backing_bytes, cbs_row_t::be_bytes, cbs_row_t::be_calls, cbs_row_t::block_bytes, cb_sink_format(), cbs_row_t::evictions, cbs_row_t::frames, cbs_row_t::hits, k_cb_io_ok, k_cbs_ns_per_us, k_cbs_req_bytes, cbs_row_t::leg, cbs_row_t::misses, cbs_row_t::reads, s_cbs_mib_f, s_cbs_ns_per_s_f, cbs_row_t::src_bytes, and cbs_row_t::wall_ns.

Referenced by internal_run_block().

◆ priv_print_seq_table()

int priv_print_seq_table	(	cb_sink_t *	sink,
		const cbs_row_t *	rows,
		uint32_t	nrows,
		const char *	be,
		const uint32_t *	blocks,
		uint32_t	nblocks )

Print one backend's sequential-scan summary table (leg a).

Derives an estimated per-miss fill cost by subtracting the independently measured hit-path cost (the hot leg's ns/read at the same size) from the sequential wall time and dividing the remainder across the misses – the Ch 23.2 method of separating per-request overhead from streaming cost.

Parameters

[in]	rows	All finished rows.
[in]	nrows	Number of rows.
[in]	be	Backend name to summarise.
[in]	blocks	The swept sizes, ascending.
[in]	nblocks	Number of swept sizes.
[in,out]	sink	Report destination.

Returns: 0 on success, or 1 when the sink rejects output.

Return values

0	The complete sequential table was published.
1	The sink rejected a table fragment.

Precondition: Rows for be exist for both legs at each size (partial rows skip).; sink is bound and writable.

Postcondition: One markdown table for be was printed.; No row data is modified.

Note: Not thread-safe: writes sink.

Since: 0.1.0

Print one backend's sequential-scan summary table (leg a).

Definition at line 155 of file sweep_block_report.c.

References cbs_row_t::backing_bytes, cbs_row_t::be_calls, cb_sink_format(), cbs_row_t::frames, internal_block_label(), internal_find_row(), internal_row_mibs(), k_cb_io_ok, cbs_row_t::misses, cbs_row_t::reads, s_cbs_mib_f, s_cbs_ns_per_us_f, cbs_row_t::src_bytes, and cbs_row_t::wall_ns.

Referenced by internal_summary().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ cbs_backend_t

Enumeration Type Documentation

◆ cbs_dim_t

Function Documentation

◆ priv_backends()

◆ priv_meter_read()

◆ priv_now_ns()

◆ priv_payload_init()

◆ priv_payload_read()

◆ priv_payload_workspace_required()

◆ priv_print_crossover()

◆ priv_print_hot_table()

◆ priv_print_row()

◆ priv_print_seq_table()