Callback-driven, caller-workspace JOF inspection and reporting. More...

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

Include dependency graph for ra8_fmt_stream_inspect.c:

Enumerations
enum	fmt_text_const_t : uint32_t { k_fmt_text_dec_digits = 20U , k_fmt_text_hex_digits = 16U , k_fmt_text_hex_row = 16U , k_fmt_text_dec_radix = 10U , k_fmt_text_nibble = 4U , k_fmt_text_nibble_mask = 15U , k_fmt_text_max_rows = 4096U , k_fmt_text_col_width = 10U , k_fmt_text_ascii_low = 32U , k_fmt_text_ascii_high = 126U }
	Text formatting constants. More...

Functions
static ra8_err_t	internal_put (const ra8_fmt_sink_t report, const uint8_t bytes, size_t len)
	Append a byte span to the report sink.
static ra8_err_t	internal_text (const ra8_fmt_sink_t report, const char text)
	Append a NUL-terminated literal to the report sink.
static ra8_err_t	internal_char (const ra8_fmt_sink_t *report, char value)
	Append one character.
static ra8_err_t	internal_u64 (const ra8_fmt_sink_t *report, uint64_t value, uint32_t width)
	Append an unsigned decimal with optional left padding.
static ra8_err_t	internal_hex (const ra8_fmt_sink_t *report, uint64_t value, uint32_t width)
	Append an uppercase hexadecimal value with zero padding.
static ra8_err_t	internal_value_line (const ra8_fmt_sink_t report, const char label, uint64_t value, const char *suffix)
	Emit one label/value decimal line.
static ra8_err_t	internal_read_exact (const ra8_fmt_source_t source, uint64_t offset, uint8_t bytes, size_t len)
	Read an exact source window.
static ra8_err_t	internal_hex_dump_header (const ra8_fmt_sink_t report, const char label, uint64_t offset, size_t len)
	Emit the label/length/offset header line for a hex/ASCII dump.
static ra8_err_t	internal_hex_dump_row (const ra8_fmt_sink_t report, uint64_t offset, const uint8_t row, size_t count)
	Render one already-loaded hex/ASCII row: offset, hex bytes, ASCII.
static ra8_err_t	internal_hex_dump (const ra8_fmt_source_t source, const ra8_fmt_sink_t report, const char *label, uint64_t offset, size_t len)
	Emit one labelled hex/ASCII source window.
static ra8_err_t	internal_dimensions (const jof_info_t info, const ra8_fmt_sink_t report)
	Emit image, tile, and grid dimensions in the legacy CLI layout.
static ra8_err_t	internal_geometry (const ra8_fmt_source_t source, const jof_info_t info, const ra8_fmt_sink_t *report)
	Emit parsed JOF geometry in the legacy CLI layout.
static ra8_err_t	internal_table_row (const ra8_fmt_sink_t report, uint32_t index, const jof_audit_record_t record)
	Render one audit-record row of the verbose per-tile table.
static ra8_err_t	internal_table (const jof_audit_record_t records, uint32_t count, const ra8_fmt_sink_t report)
	Emit the verbose per-tile table.
ra8_err_t	ra8_fmt_jof_inspect_stream (const ra8_fmt_source_t source, bool verbose, const ra8_fmt_jof_inspect_workspace_t workspace, const ra8_fmt_sink_t *report)
	Inspect one JOF source through callbacks and caller storage.

Detailed Description

Callback-driven, caller-workspace JOF inspection and reporting.

Audits injected positioned-read sources with caller-owned records, tile, and scratch spans, then emits bounded deterministic report sections.

Tag: [Ring 4 / Domain] {World: NS}

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

Since: 0.1.0

Definition in file ra8_fmt_stream_inspect.c.

Enumeration Type Documentation

◆ fmt_text_const_t

enum fmt_text_const_t : uint32_t

Text formatting constants.

Enumerator
k_fmt_text_dec_digits	Maximum u64 decimal digits.
k_fmt_text_hex_digits	Maximum u64 hex digits.
k_fmt_text_hex_row	Bytes per hex dump row.
k_fmt_text_dec_radix	Decimal formatting radix.
k_fmt_text_nibble	Bits in one hex digit.
k_fmt_text_nibble_mask	Low-nibble extraction mask.
k_fmt_text_max_rows	Maximum verbose tile rows.
k_fmt_text_col_width	Stored-value column width.
k_fmt_text_ascii_low	First printable ASCII byte.
k_fmt_text_ascii_high	Last printable ASCII byte.

