Raw-descriptor composition root for caller-workspace JOF conversion. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <unistd.h>
#include "ra8_attributes.h"
#include "ra8_fmt_host_fd_internal.h"
#include "ra8_fmt_portable_main_internal.h"
#include "ra8_fmt_stream.h"

Include dependency graph for ra8_fmt_portable_convert.c:

Data Structures
struct	convert_cli_args_t
	Parsed arguments accepted by the portable convert composition. More...

Enumerations
enum	convert_cli_const_t : uint32_t { k_convert_cli_ok = 0U , k_convert_cli_fail = 1U , k_convert_cli_usage = 2U , k_convert_cli_input = 268435456U , k_convert_cli_decimal = 20U , k_convert_cli_radix = 10U , k_convert_cli_align = 16U }
	CLI status, input, and decimal formatting bounds. More...

Functions
static ra8_err_t	internal_text (const ra8_fmt_sink_t sink, const char text)
	Append one NUL-terminated diagnostic fragment.
static ra8_err_t	internal_u64 (const ra8_fmt_sink_t *sink, uint64_t value)
	Append one unsigned decimal diagnostic field.
static void	internal_field (const ra8_fmt_sink_t sink, uint64_t value, const char suffix, ra8_err_t *status)
	Append one numeric field and suffix while status remains successful.
static void	internal_status (const ra8_fmt_sink_t errors, const char prefix, ra8_err_t status)
	Emit one canonical status diagnostic through fixed local formatting.
static bool	internal_parse (int argc, char *argv, convert_cli_args_t args)
	Parse the options accepted by the legacy convert command.
static bool	internal_align (size_t value, size_t *aligned)
	Round one byte count up to the composition arena alignment.
static bool	internal_high_water (const ra8_fmt_jof_convert_requirements_t requirements, size_t webp_offset, size_t *total)
	Compute the exact shared-arena high-water for one conversion.
static void	internal_capacity (const ra8_fmt_sink_t errors, const ra8_fmt_jof_convert_requirements_t requirements, size_t required, size_t supplied)
	Emit exact required/supplied workspace evidence.
static ra8_err_t	internal_size_input (const ra8_fmt_source_t source, size_t arena_cap, const ra8_fmt_sink_t errors, ra8_fmt_jof_convert_requirements_t requirements, size_t webp_offset, size_t high_water, bool sized)
	Probe exact producer requirements and confirm the caller arena fits.
static ra8_err_t	internal_run (const ra8_fmt_source_t source, const char output, const ra8_fmt_jof_convert_requirements_t requirements, uint8_t arena, size_t webp_offset, const ra8_fmt_sink_t *report)
	Bind exact work slices and execute one already-open conversion.
static void	internal_report_run_failure (const ra8_fmt_sink_t *errors, ra8_err_t rc, bool sized, size_t high_water, size_t arena_cap)
	Emit the one diagnostic matching how a failed conversion failed.
int	priv_fmt_try_portable_convert (int argc, char *argv, uint8_t arena, size_t arena_cap, bool *handled)
	Try the caller-workspace JOF-convert command path.

Detailed Description

Raw-descriptor composition root for caller-workspace JOF conversion.

Parses the JOF-convert subset, derives exact producer requirements, binds slices of an explicit caller arena, and publishes through a durable same-directory transaction. Over-budget inputs fail before stage creation.

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

Since: 0.1.0

Definition in file ra8_fmt_portable_convert.c.

Enumeration Type Documentation

◆ convert_cli_const_t

enum convert_cli_const_t : uint32_t

CLI status, input, and decimal formatting bounds.

Enumerator
k_convert_cli_ok	Successful conversion.
k_convert_cli_fail	Command execution failed.
k_convert_cli_usage	Invalid command line.
k_convert_cli_input	Maximum source file (256 MiB).
k_convert_cli_decimal	Digits in uint64_t.
k_convert_cli_radix	Diagnostic number radix.
k_convert_cli_align	Producer-arena slice alignment.

Definition at line 23 of file ra8_fmt_portable_convert.c.

Function Documentation

◆ internal_align()

bool internal_align	(	size_t	value,
		size_t *	aligned )

static

Round one byte count up to the composition arena alignment.

Applies checked power-of-two alignment without wrapping size_t.

Parameters

[in]	value	Unaligned byte count.
[out]	aligned	Receives the rounded byte count.

Returns: Whether rounding was representable.

