sweep_block_backends.c File Reference

Streamed pseudo-memory and RBKC-z9 block-sweep backends. More...

#include <string.h>
#include <time.h>
#include "book_chunked.h"
#include "miniz.h"
#include "ra8_err.h"
#include "sweep_block_internal.h"

Include dependency graph for sweep_block_backends.c:

Go to the source code of this file.

Data Structures
struct	cbs_pack_sink_t
struct	cbs_rbkc_t

Enumerations
enum	cbs_codec_limit_t : uint32_t {   k_cbs_codec_input_bytes = 4096U ,   k_cbs_codec_window_bits = 15U }

Functions
RA8_PRIV uint64_t	priv_now_ns (void)
	Monotonic wall-clock in nanoseconds.
RA8_PRIV ra8_err_t	priv_meter_read (void *ctx, uint64_t offset, uint8_t *buffer, uint32_t length)
	ra8_vsource_read_fn forwarding through a cbs_meter_t.
static RA8_INTERNAL int	internal_mem_setup (cbs_backend_t *be, ra8_vsource_read_fn payload_read, void *payload_ctx, uint32_t blob_bytes, uint32_t block_bytes, cb_sweep_config_t *config)
	Bind the deterministic payload directly as an uncompressed backend.
static RA8_INTERNAL void	internal_backend_teardown (cbs_backend_t *be)
	Clear the borrowed runtime bindings of one backend.
static RA8_INTERNAL void	internal_rbkc_header (uint8_t *output, uint32_t block_bytes, uint64_t total, uint32_t count)
	Encode the fixed RBKC container header into caller storage.
static RA8_INTERNAL mz_bool	internal_pack_write (const void *data, int length, void *user)
	Append one compressor fragment to the injected scratch transaction.
static RA8_INTERNAL int	internal_rbkc_pack_chunk (tdefl_compressor *compressor, cbs_pack_sink_t *sink, ra8_vsource_read_fn payload_read, void *payload_ctx, uint8_t *input, uint32_t input_capacity, uint32_t offset, uint32_t length)
	Compress one logical payload chunk into the scratch stream.
static RA8_INTERNAL int	internal_rbkc_pack (ra8_vsource_read_fn payload_read, void *payload_ctx, uint32_t blob_bytes, uint32_t block_bytes, cb_sweep_config_t *config, uint8_t *input, uint32_t input_capacity, uint64_t *output_length)
	Stream an RBKC container into the injected scratch transaction.
static RA8_INTERNAL ra8_err_t	internal_rbkc_offsets (cbs_rbkc_t *rb, uint32_t chunk, uint64_t *begin, uint64_t *end)
	Read and validate one compressed chunk's relative offset pair.
static RA8_INTERNAL ra8_err_t	internal_rbkc_inflate (cbs_rbkc_t *rb, uint64_t begin, uint64_t end, uint8_t *output, uint32_t output_length)
	Inflate one exact RBKC chunk from scratch into caller storage.
static RA8_INTERNAL ra8_err_t	internal_rbkc_read (void *ctx, uint64_t offset, uint8_t *buffer, uint32_t length)
	Serve one aligned logical chunk through the RBKC backend seam.
static RA8_INTERNAL void *	internal_setup_take (cb_sweep_config_t *config, size_t bytes)
	Take one aligned setup region from the shared small workspace.
static RA8_INTERNAL int	internal_rbkc_setup (cbs_backend_t *be, ra8_vsource_read_fn payload_read, void *payload_ctx, uint32_t blob_bytes, uint32_t block_bytes, cb_sweep_config_t *config)
	Construct and bind the streamed RBKC-z9 benchmark backend.
RA8_PRIV cbs_backend_t *	priv_backends (uint32_t *out_count)
	Expose the registered sweep backends (the seam the HW leg extends).

Variables
static cbs_backend_t	s_cbs_backends []

Detailed Description

Streamed pseudo-memory and RBKC-z9 block-sweep backends.

