#147 benchmark front end: swept-capacity report, mode dispatch, main. More...

#include <string.h>
#include "cache_bench.h"
#include "cache_bench_host.h"
#include "cache_bench_io.h"
#include "ra8_attributes.h"
#include "sweep_block.h"
#include "trace.h"

Include dependency graph for cache_bench_report.c:

Data Structures
struct	cb_sweep_backing_t

Enumerations
enum	cb_bench_size_t : uint32_t { k_cb_size_64 = 64U , k_cb_size_128 = 128U , k_cb_size_256 = 256U , k_cb_size_512 = 512U , k_cb_size_1024 = 1024U , k_cb_size_2048 = 2048U }
	Swept cache capacities (in frames) used on the RAM-budget axis. More...
enum	cb_mid_cap_t : uint32_t { k_cb_mid_cap = 256U }
	Representative mid-budget capacity used in the summary table. More...
enum	cb_pct_scale_t : uint32_t { k_cb_pct_scale = 100U }
	Full scale used when computing a hit-rate percentage (integer form). More...
enum	cb_loaded_cap_t : uint8_t { k_cb_max_loaded = 8U , k_cb_output_prefix_bytes = 9U }
	Capacity of the extra captured-trace table filled from argv. More...
enum	cb_composition_limit_t : size_t { k_cb_composition_workspace_bytes = 131072U }
enum	cb_sweep_canary_t : uint64_t { k_cb_sweep_canary_before = 0x0CACEB00C0FFEE11ULL , k_cb_sweep_canary_after = 0xA11CE55E0BADC0DEULL }

Functions
static int	internal_report_trace_header (const cb_trace_t tr, cb_sink_t sink, uint32_t nsz)
	Write the per-trace table header: title line, column heads, rule row.
static int	internal_report_trace_row (const cache_policy_t policy, const cb_trace_t tr, cb_workspace_t workspace, cb_sink_t sink, uint32_t nsz)
	Write one policy's hit-rate row across every swept cache size.
static int	internal_report_trace (const cb_trace_t tr, cb_workspace_t workspace, cb_sink_t *sink)
	Print the per-trace hit-rate matrix (policies x cache sizes).
static int	internal_report_summary (const cb_trace_t traces, uint32_t ntr, cb_workspace_t workspace, cb_sink_t *sink)
	Print the cross-workload summary (WCET + metadata + mean hit rate).
static uint32_t	internal_load_argv_traces (int argc, char *argv, cb_trace_t loaded, cb_host_source_t *sources)
	Load the extra captured traces named on the command line.
static const char *	internal_output_path (int argc, char **argv)
	Find the optional report destination in the argument vector.
static int	internal_run_sweep (cb_sink_t output, cb_sink_t error)
	Compose scratch, cache, and workspace bindings and execute block mode.
static int	internal_close_sources (cb_host_source_t *sources, uint32_t count)
	Close every captured source, preserving any close failure.
static int	internal_run_capacity (int argc, char *argv, cb_sink_t output, cb_sink_t *error)
	Execute the capacity report over synthetic and captured traces.
int	main (int argc, char **argv)

Variables
static const double	s_cb_pct_scale_f = 100.0
	Floating-point 100.0 scale factor for hit-rate percentage output.
static const uint32_t	s_cb_sizes []
	Swept cache capacities (frames) – the RAM-budget axis.
static uint8_t	s_cb_composition_workspace [k_cb_composition_workspace_bytes]

Detailed Description

#147 benchmark front end: swept-capacity report, mode dispatch, main.

Drives the replay engine in src/cache_bench.c across the RAM-budget axis and prints the markdown report the #147 decision record quotes: one hit-rate matrix per workload (policies x cache sizes), then a cross-workload summary carrying the worst per-eviction scan depth (a WCET proxy) and each policy's per-frame metadata cost. It also owns the command line – the optional <name>=<path> captured traces, --output=, and the --sweep-block composition root that hands the fixed cache backing and the scratch seam to cb_sweep_block – plus the process entry point. Every engine call goes through the public inc/cache_bench.h surface, which is why the contract test links the engine without this driver.