Return values

true	`aligned` contains the exact rounded value.
false	Adding alignment padding would overflow.

Precondition: aligned is writable.; k_convert_cli_align is a non-zero power of two.

Postcondition: Success writes a multiple of k_convert_cli_align not below value.; Failure leaves aligned unspecified and performs no I/O.

Note: Pure apart from the caller output.

Since: 0.1.0

Definition at line 194 of file ra8_fmt_portable_convert.c.

References k_convert_cli_align.

Referenced by internal_high_water(), and internal_layout().

◆ internal_capacity()

void internal_capacity	(	const ra8_fmt_sink_t *	errors,
		const ra8_fmt_jof_convert_requirements_t *	requirements,
		size_t	required,
		size_t	supplied )

static

Emit exact required/supplied workspace evidence.

Reports total high-water and both component arena requirements.

Parameters

[in]	errors	Diagnostic sink.
[in]	requirements	Exact producer requirements.
[in]	required	Shared-arena high-water including alignment.
[in]	supplied	Caller arena capacity.

Precondition: errors and its write callback are non-null.; requirements describes a successfully probed source.

Postcondition: Complete diagnostic is attempted until the first sink error.; Requirements and capacity values remain unchanged.

Note: Diagnostic sink failures are intentionally ignored.

Since: 0.1.0

Definition at line 250 of file ra8_fmt_portable_convert.c.

References internal_field(), internal_text(), ra8_fmt_jof_convert_requirements_t::webp_work_bytes, and ra8_fmt_jof_convert_requirements_t::work_bytes.

Referenced by internal_size_input().

◆ internal_field()

void internal_field	(	const ra8_fmt_sink_t *	sink,
		uint64_t	value,
		const char *	suffix,
		ra8_err_t *	status )

static

Append one numeric field and suffix while status remains successful.

Centralizes fail-fast report composition without a local formatting macro.

Parameters

[in]	sink	Bound diagnostic sink.
[in]	value	Unsigned field value.
[in]	suffix	NUL-terminated text following the number.
[in,out]	status	Current and resulting sink status.

Precondition: Every pointer argument is non-null.; suffix is NUL-terminated and *status is a canonical status.

Postcondition: A successful incoming status attempts number then suffix in order.; A failing incoming or intermediate status prevents later writes.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 106 of file ra8_fmt_portable_convert.c.

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

Referenced by internal_capacity().

◆ internal_high_water()

bool internal_high_water	(	const ra8_fmt_jof_convert_requirements_t *	requirements,
		size_t *	webp_offset,
		size_t *	total )

static

Compute the exact shared-arena high-water for one conversion.

Adds the aligned producer slice and optional WebP slice with overflow checks.

Parameters

[in]	requirements	Per-producer arena requirements.
[out]	webp_offset	Aligned offset of optional WebP arena.
[out]	total	Exact shared arena high-water.

Returns: Whether the sum is representable.

Return values

true	Both outputs contain exact representable byte counts.
false	Alignment or addition would overflow size_t.

Precondition: Every pointer argument is non-null.; requirements was produced by the requirements API.

Postcondition: Success includes inter-arena alignment padding in total.; Failure performs no I/O or output transaction work.

Note: Pure apart from the two outputs.

Since: 0.1.0

Definition at line 221 of file ra8_fmt_portable_convert.c.

References internal_align(), ra8_fmt_jof_convert_requirements_t::webp_work_bytes, and ra8_fmt_jof_convert_requirements_t::work_bytes.

Referenced by internal_size_input().

◆ internal_parse()

bool internal_parse	(	int	argc,
		char **	argv,
		convert_cli_args_t *	args )

static

Parse the options accepted by the legacy convert command.

Recognizes the same bounded convert spellings before selecting JOF.

Parameters

[in]	argc	Argument count.
[in]	argv	Argument vector.
[out]	args	Receives input, output, and format selections.

Returns: Whether every argument was recognized and complete.

Return values

true	All arguments were consumed into `args`.
false	An unknown, duplicate positional, or incomplete option occurred.

Precondition: argv holds argc NUL-terminated argument pointers.; args is writable and initially zeroed.

Postcondition: Success consumes the complete argument vector without I/O.; Returned path pointers continue to refer into argv.

Note: Parsing is deterministic and locale-independent.

Since: 0.1.0

Definition at line 158 of file ra8_fmt_portable_convert.c.