RBKC construction writes directly to an injected scratch transaction. Compression state temporarily overlays the 1 MiB cache backing before the measured cache exists; the region is zeroed before it is rebound as frame storage. Chunk offsets and compressed input are read on demand, so no container, table, or max-chunk staging array is resident.

[Ring 7 / Tooling] {World: NS}

Copyright

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

Since

0.1.0

Definition in file sweep_block_backends.c.

Enumeration Type Documentation

cbs_codec_limit_t

enum cbs_codec_limit_t : uint32_t

Enumerator
k_cbs_codec_input_bytes	Streamed codec transfer grain.
k_cbs_codec_window_bits	Zlib window size as log2(bytes).

Definition at line 25 of file sweep_block_backends.c.

Function Documentation

internal_backend_teardown()

RA8_INTERNAL void internal_backend_teardown ( cbs_backend_t * be )

static

Clear the borrowed runtime bindings of one backend.

Makes teardown idempotent by nulling the read, context, and source counter pointers while leaving static identity fields unchanged.

Parameters

[in,out]

be

Backend to unbind; NULL is accepted.

Precondition

be is NULL or points to an initialized backend record.

No read is in flight through be.

Postcondition

A non-NULL backend has no active read or counter binding.

Static name, setup, teardown, and backing-byte fields are unchanged.

Note

Caller-owned payload and scratch storage are not released here.

Since

0.1.0

Definition at line 127 of file sweep_block_backends.c.

internal_mem_setup()

RA8_INTERNAL int internal_mem_setup ( cbs_backend_t * be, ra8_vsource_read_fn payload_read, void * payload_ctx, uint32_t blob_bytes, uint32_t block_bytes, cb_sweep_config_t * config )

static

Bind the deterministic payload directly as an uncompressed backend.

Publishes the injected read callback and logical blob size without allocating, copying, or using the scratch transaction.

Parameters

[in,out]	be	Backend record to bind.
[in]	payload_read	Deterministic payload reader.
[in]	payload_ctx	Payload reader context.
[in]	blob_bytes	Logical source length.
[in]	block_bytes	Swept block size, unused by direct memory.
[in,out]	config	Sweep composition, unused by direct memory.

Returns

Zero on a valid bind, otherwise one.

Return values

0	be publishes the injected source.
1	A required binding is absent or the blob is empty.

Precondition

be is writable.

payload_read and payload_ctx remain valid through teardown.

Postcondition

On success, be->backing_bytes == blob_bytes.

No ownership changes and no bytes are copied.

Note

The block and config parameters preserve the common backend seam.

Since

0.1.0

Definition at line 94 of file sweep_block_backends.c.

internal_pack_write()

RA8_INTERNAL mz_bool internal_pack_write ( const void * data, int length, void * user )

static

Append one compressor fragment to the injected scratch transaction.

Implements miniz's output callback and advances the absolute scratch offset only after a complete injected write.

Parameters

[in]	data	Compressor output bytes.
[in]	length	Fragment length from miniz.
[in,out]	user	Bound cbs_pack_sink_t.

Returns

Miniz callback status.

Return values

MZ_TRUE	The fragment was appended.
MZ_FALSE	An argument, prior failure, or scratch write failed.

Precondition

user identifies a live scratch transaction.

data is readable for non-negative length bytes.

Postcondition

On success, the sink offset advances by length.

On scratch failure, sink->failed remains latched.

Note

The callback never retries a failed injected transaction write.

Since

0.1.0

Definition at line 186 of file sweep_block_backends.c.

References cb_scratch_t::ctx, cbs_pack_sink_t::failed, k_cb_io_ok, cbs_pack_sink_t::offset, cbs_pack_sink_t::scratch, and cb_scratch_t::write.

Referenced by internal_rbkc_pack_chunk().

internal_rbkc_header()

RA8_INTERNAL void internal_rbkc_header ( uint8_t * output, uint32_t block_bytes, uint64_t total, uint32_t count )

static

Encode the fixed RBKC container header into caller storage.