Definition at line 24 of file ra8_fmt_stream_inspect.c.

Function Documentation

◆ internal_char()

ra8_err_t internal_char	(	const ra8_fmt_sink_t *	report,
		char	value )

static

Append one character.

Converts the character to one byte and delegates an exact one-byte span.

Parameters

[in]	report	Report sink.
[in]	value	Character byte.

Returns: Sink status.

Return values

k_ra8_ok	Sink accepted the character byte.
other	Injected sink rejected the byte.

Precondition: report and its callback are non-null.; value is treated as one byte without locale conversion.

Postcondition: Exactly one sink write was attempted.; No caller storage was retained.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 100 of file ra8_fmt_stream_inspect.c.

References internal_put().

Referenced by internal_hex_dump_row(), internal_table_row(), and internal_u64().

◆ internal_dimensions()

ra8_err_t internal_dimensions	(	const jof_info_t *	info,
		const ra8_fmt_sink_t *	report )

static

Emit image, tile, and grid dimensions in the legacy CLI layout.

Formats parsed dimensions in the exact established multi-line order.

Parameters

[in]	info	Parsed geometry.
[in]	report	Report sink.

Returns: Sink status.

Return values

k_ra8_ok	Every field was emitted.
other	First injected sink failure.

Precondition: info and report are non-null.; Geometry was accepted by the JOF parser.

Postcondition: Success emits image, tile, and grid lines exactly once.; Parsed geometry is unchanged.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 394 of file ra8_fmt_stream_inspect.c.

References jof_info_t::height, internal_text(), internal_u64(), k_ra8_ok, jof_info_t::tile_cols, jof_info_t::tile_h, jof_info_t::tile_rows, jof_info_t::tile_w, and jof_info_t::width.

Referenced by internal_geometry().

◆ internal_geometry()

ra8_err_t internal_geometry	(	const ra8_fmt_source_t *	source,
		const jof_info_t *	info,
		const ra8_fmt_sink_t *	report )

static

Emit parsed JOF geometry in the legacy CLI layout.

Reports source size, dimensions, codec, layout offsets, and long-strip evidence.

Parameters

[in]	source	Source object.
[in]	info	Parsed geometry.
[in]	report	Report sink.

Returns: Sink status.

Return values

k_ra8_ok	Every geometry field was emitted.
other	First injected sink failure.

Precondition: Source, parsed info, report, and callbacks are non-null.; Source size and info came from the same parsed object.

Postcondition: Success emits the complete legacy geometry section.; Source and parsed metadata remain unchanged.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 453 of file ra8_fmt_stream_inspect.c.

References jof_info_t::bpp, jof_info_t::codec, jof_info_t::index_off, internal_dimensions(), internal_text(), internal_u64(), internal_value_line(), k_jof_codec_deflate, k_ra8_ok, ra8_fmt_source_t::size, jof_info_t::tile_count, jof_info_t::tile_w, jof_info_t::total_size, and jof_info_t::width.

Referenced by ra8_fmt_jof_inspect_stream().

◆ internal_hex()

ra8_err_t internal_hex	(	const ra8_fmt_sink_t *	report,
		uint64_t	value,
		uint32_t	width )

static

Append an uppercase hexadecimal value with zero padding.

Extracts nibbles into a fixed buffer independent of host endianness.

Parameters

[in]	report	Report sink.
[in]	value	Value to format.
[in]	width	Exact digit width (up to 16).

Returns: Sink status.

Return values

k_ra8_ok	Exactly `width` digits were accepted.
k_ra8_err_invalid_size	Width exceeds 16 hexadecimal digits.
other	Injected sink rejected the byte span.

Precondition: report and its callback are non-null.; width may be zero through any uint32_t value.

Postcondition: Success emits uppercase digits with leading zeroes.; Invalid width invokes no sink callback.

Note: Values wider than the requested field are intentionally truncated.

Since: 0.1.0

Definition at line 159 of file ra8_fmt_stream_inspect.c.