References convert_cli_args_t::format, convert_cli_args_t::input, convert_cli_args_t::output, and strcmp().

Referenced by priv_fmt_try_portable_convert().

◆ internal_report_run_failure()

void internal_report_run_failure	(	const ra8_fmt_sink_t *	errors,
		ra8_err_t	rc,
		bool	sized,
		size_t	high_water,
		size_t	arena_cap )

static

Emit the one diagnostic matching how a failed conversion failed.

Distinguishes an in-budget engine failure from an unsized or over-budget source so the operator sees the correct rc-bearing line.

Parameters

[in]	errors	Diagnostic sink.
[in]	rc	Canonical status returned by the conversion attempt.
[in]	sized	Whether sizing produced a representable high-water.
[in]	high_water	Exact shared arena high-water, if `sized`.
[in]	arena_cap	Caller-supplied composition arena capacity.

Precondition: errors and its write callback are non-null.; high_water is meaningful only when sized is true.

Postcondition: A successful rc emits no diagnostic.; A failing rc emits exactly one diagnostic line.

Note: Diagnostic sink failures are intentionally ignored.

Since: 0.1.0

Definition at line 363 of file ra8_fmt_portable_convert.c.

References internal_status(), and k_ra8_ok.

Referenced by priv_fmt_try_portable_convert().

◆ internal_run()

ra8_err_t internal_run	(	const ra8_fmt_source_t *	source,
		const char *	output,
		const ra8_fmt_jof_convert_requirements_t *	requirements,
		uint8_t *	arena,
		size_t	webp_offset,
		const ra8_fmt_sink_t *	report )

static

Bind exact work slices and execute one already-open conversion.

Begins the sibling transaction only after sizing, then delegates the full engine.

Parameters

[in]	source	Open host source.
[in]	output	Destination path.
[in]	requirements	Exact producer requirements.
[in,out]	arena	Caller composition workspace.
[in]	webp_offset	Aligned WebP arena offset.
[in]	report	Standard-output report sink.

Returns: Canonical conversion or host transaction status.

Return values

k_ra8_ok	A complete atlas was durably published and reported.
other	Transaction creation or the portable engine failed.

Precondition: source and report remain bound for the complete call.; arena spans both exact slices at webp_offset.

Postcondition: Any failed conversion preserves the prior destination.; Every transaction resource acquired here is released.

Note: Descriptor ownership stays at this host composition edge.

Since: 0.1.0

Definition at line 323 of file ra8_fmt_portable_convert.c.

References k_ra8_ok, priv_fmt_host_transaction_begin(), ra8_fmt_jof_convert_stream(), ra8_fmt_jof_convert_requirements_t::webp_work_bytes, and ra8_fmt_jof_convert_requirements_t::work_bytes.

Referenced by priv_fmt_try_portable_convert().

◆ internal_size_input()

ra8_err_t internal_size_input	(	const ra8_fmt_source_t *	source,
		size_t	arena_cap,
		const ra8_fmt_sink_t *	errors,
		ra8_fmt_jof_convert_requirements_t *	requirements,
		size_t *	webp_offset,
		size_t *	high_water,
		bool *	sized )

static

Probe exact producer requirements and confirm the caller arena fits.

Delegates to the requirements API and the alignment-checked high-water sum, then reports and converts a too-small arena into a canonical sizing failure so the caller need not repeat that branch.

Parameters

[in]	source	Open host source already positioned for probing.
[in]	arena_cap	Caller-supplied composition arena capacity.
[in]	errors	Diagnostic sink.
[out]	requirements	Receives the exact producer requirements.
[out]	webp_offset	Receives the aligned optional WebP arena offset.
[out]	high_water	Receives the exact shared arena high-water.
[out]	sized	Receives whether `high_water` is representable.

Returns: Canonical requirements or capacity status.

Return values

k_ra8_ok	The arena is large enough for the probed source.
k_ra8_err_invalid_size	Sizing overflowed or exceeded `arena_cap`.
other	The requirements probe itself failed.

Precondition: Every pointer argument is non-null.; source remains valid and positioned for the complete probe.

Postcondition: Success writes representable, in-budget sizing into every output.; Failure emits one diagnostic through errors before returning.

Note: Thread safety inherits the injected sink and source.

Since: 0.1.0

Definition at line 286 of file ra8_fmt_portable_convert.c.