Writes magic, block geometry, total length, chunk count, and the reserved zero field in the reader's native container layout.

Parameters

[out]	output	Header buffer of k_book_container_header_len bytes.
[in]	block_bytes	Chunk size encoded in the header.
[in]	total	Logical uncompressed byte length.
[in]	count	Number of chunks.

Precondition

output is non-NULL and large enough for the fixed header.

block_bytes and count describe total consistently.

Postcondition

Every header field is initialized.

No storage outside the fixed header span is touched.

Note

Encoding matches the in-tree ::book_chunked reader contract.

Since

0.1.0

Definition at line 153 of file sweep_block_backends.c.

References memcpy().

Referenced by internal_rbkc_pack().

internal_rbkc_inflate()

RA8_INTERNAL ra8_err_t internal_rbkc_inflate ( cbs_rbkc_t * rb, uint64_t begin, uint64_t end, uint8_t * output, uint32_t output_length )

static

Inflate one exact RBKC chunk from scratch into caller storage.

Pulls bounded compressed grains, drives tinfl in non-wrapping mode, and rejects stalled, truncated, extra-input, or wrong-size streams.

Parameters

[in,out]	rb	Bound RBKC reader and traffic counter.
[in]	begin	Relative compressed start.
[in]	end	Relative compressed end.
[out]	output	Destination buffer.
[in]	output_length	Exact expected uncompressed length.

Returns

Repository error code.

Return values

k_ra8_ok	Exactly one stream produced the requested bytes.
k_ra8_err_invalid_size	Scratch I/O or stream geometry failed.

Precondition

rb and output are non-NULL and begin < end.

output is writable for output_length bytes.

Postcondition

On success, all compressed bytes and output bytes are consumed exactly.

rb->source_bytes includes every compressed grain read.

Note

The inflater and input workspace are caller-owned and reused per chunk.

Since

0.1.0

Definition at line 395 of file sweep_block_backends.c.

References cb_scratch_t::ctx, cbs_rbkc_t::inflater, cbs_rbkc_t::input, cbs_rbkc_t::input_capacity, k_cb_io_ok, k_ra8_err_invalid_size, k_ra8_ok, cbs_rbkc_t::payload_offset, cb_scratch_t::read, cbs_rbkc_t::scratch, and cbs_rbkc_t::source_bytes.

Referenced by internal_rbkc_read().

internal_rbkc_offsets()

RA8_INTERNAL ra8_err_t internal_rbkc_offsets ( cbs_rbkc_t * rb, uint32_t chunk, uint64_t * begin, uint64_t * end )

static

Read and validate one compressed chunk's relative offset pair.

Fetches adjacent table entries through the injected scratch seam and checks monotonicity plus the physical container bound.

Parameters

[in,out]	rb	Bound RBKC reader state.
[in]	chunk	Chunk-table index.
[out]	begin	Receives the relative compressed start.
[out]	end	Receives the relative compressed end.

Returns

Repository error code.

Return values

k_ra8_ok	The offset pair is ordered and in range.
k_ra8_err_invalid_size	A read or geometry validation failed.

Precondition

rb, begin, and end are non-NULL.

chunk is less than rb->chunk_count.

Postcondition

On success, *begin <= *end within the scratch payload.

Reader state and scratch bytes are not modified.

Note

Offsets are relative to rb->payload_offset.

Since

0.1.0

Definition at line 360 of file sweep_block_backends.c.

References cb_scratch_t::ctx, k_book_container_entry_len, k_book_container_header_len, k_cb_io_ok, k_ra8_err_invalid_size, k_ra8_ok, cbs_rbkc_t::payload_offset, cb_scratch_t::read, cbs_rbkc_t::scratch, and cb_scratch_t::size.

Referenced by internal_rbkc_read().

internal_rbkc_pack()

RA8_INTERNAL int internal_rbkc_pack ( ra8_vsource_read_fn payload_read, void * payload_ctx, uint32_t blob_bytes, uint32_t block_bytes, cb_sweep_config_t * config, uint8_t * input, uint32_t input_capacity, uint64_t * output_length )