References internal_put(), k_fmt_text_hex_digits, k_fmt_text_nibble, k_fmt_text_nibble_mask, and k_ra8_err_invalid_size.

Referenced by internal_hex_dump_row(), and internal_table_row().

◆ internal_hex_dump()

ra8_err_t internal_hex_dump	(	const ra8_fmt_source_t *	source,
		const ra8_fmt_sink_t *	report,
		const char *	label,
		uint64_t	offset,
		size_t	len )

static

Emit one labelled hex/ASCII source window.

Reads through a fixed 16-byte row and renders stable offsets, hex, and ASCII.

Parameters

[in]	source	Source object.
[in]	report	Report sink.
[in]	label	Section label.
[in]	offset	Absolute source offset.
[in]	len	Byte count.

Returns: Read or sink status.

Return values

k_ra8_ok	Complete labelled dump was emitted.
other	First exact-read or sink error.

Precondition: Source, report, label, and callbacks are non-null.; Requested half-open source window is within source->size.

Postcondition: Success reads and reports exactly len source bytes.; No source or report binding is modified.

Note: Uses bounded stack storage independent of dump length.

Since: 0.1.0

Definition at line 355 of file ra8_fmt_stream_inspect.c.

References internal_hex_dump_header(), internal_hex_dump_row(), internal_read_exact(), k_fmt_text_hex_row, and k_ra8_ok.

Referenced by ra8_fmt_jof_inspect_stream().

◆ internal_hex_dump_header()

ra8_err_t internal_hex_dump_header	(	const ra8_fmt_sink_t *	report,
		const char *	label,
		uint64_t	offset,
		size_t	len )

static

Emit the label/length/offset header line for a hex/ASCII dump.

Sequences the label, the decimal byte count, and the decimal source offset into one line, stopping at the first sink failure.

Parameters

[in]	report	Report sink.
[in]	label	Section label.
[in]	offset	Absolute source offset.
[in]	len	Byte count.

Returns: Sink status.

Return values

k_ra8_ok	The complete header line was emitted.
other	First injected sink failure.

Precondition: report and label are non-null.; label is NUL-terminated.

Postcondition: No source or report binding is modified.; Failure prevents all later components from being offered.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 255 of file ra8_fmt_stream_inspect.c.

References internal_text(), internal_u64(), and k_ra8_ok.

Referenced by internal_hex_dump().

◆ internal_hex_dump_row()

ra8_err_t internal_hex_dump_row	(	const ra8_fmt_sink_t *	report,
		uint64_t	offset,
		const uint8_t *	row,
		size_t	count )

static

Render one already-loaded hex/ASCII row: offset, hex bytes, ASCII.

Emits the zero-padded offset, then k_fmt_text_hex_row hex columns in which every column past count is blanked, then the ASCII gutter where a byte outside the printable range renders as a period.

Parameters

[in]	report	Report sink.
[in]	offset	Absolute source offset of `row`[0].
[in]	row	Loaded row bytes, exactly k_fmt_text_hex_row long.
[in]	count	Valid leading bytes of `row` (the rest pad with spaces).

Returns: Sink status.

Return values

k_ra8_ok	The complete row was emitted.
other	First injected sink failure.

Precondition: report and row are non-null; count is at most k_fmt_text_hex_row.; row holds the count bytes already read from offset.

Postcondition: No source or report binding is modified.; Failure prevents all later columns from being offered.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 300 of file ra8_fmt_stream_inspect.c.

References internal_char(), internal_hex(), internal_text(), k_fmt_text_ascii_high, k_fmt_text_ascii_low, k_fmt_text_hex_row, and k_ra8_ok.

Referenced by internal_hex_dump().

◆ internal_put()

ra8_err_t internal_put	(	const ra8_fmt_sink_t *	report,
		const uint8_t *	bytes,
		size_t	len )

static

Append a byte span to the report sink.

Delegates exactly once to the injected sink without retaining bytes.

Parameters

[in]	report	Report sink.
[in]	bytes	Bytes to append.
[in]	len	Byte count.

Returns: Sink status.

Return values

k_ra8_ok	Sink accepted the complete span.
other	Injected sink rejected the span.

Precondition: report and its write callback are non-null.; bytes spans len readable bytes.

Postcondition: Sink callback was invoked exactly once.; Source bytes and sink binding are unchanged.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 54 of file ra8_fmt_stream_inspect.c.