[Ring 7 / Tooling] {World: NS}

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

Since: 0.1.0

Definition in file cache_bench_report.c.

Enumeration Type Documentation

◆ cb_bench_size_t

enum cb_bench_size_t : uint32_t

Swept cache capacities (in frames) used on the RAM-budget axis.

These are the seven capacity points that the benchmark sweeps over. Each is a power of two chosen to cover the expected SRAM/SDRAM budget range for the RA8D2 page cache (#147 decision record).

Since: 0.1.0

Enumerator
k_cb_size_64	Smallest evaluated capacity (frames).
k_cb_size_128	128-frame sweep point.
k_cb_size_256	Mid-budget representative sweep point.
k_cb_size_512	512-frame sweep point.
k_cb_size_1024	1 K-frame sweep point.
k_cb_size_2048	Largest evaluated capacity (frames).

Definition at line 41 of file cache_bench_report.c.

◆ cb_composition_limit_t

enum cb_composition_limit_t : size_t

Enumerator
k_cb_composition_workspace_bytes	Maximum exact metadata budget.

Definition at line 264 of file cache_bench_report.c.

◆ cb_loaded_cap_t

enum cb_loaded_cap_t : uint8_t

Capacity of the extra captured-trace table filled from argv.

Enumerator
k_cb_max_loaded	Most <name>=<path> traces accepted per run.
k_cb_output_prefix_bytes	Bytes in the literal --output= prefix.

Definition at line 259 of file cache_bench_report.c.

◆ cb_mid_cap_t

enum cb_mid_cap_t : uint32_t

Representative mid-budget capacity used in the summary table.

Enumerator
k_cb_mid_cap	Mid-point capacity (frames) for the summary view.

Definition at line 51 of file cache_bench_report.c.

◆ cb_pct_scale_t

enum cb_pct_scale_t : uint32_t

Full scale used when computing a hit-rate percentage (integer form).

Enumerator
k_cb_pct_scale	Divisor to convert a ratio to a percentage.

Definition at line 56 of file cache_bench_report.c.

◆ cb_sweep_canary_t

enum cb_sweep_canary_t : uint64_t

Enumerator
k_cb_sweep_canary_before	Leading guard value.
k_cb_sweep_canary_after	Trailing guard value.

Definition at line 275 of file cache_bench_report.c.

Function Documentation

◆ internal_close_sources()

int internal_close_sources	(	cb_host_source_t *	sources,
		uint32_t	count )

static

Close every captured source, preserving any close failure.

Attempts all count closes even after one fails so no later borrowed host binding is skipped during teardown.

Parameters

[in,out]	sources	Array of open host source bindings.
[in]	count	Number of entries to close.

Returns: Zero when every close succeeds, otherwise one.

Return values

0	All descriptors closed successfully.
1	At least one close operation failed.

Precondition: sources contains count initialized bindings.; Each binding is closed at most once by this call.

Postcondition: Every entry has been passed to cb_host_source_close.; A failure does not prevent later entries from being attempted.

Note: Not thread-safe with concurrent users of the same descriptors.

Since: 0.1.0

Definition at line 413 of file cache_bench_report.c.

References cb_host_source_close(), and k_cb_io_ok.

Referenced by internal_run_capacity().

◆ internal_load_argv_traces()

uint32_t internal_load_argv_traces	(	int	argc,
		char **	argv,
		cb_trace_t *	loaded,
		cb_host_source_t *	sources )

static

Load the extra captured traces named on the command line.

Each argv of the form <name>=<path> (e.g. hw-reader=t.trace) is split at the first = and loaded via ::cb_trace_load; arguments without = are ignored (they are mode flags). Traces that fail to load (n == 0) are dropped silently, exactly as before.

Parameters

[in]	argc	Argument count from main.
[in]	argv	Argument vector from main (read, never modified).
[out]	loaded	Receives up to k_cb_max_loaded loaded traces.
[out]	sources	Receives the corresponding open host bindings.

Returns: uint32_t Number of traces actually loaded (0 .. k_cb_max_loaded).

Return values

0	No argv held a loadable <name>=<path> pair.
other	The count of successfully loaded traces.

Precondition: loaded has capacity k_cb_max_loaded.; Every argv[a] is NUL-terminated.

Postcondition: Entries loaded[0..return) all have n > 0.; No argument string is modified.

Note: Not thread-safe (the host source bindings are caller-owned).

Since: 0.1.0

Definition at line 302 of file cache_bench_report.c.

References cb_host_source_close(), cb_host_source_open(), cb_trace_bind(), k_cb_io_ok, k_cb_max_loaded, k_cb_output_prefix_bytes, and strncmp().

Referenced by internal_run_capacity().

◆ internal_output_path()

const char * internal_output_path	(	int	argc,
		char **	argv )

static

Find the optional report destination in the argument vector.

Scans arguments after argv[0] and returns the bytes following the first --output= prefix without copying or taking ownership.

Parameters

[in]	argc	Number of entries in `argv`.
[in]	argv	Process argument vector.

Returns: Borrowed destination path, or NULL when the option is absent.

Return values

NULL	No --output= argument was present.
other	Pointer into the matching argument.

Precondition: argv names at least argc readable pointers.; Each inspected argument is NUL-terminated.

Postcondition: argv and its strings are not modified.; Any non-NULL result remains valid while the argument vector lives.

Note: The empty path from a bare --output= is returned for open validation.

Since: 0.1.0

Definition at line 342 of file cache_bench_report.c.

References k_cb_output_prefix_bytes, and strncmp().

Referenced by main().

◆ internal_report_summary()

int internal_report_summary	(	const cb_trace_t *	traces,
		uint32_t	ntr,
		cb_workspace_t *	workspace,
		cb_sink_t *	sink )

static

Print the cross-workload summary (WCET + metadata + mean hit rate).

For each policy, replays every trace at the fixed mid-budget capacity k_cb_mid_cap, then prints the mean hit rate across workloads, the worst per-eviction scan depth seen (a WCET proxy), and the policy's per-frame metadata cost.

Parameters

[in]	traces	Array of `ntr` workloads to average over.
[in]	ntr	Number of traces in `traces` (> 0).
[in,out]	workspace	Reusable exact replay workspace.
[in,out]	sink	Report destination.

Precondition: traces is non-NULL with ntr valid entries.; g_cb_policies / g_cb_policy_count are initialized.

Postcondition: One markdown summary table is written to sink.; No trace or policy state is mutated by the reporting.

Returns: Zero after complete publication, otherwise one.

Return values

0	Every summary row was replayed and accepted by `sink`.
1	A replay or sink operation failed.

Note: Not thread-safe: writes sink and runs replays. Benchmark thread only.

Since: 0.1.0

Definition at line 218 of file cache_bench_report.c.

References cb_result_t::accesses, cb_replay(), cb_sink_format(), g_cb_policies, g_cb_policy_count, cb_result_t::hits, k_cb_io_ok, k_cb_mid_cap, s_cb_pct_scale_f, and cb_result_t::worst_scan.

Referenced by internal_run_capacity().

◆ internal_report_trace()

int internal_report_trace	(	const cb_trace_t *	tr,
		cb_workspace_t *	workspace,
		cb_sink_t *	sink )

static

Print the per-trace hit-rate matrix (policies x cache sizes).

Emits a markdown section for tr: a header naming the workload, then one row per registered policy giving its hit-rate percentage at each swept capacity in s_cb_sizes. Each cell is produced by a full cb_replay of the trace at that size (0.0 when no accesses ran).

Parameters

[in]	tr	Trace to report (name, key stream, footprint).
[in,out]	workspace	Reusable exact replay workspace.
[in,out]	sink	Report destination.

Precondition: tr is non-NULL with valid reset and next operations.; g_cb_policies / g_cb_policy_count are initialized.

Postcondition: One markdown table for tr is written to sink.; tr and every policy are left unmodified (replays are self-contained).

Returns: Zero after complete publication, otherwise one.

Return values

0	Every table fragment was accepted by `sink`.
1	A replay or sink operation failed.

Note: Not thread-safe: writes sink and runs replays. Benchmark thread only.

Since: 0.1.0

Definition at line 183 of file cache_bench_report.c.

References g_cb_policies, g_cb_policy_count, internal_report_trace_header(), internal_report_trace_row(), and s_cb_sizes.

Referenced by internal_run_capacity().

◆ internal_report_trace_header()

int internal_report_trace_header	(	const cb_trace_t *	tr,
		cb_sink_t *	sink,
		uint32_t	nsz )

static

Write the per-trace table header: title line, column heads, rule row.

Emits the "### name (...)" title, the "| policy |" column heading with one column per swept size in s_cb_sizes, and the markdown table rule row beneath it.

Parameters

[in]	tr	Trace being reported (name, access count, footprint).
[in,out]	sink	Report destination.
[in]	nsz	Number of entries in s_cb_sizes to head one column each.

Precondition: tr is non-NULL.; sink is non-NULL and accepts further writes.

Postcondition: The complete three-line markdown header is written to sink.; sink is left ready for one row per policy.

Returns: Zero after the complete header was accepted, otherwise one.

Return values

0	Every header fragment was accepted by `sink`.
1	A sink write failed.

Note: Not thread-safe: writes sink. Benchmark thread only.

Since: 0.1.0

Definition at line 93 of file cache_bench_report.c.

References cb_sink_format(), cb_trace::footprint, k_cb_io_ok, cb_trace::n, cb_trace::name, and s_cb_sizes.

Referenced by internal_report_trace().

◆ internal_report_trace_row()

int internal_report_trace_row	(	const cache_policy_t *	policy,
		const cb_trace_t *	tr,
		cb_workspace_t *	workspace,
		cb_sink_t *	sink,
		uint32_t	nsz )

static

Write one policy's hit-rate row across every swept cache size.

Replays tr once per entry in s_cb_sizes under policy, converting each result to a hit-rate percentage cell (0.0 when no accesses ran), and terminates the row with a newline.

Parameters

[in]	policy	Policy under test for this row.
[in]	tr	Trace to replay (name, key stream, footprint).
[in,out]	workspace	Reusable exact replay workspace.
[in,out]	sink	Report destination.
[in]	nsz	Number of entries in s_cb_sizes to replay and print.

Precondition: policy and tr are non-NULL with valid operations.; sink is non-NULL and accepts further writes.

Postcondition: One complete markdown row for policy is written to sink.; tr and policy are left unmodified (replays are self-contained).

Returns: Zero after the complete row was accepted, otherwise one.

Return values

0	Every cell was replayed and accepted by `sink`.
1	A replay or sink write failed.

Note: Not thread-safe: writes sink and runs replays. Benchmark thread only.

Since: 0.1.0

Definition at line 140 of file cache_bench_report.c.

References cb_result_t::accesses, cb_replay(), cb_sink_format(), cb_result_t::hits, k_cb_io_ok, cache_policy_t::name, s_cb_pct_scale_f, and s_cb_sizes.

Referenced by internal_report_trace().

◆ internal_run_capacity()

int internal_run_capacity	(	int	argc,
		char **	argv,
		cb_sink_t *	output,
		cb_sink_t *	error )

static

Execute the capacity report over synthetic and captured traces.

Binds the fixed synthetic corpus, opens optional captured sources, publishes per-trace and summary tables, and closes every source.

Parameters

[in]	argc	Number of entries in `argv`.
[in,out]	argv	Writable process argument vector.
[in,out]	output	Report destination.
[in,out]	error	Diagnostic destination used for close failures.

Returns: Zero on complete publication and teardown, otherwise one.

Return values

0	All replays, sink writes, and source closes succeeded.
1	A trace, workspace, sink, or close operation failed.

Precondition: argv names argc writable, NUL-terminated argument strings.; output and error are bound writable sinks.

Postcondition: Every successfully opened captured source is closed.; The fixed composition workspace remains owned by this translation unit.

Note: This function mutates accepted <name>=<path> argument separators.

Since: 0.1.0

Definition at line 443 of file cache_bench_report.c.

References cb_workspace_t::capacity, cb_sink_format(), cb_traces_synthetic(), cb_host_source_t::fd, internal_close_sources(), internal_load_argv_traces(), internal_report_summary(), internal_report_trace(), k_cb_io_ok, k_cb_max_loaded, k_cb_synthetic_trace_count, cb_workspace_t::required, and s_cb_composition_workspace.

Referenced by main().

◆ internal_run_sweep()

int internal_run_sweep	(	cb_sink_t *	output,
		cb_sink_t *	error )

static

Compose scratch, cache, and workspace bindings and execute block mode.

Opens one host scratch transaction, guards the fixed cache backing with canaries, runs cb_sweep_block, then closes the scratch seam.

Parameters

[in,out]	output	Sweep report destination.
[in,out]	error	Diagnostic destination.

Returns: Zero on a complete sweep, otherwise one.

Return values

0	The sweep, canary checks, and scratch close all succeeded.
1	Composition, sweep, canary, or close validation failed.

Precondition: output and error are bound writable sinks.; The benchmark runs on its single composition thread.

Postcondition: The scratch descriptor is closed on every successful open path.; The fixed cache backing remains owned by this translation unit.

Note: The two sink bindings may refer to distinct borrowed descriptors.

Since: 0.1.0

Fixed cache backing owned by this translation unit alone.

Definition at line 369 of file cache_bench_report.c.

References cb_sweep_backing_t::after, cb_sweep_backing_t::before, cb_sweep_backing_t::bytes, cb_host_scratch_close(), cb_host_scratch_open(), cb_sweep_block(), k_cb_io_ok, k_cb_sweep_canary_after, k_cb_sweep_canary_before, and s_cb_composition_workspace.

Referenced by main().

◆ main()

int main	(	int	argc,
		char **	argv )

Definition at line 483 of file cache_bench_report.c.

References cb_host_output_abort(), cb_host_output_commit(), cb_host_output_open(), cb_host_standard_sinks(), cb_sink_format(), internal_output_path(), internal_run_capacity(), internal_run_sweep(), k_cb_io_ok, and strcmp().

Variable Documentation

◆ s_cb_composition_workspace

uint8_t s_cb_composition_workspace[k_cb_composition_workspace_bytes]

static

Definition at line 268 of file cache_bench_report.c.

Referenced by internal_run_capacity(), and internal_run_sweep().

◆ s_cb_pct_scale_f

const double s_cb_pct_scale_f = 100.0

static

Floating-point 100.0 scale factor for hit-rate percentage output.

double 100.0 for pct maths.

Definition at line 61 of file cache_bench_report.c.

Referenced by internal_report_summary(), and internal_report_trace_row().

◆ s_cb_sizes

const uint32_t s_cb_sizes[]

static

Initial value:

                                 = {
  32U,
  (uint32_t)k_cb_size_64,
  (uint32_t)k_cb_size_128,
  (uint32_t)k_cb_size_256,
  (uint32_t)k_cb_size_512,
  (uint32_t)k_cb_size_1024,
  (uint32_t)k_cb_size_2048,
}

Swept cache capacities (frames) – the RAM-budget axis.

Definition at line 64 of file cache_bench_report.c.

Referenced by internal_report_trace(), internal_report_trace_header(), and internal_report_trace_row().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ cb_bench_size_t

◆ cb_composition_limit_t

◆ cb_loaded_cap_t

◆ cb_mid_cap_t

◆ cb_pct_scale_t

◆ cb_sweep_canary_t

Function Documentation

◆ internal_close_sources()

◆ internal_load_argv_traces()

◆ internal_output_path()

◆ internal_report_summary()

◆ internal_report_trace()

◆ internal_report_trace_header()

◆ internal_report_trace_row()

◆ internal_run_capacity()

◆ internal_run_sweep()

◆ main()

Variable Documentation

◆ s_cb_composition_workspace

◆ s_cb_pct_scale_f

◆ s_cb_sizes