static

Stream an RBKC container into the injected scratch transaction.

Writes the fixed header and offset table incrementally, overlays tdefl state on the future cache backing, then erases that backing.

Parameters

[in]	payload_read	Deterministic payload reader.
[in]	payload_ctx	Payload reader context.
[in]	blob_bytes	Logical source length.
[in]	block_bytes	RBKC chunk size.
[in,out]	config	Scratch, cache overlay, and diagnostics.
[in,out]	input	Bounded codec input buffer.
[in]	input_capacity	Capacity of input.
[out]	output_length	Receives the container byte length.

Returns

Zero after complete construction, otherwise one.

Return values

0	Header, table, and all compressed chunks were written.
1	Alignment, capacity, read, compression, or scratch I/O failed.

Precondition

All bindings are non-NULL and sizes are non-zero.

Cache backing satisfies tdefl size and alignment requirements.

Postcondition

On success, scratch size and output_length match the container end.

On success, the full cache backing is zeroed before cache binding.

Note

The container and offset table are never materialized in RAM.

Since

0.1.0

Definition at line 279 of file sweep_block_backends.c.

References cb_sweep_config_t::cache_backing, cb_sweep_config_t::cache_capacity, cb_scratch_t::ctx, internal_rbkc_header(), internal_rbkc_pack_chunk(), k_book_container_entry_len, k_book_container_header_len, k_cb_io_ok, memset(), cbs_pack_sink_t::offset, cb_sweep_config_t::scratch, cb_scratch_t::size, cb_sweep_config_t::workspace_required, and cb_scratch_t::write.

Referenced by internal_rbkc_setup().

internal_rbkc_pack_chunk()

RA8_INTERNAL int internal_rbkc_pack_chunk ( tdefl_compressor * compressor, cbs_pack_sink_t * sink, ra8_vsource_read_fn payload_read, void * payload_ctx, uint8_t * input, uint32_t input_capacity, uint32_t offset, uint32_t length )

static

Compress one logical payload chunk into the scratch stream.

Reinitializes tdefl for an independent zlib stream, pulls the chunk in bounded input grains, and finishes through internal_pack_write.

Parameters

[in,out]	compressor	Caller-provided tdefl state.
[in,out]	sink	Scratch append binding.
[in]	payload_read	Payload read callback.
[in]	payload_ctx	Payload callback context.
[in,out]	input	Bounded codec input buffer.
[in]	input_capacity	Capacity of input.
[in]	offset	Payload start offset.
[in]	length	Uncompressed chunk length.

Returns

Zero after a complete zlib stream, otherwise one.

Return values

0	The chunk was fully compressed and appended.
1	Initialization, payload read, compression, or sink append failed.

Precondition

All pointer bindings are non-NULL and input_capacity is non-zero.

The requested payload range is valid.

Postcondition

On success, sink points immediately after the chunk stream.

The compressor state may be reused only after reinitialization.

Note

Each chunk intentionally starts a fresh zlib history.

Since

0.1.0

Definition at line 225 of file sweep_block_backends.c.

References cbs_pack_sink_t::failed, internal_pack_write(), k_cbs_codec_window_bits, and k_ra8_ok.

Referenced by internal_rbkc_pack().

internal_rbkc_read()

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

static

Serve one aligned logical chunk through the RBKC backend seam.

Validates the vsource request geometry, fetches its table offsets, and inflates exactly the requested logical chunk.

Parameters

[in]	ctx	Bound cbs_rbkc_t.
[in]	offset	Chunk-aligned logical byte offset.
[out]	buffer	Destination buffer.
[in]	length	Exact logical chunk length.

Returns

Repository error code.

Return values

k_ra8_ok	The chunk was decoded exactly.
k_ra8_err_null_ptr	A required binding is NULL.
k_ra8_err_out_of_range	The offset is outside or misaligned.
k_ra8_err_invalid_size	The length, table, or stream is invalid.

