ra8-firmware: tools/reader_vmem/inc/reader_vmem_internal.h File Reference

ra8-firmware 0.1.0

Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)

Loading...

Searching...

No Matches

Private host sink and caller-owned workspace contracts for reader_vmem. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_vmem.h"

Include dependency graph for reader_vmem_internal.h:

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

Go to the source code of this file.

Data Structures
struct	rv_workspace_need_t
	Exact byte regions required for one cache budget. More...
struct	rv_workspace_t
	Typed views carved from a caller's workspace. More...
struct	rv_trace_t
	Caller-owned atomic trace-publication state. More...

Macros
#define	READER_VMEM_MAX_BUDGET (1024U)
	Maximum frames reserved by the standalone composition root.

Enumerations
enum	rv_internal_limit_t : uint32_t { k_rv_frame_bytes = 4096U , k_rv_bucket_count = 1024U , k_rv_host_path_cap = 4096U , k_rv_host_name_cap = 256U }
	Fixed composition and host-path limits. More...

Functions
bool	priv_rv_workspace_require (uint32_t budget, rv_workspace_need_t *need)
	Query exact split-region requirements for one frame budget.
bool	priv_rv_workspace_bind (void backing, size_t backing_bytes, const rv_workspace_need_t need, rv_workspace_t *workspace)
	Bind typed cache views into an aligned caller-owned backing.
bool	priv_rv_trace_begin (const char path, rv_trace_t trace)
	Begin one unpublished same-directory trace transaction.
bool	priv_rv_trace_reference (rv_trace_t *trace, uint32_t object_id, uint32_t frame)
	Append one exact object/frame reference to a trace transaction.
bool	priv_rv_trace_commit (rv_trace_t *trace)
	Durably and atomically publish a complete trace.
void	priv_rv_trace_abort (rv_trace_t *trace)
	Close and unlink an unpublished trace.
void	priv_rv_diag (const char *text)
	Write one best-effort diagnostic fragment to standard error.
void	priv_rv_diag_u64 (uint64_t value)
	Write one unsigned decimal diagnostic without stdio.

Detailed Description

Private host sink and caller-owned workspace contracts for reader_vmem.

The workload remains independent of hosted streams and allocation. The standalone composition root supplies one explicitly bounded RAM workspace, while trace publication is isolated behind a descriptor-backed host edge.

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

Since: 0.1.0

Definition in file reader_vmem_internal.h.

Macro Definition Documentation

◆ READER_VMEM_MAX_BUDGET

#define READER_VMEM_MAX_BUDGET (1024U)

Maximum frames reserved by the standalone composition root.

Definition at line 25 of file reader_vmem_internal.h.

Referenced by internal_prepare(), internal_report_workspace(), and internal_usage().

Enumeration Type Documentation

◆ rv_internal_limit_t

enum rv_internal_limit_t : uint32_t

Fixed composition and host-path limits.

Enumerator
k_rv_frame_bytes	Bytes per cache frame.
k_rv_bucket_count	Cache hash-bucket count.
k_rv_host_path_cap	Hosted path capacity.
k_rv_host_name_cap	Hosted leaf capacity.

Definition at line 29 of file reader_vmem_internal.h.

Function Documentation

◆ priv_rv_diag()

void priv_rv_diag ( const char * text )

Write one best-effort diagnostic fragment to standard error.

Retries interrupted and short raw-descriptor writes without stdio.

Parameters

[in] text NUL-terminated fragment; null is ignored.

Precondition: text is null or NUL-terminated.; Standard error may accept or reject output.

Postcondition: The complete non-null fragment was attempted.; No cache, trace, or filesystem state changed.

Note: Fragments can interleave with another process.

Since: 0.1.0

Definition at line 52 of file reader_vmem_host.c.

References strlen().

Referenced by internal_execute(), internal_prepare(), internal_report(), internal_report_rate(), internal_report_workspace(), internal_touch(), internal_usage(), priv_rv_diag_u64(), ra8_log_emit_error(), and ra8_log_emit_error_val().

◆ priv_rv_diag_u64()

void priv_rv_diag_u64 ( uint64_t value )

Write one unsigned decimal diagnostic without stdio.

Converts through a fixed local buffer before one bounded fragment write.

Parameters

[in] value Unsigned value to render in base ten.

Precondition: The fixed digit buffer covers every uint64_t value.; Standard error may accept or reject output.

Postcondition: The complete decimal spelling was attempted.; No cache, trace, or filesystem state changed.