Referenced by internal_char(), internal_hex(), and internal_text().

◆ internal_read_exact()

ra8_err_t internal_read_exact	(	const ra8_fmt_source_t *	source,
		uint64_t	offset,
		uint8_t *	bytes,
		size_t	len )

static

Read an exact source window.

Converts a short successful callback result into validation failure.

Parameters

[in]	source	Source object.
[in]	offset	Absolute offset.
[out]	bytes	Destination.
[in]	len	Exact length.

Returns: Read status or validation failure on a short read.

Return values

k_ra8_ok	Exactly `len` bytes were read.
k_ra8_err_validation_failed	Callback returned a short success.
other	Injected source read failed.

Precondition: source and its callback are non-null.; bytes spans len writable bytes.

Postcondition: Success initializes the complete destination range.; Failure never claims an exact read.

Note: Thread safety inherits the injected source.

Since: 0.1.0

Definition at line 226 of file ra8_fmt_stream_inspect.c.

References ra8_fmt_source_t::ctx, k_ra8_err_validation_failed, k_ra8_ok, and ra8_fmt_source_t::read_at.

Referenced by internal_hex_dump().

◆ internal_table()

ra8_err_t internal_table	(	const jof_audit_record_t *	records,
		uint32_t	count,
		const ra8_fmt_sink_t *	report )

static

Emit the verbose per-tile table.

Bounds output to the configured row ceiling and reports any elided count.

Parameters

[in]	records	Completed audit records.
[in]	count	Record count.
[in]	report	Report sink.

Returns: Sink status.

Return values

k_ra8_ok	Header, bounded records, and elision notice were emitted.
other	First injected sink failure.

Precondition: records spans count completed audit records.; report and its callback are non-null.

Postcondition: At most k_fmt_text_max_rows records are emitted.; Record storage is unchanged.

Note: Output work is bounded even for the maximum legal atlas.

Since: 0.1.0

Definition at line 561 of file ra8_fmt_stream_inspect.c.

References internal_table_row(), internal_text(), internal_u64(), k_fmt_text_max_rows, and k_ra8_ok.

Referenced by ra8_fmt_jof_inspect_stream().

◆ internal_table_row()

ra8_err_t internal_table_row	(	const ra8_fmt_sink_t *	report,
		uint32_t	index,
		const jof_audit_record_t *	record )

static

Render one audit-record row of the verbose per-tile table.

Emits the row index and the record's offset, length, payload, width, and height as fixed-width decimal columns, then the content hash in hex.

Parameters

[in]	report	Report sink.
[in]	index	Zero-based row index, printed in the tile column.
[in]	record	Completed audit record for this row.

Returns: Sink status.

Return values

k_ra8_ok	The complete row was emitted.
other	First injected sink failure.

Precondition: report and record are non-null.; record was completed by the JOF audit pass.

Postcondition: Record storage is unchanged.; Failure prevents all later columns from being offered.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 513 of file ra8_fmt_stream_inspect.c.

References jof_audit_record_t::content_hash, jof_audit_record_t::height, internal_char(), internal_hex(), internal_text(), internal_u64(), k_fmt_text_col_width, k_ra8_ok, jof_audit_record_t::length, jof_audit_record_t::offset, jof_audit_record_t::payload, and jof_audit_record_t::width.

Referenced by internal_table().

◆ internal_text()

ra8_err_t internal_text	(	const ra8_fmt_sink_t *	report,
		const char *	text )

static

Append a NUL-terminated literal to the report sink.

Measures the literal explicitly, then delegates one exact byte span.

Parameters

[in]	report	Report sink.
[in]	text	NUL-terminated text.

Returns: Sink status.

Return values

k_ra8_ok	Sink accepted the complete literal.
other	Injected sink rejected the literal.

Precondition: report and text are non-null.; text is NUL-terminated.

Postcondition: Exactly the bytes before NUL were offered to the sink.; No NUL byte is appended.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 75 of file ra8_fmt_stream_inspect.c.

References internal_put().

Referenced by internal_dimensions(), internal_geometry(), internal_hex_dump_header(), internal_hex_dump_row(), internal_table(), internal_table_row(), internal_value_line(), and ra8_fmt_jof_inspect_stream().