Precondition

buffer is writable for length bytes.

ctx remains bound until backend teardown.

Postcondition

On success, buffer holds the requested payload bytes.

Scratch bytes and logical geometry are not modified.

Note

This is the exact ra8_vsource_read_fn bound into the measured cache.

Since

0.1.0

Definition at line 459 of file sweep_block_backends.c.

References cbs_rbkc_t::chunk_bytes, cbs_rbkc_t::chunk_count, internal_rbkc_inflate(), internal_rbkc_offsets(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_err_out_of_range, k_ra8_ok, and cbs_rbkc_t::total_bytes.

Referenced by internal_rbkc_setup().

internal_rbkc_setup()

RA8_INTERNAL int internal_rbkc_setup ( cbs_backend_t * be, ra8_vsource_read_fn payload_read, void * payload_ctx, uint32_t blob_bytes, uint32_t block_bytes, cb_sweep_config_t * config )

static

Construct and bind the streamed RBKC-z9 benchmark backend.

Temporarily reserves codec input, builds the scratch container, rolls back to the setup floor, then binds inflater reader state.

Parameters

[in,out]	be	Backend record to bind.
[in]	payload_read	Deterministic payload reader.
[in]	payload_ctx	Payload reader context.
[in]	blob_bytes	Logical source length.
[in]	block_bytes	Swept chunk size.
[in,out]	config	Scratch and workspace composition.

Returns

Zero after a complete bind, otherwise one.

Return values

0	be publishes the RBKC read seam and traffic counter.
1	A binding, construction, or workspace check failed.

Precondition

Required pointers are non-NULL and block_bytes is non-zero.

Scratch and cache backing meet the packer's contracts.

Postcondition

On success, be remains valid until teardown or workspace reuse.

Setup-only tdefl state no longer occupies the cache backing.

Note

Codec workspace is phase-overlaid but never dynamically allocated.

Since

0.1.0

Definition at line 535 of file sweep_block_backends.c.

References internal_rbkc_pack(), internal_rbkc_read(), internal_setup_take(), k_book_container_entry_len, k_book_container_header_len, k_cbs_codec_input_bytes, cb_sweep_config_t::scratch, cbs_rbkc_t::source_bytes, cb_sweep_config_t::workspace_floor, and cb_sweep_config_t::workspace_used.

internal_setup_take()

RA8_INTERNAL void * internal_setup_take ( cb_sweep_config_t * config, size_t bytes )

static

Take one aligned setup region from the shared small workspace.

Advances workspace_used on success and always updates the exact required-capacity diagnostic for the attempted partition.

Parameters

[in,out]	config	Sweep workspace state.
[in]	bytes	Requested byte count before alignment.

Returns

Borrowed region pointer, or NULL on insufficient capacity.

Return values

NULL	The aligned request does not fit.
other	Pointer to the reserved region.

Precondition

config and config->workspace are non-NULL.

The aligned addition fits in size_t by fixed sweep geometry.

Postcondition

On success, workspace_used advances by the aligned span.

On failure, workspace_required exposes the attempted end offset.

Note

Returned storage remains caller-owned.

Since

0.1.0

Definition at line 499 of file sweep_block_backends.c.

References cb_sweep_config_t::workspace, cb_sweep_config_t::workspace_capacity, cb_sweep_config_t::workspace_required, and cb_sweep_config_t::workspace_used.

Referenced by internal_rbkc_setup().

priv_backends()

RA8_PRIV 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_PRIV 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()

RA8_PRIV 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().

Variable Documentation

s_cbs_backends

cbs_backend_t s_cbs_backends[]

static

Initial value:

                                    = {
  {.name = "mem", .setup = internal_mem_setup, .teardown = internal_backend_teardown},
  {.name = "rbkc-z9", .setup = internal_rbkc_setup, .teardown = internal_backend_teardown},
}

Definition at line 583 of file sweep_block_backends.c.

Referenced by priv_backends().