Note: Fragments can interleave with another process.

Since: 0.1.0

Definition at line 100 of file reader_vmem_host.c.

References internal_decimal(), k_host_decimal_digits, and priv_rv_diag().

Referenced by internal_report(), internal_report_rate(), internal_report_workspace(), internal_touch(), internal_usage(), and ra8_log_emit_error_val().

◆ priv_rv_trace_abort()

void priv_rv_trace_abort ( rv_trace_t * trace )

Close and unlink an unpublished trace.

Idempotently releases every partially acquired transaction resource.

Parameters

[in,out] trace Trace state returned by the begin operation.

Precondition: trace is non-null and may be partially initialized.; No further append or commit uses the same state concurrently.

Postcondition: Every owned descriptor is closed.; Any owned private leaf is removed; the final trace is unchanged.

Note: Not thread-safe through one trace state.

Since: 0.1.0

Definition at line 312 of file reader_vmem_host.c.

References rv_trace_t::directory_fd, rv_trace_t::temp_exists, rv_trace_t::temp_name, and rv_trace_t::trace_fd.

Referenced by internal_execute(), priv_rv_trace_begin(), and priv_rv_trace_commit().

◆ priv_rv_trace_begin()

bool priv_rv_trace_begin	(	const char *	path,
		rv_trace_t *	trace )

nodiscard

Begin one unpublished same-directory trace transaction.

Definition at line 232 of file reader_vmem_host.c.

References rv_trace_t::directory_fd, rv_trace_t::final_name, internal_split_path(), internal_temp_name(), k_host_create_mode, k_host_temp_attempts, k_rv_host_path_cap, O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW, priv_rv_trace_abort(), rv_trace_t::temp_exists, rv_trace_t::temp_name, and rv_trace_t::trace_fd.

Referenced by internal_execute().

◆ priv_rv_trace_commit()

bool priv_rv_trace_commit ( rv_trace_t * trace )

nodiscard

Durably and atomically publish a complete trace.

Definition at line 287 of file reader_vmem_host.c.

References rv_trace_t::directory_fd, rv_trace_t::final_name, rv_trace_t::io_failed, priv_rv_trace_abort(), renameat(), rv_trace_t::temp_exists, rv_trace_t::temp_name, and rv_trace_t::trace_fd.

Referenced by internal_execute().

◆ priv_rv_trace_reference()

bool priv_rv_trace_reference	(	rv_trace_t *	trace,
		uint32_t	object_id,
		uint32_t	frame )

nodiscard

Append one exact object/frame reference to a trace transaction.

Definition at line 266 of file reader_vmem_host.c.

References internal_decimal(), internal_pwrite_exact(), rv_trace_t::io_failed, k_host_decimal_digits, memcpy(), rv_trace_t::offset, and rv_trace_t::trace_fd.

Referenced by internal_touch().

◆ priv_rv_workspace_bind()

bool priv_rv_workspace_bind	(	void *	backing,
		size_t	backing_bytes,
		const rv_workspace_need_t *	need,
		rv_workspace_t *	workspace )

nodiscard

Bind typed cache views into an aligned caller-owned backing.

Definition at line 121 of file reader_vmem_workspace.c.

References rv_workspace_need_t::bucket_bytes, rv_workspace_need_t::bucket_offset, rv_workspace_need_t::frame_bytes, rv_workspace_need_t::frame_offset, internal_region_valid(), rv_workspace_need_t::key_bytes, rv_workspace_need_t::key_offset, rv_workspace_need_t::meta_bytes, rv_workspace_need_t::meta_offset, and rv_workspace_need_t::total_bytes.

Referenced by internal_prepare().

◆ priv_rv_workspace_require()

bool priv_rv_workspace_require	(	uint32_t	budget,
		rv_workspace_need_t *	need )

nodiscard

Query exact split-region requirements for one frame budget.

Definition at line 75 of file reader_vmem_workspace.c.

References rv_workspace_need_t::bucket_bytes, rv_workspace_need_t::bucket_offset, rv_workspace_need_t::frame_bytes, rv_workspace_need_t::frame_offset, internal_region(), internal_size_mul(), k_rv_bucket_count, k_rv_frame_bytes, rv_workspace_need_t::key_bytes, rv_workspace_need_t::key_offset, rv_workspace_need_t::meta_bytes, rv_workspace_need_t::meta_offset, and rv_workspace_need_t::total_bytes.

Referenced by internal_prepare().