◆ internal_u64()

ra8_err_t internal_u64	(	const ra8_fmt_sink_t *	report,
		uint64_t	value,
		uint32_t	width )

static

Append an unsigned decimal with optional left padding.

Converts in a fixed reverse buffer and emits padding and digits incrementally.

Parameters

[in]	report	Report sink.
[in]	value	Value to format.
[in]	width	Minimum field width.

Returns: Sink status.

Return values

k_ra8_ok	Every padding and digit byte was accepted.
other	First injected sink failure.

Precondition: report and its callback are non-null.; Fixed digit capacity covers every uint64_t value.

Postcondition: On success at least width characters were emitted.; On failure no further sink call is made.

Note: Large widths are streamed and acquire no additional storage.

Since: 0.1.0

Definition at line 123 of file ra8_fmt_stream_inspect.c.

References internal_char(), k_fmt_text_dec_digits, k_fmt_text_dec_radix, and k_ra8_ok.

Referenced by internal_dimensions(), internal_geometry(), internal_hex_dump_header(), internal_table(), internal_table_row(), and internal_value_line().

◆ internal_value_line()

ra8_err_t internal_value_line	(	const ra8_fmt_sink_t *	report,
		const char *	label,
		uint64_t	value,
		const char *	suffix )

static

Emit one label/value decimal line.

Sequences prefix, unpadded integer, and suffix with fail-fast sink handling.

Parameters

[in]	report	Report sink.
[in]	label	Prefix including spacing and colon.
[in]	value	Decimal value.
[in]	suffix	Text following the value, including newline.

Returns: Sink status.

Return values

k_ra8_ok	Every component was accepted.
other	First injected sink failure.

Precondition: report, label, and suffix are non-null.; Both text fragments are NUL-terminated.

Postcondition: Success emits the three components contiguously.; Failure prevents all later components from being offered.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 191 of file ra8_fmt_stream_inspect.c.

References internal_text(), internal_u64(), and k_ra8_ok.

Referenced by internal_geometry(), and ra8_fmt_jof_inspect_stream().

◆ ra8_fmt_jof_inspect_stream()

ra8_err_t ra8_fmt_jof_inspect_stream	(	const ra8_fmt_source_t *	source,
		bool	verbose,
		const ra8_fmt_jof_inspect_workspace_t *	workspace,
		const ra8_fmt_sink_t *	report )

nodiscard

Inspect one JOF source through callbacks and caller storage.

Parameters

[in]	source	Immutable JOF input.
[in]	verbose	Emit header/footer hex and the full tile table.
[in,out]	workspace	Exact-or-larger audit buffers.
[in,out]	report	Human-readable text sink.

Returns: Audit or sink status.

Postcondition: No allocation occurs and no backend pointer is retained.

Since: 0.1.0

Definition at line 584 of file ra8_fmt_stream_inspect.c.

References ra8_fmt_source_t::ctx, jof_audit_result_t::duplicate_candidates, jof_audit_result_t::info, internal_geometry(), internal_hex_dump(), internal_table(), internal_text(), internal_value_line(), jof_audit(), k_jof_footer_bytes, k_jof_hdr_bytes, k_ra8_err_null_ptr, k_ra8_err_validation_failed, k_ra8_ok, ra8_fmt_source_t::read_at, ra8_fmt_jof_inspect_workspace_t::record_cap, ra8_fmt_jof_inspect_workspace_t::records, ra8_fmt_jof_inspect_workspace_t::scratch, ra8_fmt_jof_inspect_workspace_t::scratch_cap, ra8_fmt_source_t::size, ra8_fmt_jof_inspect_workspace_t::tile, ra8_fmt_jof_inspect_workspace_t::tile_cap, and jof_info_t::tile_count.

Referenced by internal_run_jof().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ fmt_text_const_t

Function Documentation

◆ internal_char()

◆ internal_dimensions()

◆ internal_geometry()

◆ internal_hex()

◆ internal_hex_dump()

◆ internal_hex_dump_header()

◆ internal_hex_dump_row()

◆ internal_put()

◆ internal_read_exact()

◆ internal_table()

◆ internal_table_row()

◆ internal_text()

◆ internal_u64()

◆ internal_value_line()

◆ ra8_fmt_jof_inspect_stream()