References internal_capacity(), internal_high_water(), k_ra8_err_invalid_size, k_ra8_ok, and ra8_fmt_jof_convert_requirements().

Referenced by priv_fmt_try_portable_convert().

◆ internal_status()

void internal_status	(	const ra8_fmt_sink_t *	errors,
		const char *	prefix,
		ra8_err_t	status )

static

Emit one canonical status diagnostic through fixed local formatting.

Appends a caller prefix, numeric status, and closing line delimiter.

Parameters

[in]	errors	Bound diagnostic sink.
[in]	prefix	NUL-terminated prefix including an opening delimiter.
[in]	status	Canonical status value.

Precondition: errors and its callback are non-null.; prefix is non-null and NUL-terminated.

Postcondition: Components were offered in order until the first sink error.; Diagnostic failure does not alter command state.

Note: The no-return diagnostic path intentionally drops sink errors.

Since: 0.1.0

Definition at line 130 of file ra8_fmt_portable_convert.c.

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

Referenced by internal_report_run_failure(), and priv_fmt_try_portable_convert().

◆ internal_text()

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

static

Append one NUL-terminated diagnostic fragment.

Measures the complete fragment and delegates one exact write.

Parameters

[in]	sink	Bound diagnostic sink.
[in]	text	NUL-terminated text fragment.

Returns: Injected sink status.

Return values

k_ra8_ok Complete text was accepted.

Precondition: sink and its callback are non-null.; text is non-null and NUL-terminated.

Postcondition: Exactly the bytes before NUL were offered once.; Neither sink binding nor source text was changed.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 55 of file ra8_fmt_portable_convert.c.

References ra8_fmt_sink_t::ctx, strlen(), and ra8_fmt_sink_t::write.

Referenced by internal_capacity(), internal_field(), internal_status(), and priv_fmt_try_portable_convert().

◆ internal_u64()

ra8_err_t internal_u64	(	const ra8_fmt_sink_t *	sink,
		uint64_t	value )

static

Append one unsigned decimal diagnostic field.

Converts without locale or formatting streams through fixed buffers.

Parameters

[in]	sink	Bound diagnostic sink.
[in]	value	Unsigned value to render.

Returns: Injected sink status.

Return values

k_ra8_ok Every decimal digit was accepted.

Precondition: sink and its callback are non-null.; The fixed digit capacity covers every uint64_t value.

Postcondition: One non-empty base-ten spelling was offered.; No global or filesystem state changed.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 75 of file ra8_fmt_portable_convert.c.

References ra8_fmt_sink_t::ctx, k_convert_cli_decimal, k_convert_cli_radix, and ra8_fmt_sink_t::write.

Referenced by internal_field(), and internal_status().

◆ priv_fmt_try_portable_convert()

int priv_fmt_try_portable_convert	(	int	argc,
		char **	argv,
		uint8_t *	arena,
		size_t	arena_cap,
		bool *	handled )

nodiscard

Try the caller-workspace JOF-convert command path.

Parameters

[in]	argc	Process argument count.
[in]	argv	Process argument vector.
[in,out]	arena	Explicit caller-owned producer workspace.
[in]	arena_cap	Exact bytes supplied at `arena`.
[out]	handled	Set when this function owns the exit status.

Returns: Process exit status when handled; unspecified otherwise.

Precondition: arena is aligned for max_align_t and spans arena_cap bytes.

Postcondition: An over-budget input fails before any output transaction begins.

Since: 0.1.0

Definition at line 379 of file ra8_fmt_portable_convert.c.

References convert_cli_args_t::format, convert_cli_args_t::input, internal_parse(), internal_report_run_failure(), internal_run(), internal_size_input(), internal_status(), internal_text(), k_convert_cli_fail, k_convert_cli_input, k_convert_cli_ok, k_convert_cli_usage, k_ra8_ok, convert_cli_args_t::output, priv_fmt_host_fd_sink(), priv_fmt_host_source_close(), priv_fmt_host_source_open(), RA8_PRIV, ra8_fmt_host_source_t::source, and strcmp().

Referenced by internal_dispatch().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ convert_cli_const_t

Function Documentation

◆ internal_align()

◆ internal_capacity()

◆ internal_field()

◆ internal_high_water()

◆ internal_parse()

◆ internal_report_run_failure()

◆ internal_run()

◆ internal_size_input()

◆ internal_status()

◆ internal_text()

◆ internal_u64()

◆ priv_fmt_try_portable_convert()