ra8_io_stream.h File Reference

ra8_io targetable byte-stream facade – one writer, many destinations. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_io_stream.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_io_stream_t
	Caller-allocated byte-stream handle binding a sink to its context. More...

Typedefs
typedef struct ra8_io_stream_iface	ra8_io_stream_iface_t

Functions
ra8_err_t	ra8_io_stream_write (ra8_io_stream_t *s, const uint8_t *buf, uint32_t len, uint32_t *out_written)
	Write len bytes to the bound sink.
ra8_err_t	ra8_io_stream_flush (ra8_io_stream_t *s)
	Flush any sink-side buffering to its destination.
ra8_err_t	ra8_io_stream_putc (ra8_io_stream_t *s, char c)
	Write a single byte to the bound sink.
ra8_err_t	ra8_io_stream_puts (ra8_io_stream_t *s, const char *str)
	Write a NUL-terminated string (without the NUL) to the bound sink.
ra8_err_t	ra8_io_stream_put_u32 (ra8_io_stream_t *s, uint32_t value)
	Write value as unsigned decimal ASCII (no leading zeros).
ra8_err_t	ra8_io_stream_put_u64 (ra8_io_stream_t *s, uint64_t value)
	Write value as unsigned 64-bit decimal ASCII without leading zeros.
ra8_err_t	ra8_io_stream_put_hex (ra8_io_stream_t *s, uint32_t value, uint8_t min_digits)
	Write value as lowercase hex ASCII, zero-padded to min_digits.

Detailed Description

ra8_io targetable byte-stream facade – one writer, many destinations.

Tag

[Ring 4 / PAL] {World: NS}

A stream is a byte sink the application names rather than couples to: bind a backend (UART/SCI, USB-CDC, an in-RAM buffer, or a raw block device) into a caller-owned ra8_io_stream_t, then write to it. This is the "do an output operation and pick the target" half of the fabric – the same puts / putc / write / put_u32 / put_hex call lands wherever the bound backend sends it, exactly as a block-device backend is chosen for storage.

The formatted helpers are deliberately varargs-free. The firmware traps _sbrk and bans the newlib printf family (its vfprintf blows the bounded-stack budget), so this layer offers small, bounded, no-allocation primitives instead of a fprintf: integers go out through ra8_io_stream_put_u32 / ra8_io_stream_put_hex, strings through ra8_io_stream_puts.

static uint8_t s_buf[256];
static ra8_io_stream_ram_state_t s_st;
ra8_io_stream_t out = {};
(void)ra8_io_stream_ram_init(&out, &s_st, s_buf, sizeof(s_buf));
(void)ra8_io_stream_puts(&out, "temp=");
(void)ra8_io_stream_put_u32(&out, 42U);
(void)ra8_io_stream_putc(&out, '\n');

Copyright

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

Since

0.1.0

Definition in file ra8_io_stream.h.

Typedef Documentation

ra8_io_stream_iface_t

typedef struct ra8_io_stream_iface ra8_io_stream_iface_t

Definition at line 62 of file ra8_io_stream.h.

Function Documentation

ra8_io_stream_flush()

ra8_err_t ra8_io_stream_flush ( ra8_io_stream_t * s )

nodiscard

Flush any sink-side buffering to its destination.

Parameters

[in]

s

Bound stream handle.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Pending bytes committed (or none pending).
k_ra8_err_null_ptr	s was NULL.
k_ra8_err_not_initialized	No sink is bound to s.

Precondition

A sink has been bound into s.

The stream is idle (no concurrent writer).

Postcondition

On success the destination reflects every prior successful write.

No handle state is mutated by a flush of an unbuffered sink.

Note

Not thread-safe with respect to the same stream.

Since

0.1.0

Definition at line 116 of file ra8_io_stream.c.

References ra8_io_stream_t::ctx, ra8_io_stream_iface::flush, ra8_io_stream_t::iface, internal_validate(), and k_ra8_ok.

Referenced by internal_solve_words(), main(), and priv_mdl_stream_flush().

ra8_io_stream_put_hex()

ra8_err_t ra8_io_stream_put_hex ( ra8_io_stream_t * s, uint32_t value, uint8_t min_digits )

nodiscard

Write value as lowercase hex ASCII, zero-padded to min_digits.

Parameters

[in]	s	Bound stream handle.
[in]	value	Value to render.
[in]	min_digits	Minimum digit count (1..8); pad with leading zeros.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Digits written.
k_ra8_err_null_ptr	s was NULL.
k_ra8_err_not_initialized	No sink is bound to s.
k_ra8_err_invalid_arg	min_digits is zero or greater than eight.
k_ra8_err_no_mem	A bounded sink could not accept the digits.

Precondition

A sink has been bound into s.

min_digits is in 1..8.

Postcondition

On success the hex rendering of value was written (no 0x prefix).

At most eight ASCII digits are produced.

Note

Not thread-safe; uses a bounded stack buffer (no allocation).

Since

0.1.0

Definition at line 197 of file ra8_io_stream.c.

References internal_validate(), k_ra8_err_invalid_arg, k_ra8_io_hex_base, k_ra8_io_hex_max_digits, k_ra8_ok, and ra8_io_stream_write().

Referenced by internal_put_hex(), and priv_mdl_stream_hex().

ra8_io_stream_put_u32()

ra8_err_t ra8_io_stream_put_u32 ( ra8_io_stream_t * s, uint32_t value )

nodiscard

Write value as unsigned decimal ASCII (no leading zeros).

Parameters

[in]	s	Bound stream handle.
[in]	value	Value to render.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Digits written.
k_ra8_err_null_ptr	s was NULL.
k_ra8_err_not_initialized	No sink is bound to s.
k_ra8_err_no_mem	A bounded sink could not accept the digits.

Precondition

A sink has been bound into s.

The stream is idle.

Postcondition

On success the decimal rendering of value was written.

At most ten ASCII digits are produced.

Note

Not thread-safe; uses a bounded stack buffer (no allocation).

Since

0.1.0

Definition at line 155 of file ra8_io_stream.c.

References internal_validate(), k_ra8_io_dec_base, k_ra8_io_u32_max_digits, k_ra8_ok, and ra8_io_stream_write().

Referenced by demo_report_map(), demo_report_wear(), internal_emit_match(), internal_put_u32(), internal_report_header(), internal_report_row(), internal_swap_run_one(), and main().

ra8_io_stream_put_u64()

ra8_err_t ra8_io_stream_put_u64 ( ra8_io_stream_t * s, uint64_t value )

nodiscard

Write value as unsigned 64-bit decimal ASCII without leading zeros.

Parameters

[in]	s	Bound stream handle.
[in]	value	Value to render.

Returns

Canonical stream status.

Return values

k_ra8_ok	Digits written.
k_ra8_err_null_ptr	s was null.
k_ra8_err_not_initialized	No sink is bound to s.
k_ra8_err_no_mem	A bounded sink could not accept the digits.

Precondition

A sink has been bound into s and the stream is idle.

Postcondition

Success writes the exact base-10 identity of value.

At most twenty ASCII digits are produced.

Note

Not thread-safe for concurrent use of one stream.

Since

0.1.0

Definition at line 176 of file ra8_io_stream.c.

References internal_validate(), k_ra8_io_dec_base, k_ra8_io_u64_max_digits, k_ra8_ok, and ra8_io_stream_write().

Referenced by internal_cli_reject_limit(), internal_put_padded_u64(), internal_put_u64(), internal_report_header(), internal_run_report(), and priv_mdl_stream_u64().

ra8_io_stream_putc()

ra8_err_t ra8_io_stream_putc ( ra8_io_stream_t * s, char c )

nodiscard

Write a single byte to the bound sink.

Parameters

[in]	s	Bound stream handle.
[in]	c	Byte to write.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Byte written.
k_ra8_err_null_ptr	s was NULL.
k_ra8_err_not_initialized	No sink is bound to s.
k_ra8_err_no_mem	A bounded sink was full.

Precondition

A sink has been bound into s.

The stream is idle.

Postcondition

On success one byte was appended to the sink.

No more than one byte is consumed.

Note

Not thread-safe with respect to the same stream.

Since

0.1.0

Definition at line 128 of file ra8_io_stream.c.

References internal_validate(), k_ra8_ok, and ra8_io_stream_write().

Referenced by internal_emit_match(), internal_log_byte(), internal_log_sink(), internal_put_padded_u64(), internal_report_row(), and priv_mdl_stream_repeat().

ra8_io_stream_puts()

ra8_err_t ra8_io_stream_puts ( ra8_io_stream_t * s, const char * str )

nodiscard

Write a NUL-terminated string (without the NUL) to the bound sink.

Scans up to a bounded maximum for the terminator (NASA Power-of-10 Rule 2), then writes that many bytes. An unterminated or overlong string is rejected; it is never silently truncated.

Parameters

[in]	s	Bound stream handle.
[in]	str	NUL-terminated string.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	String written.
k_ra8_err_null_ptr	s or str was NULL.
k_ra8_err_not_initialized	No sink is bound to s.
k_ra8_err_no_mem	A bounded sink could not accept all bytes.
k_ra8_err_invalid_size	No terminator appeared inside the scan bound.

Precondition

A sink has been bound into s.

str is NUL-terminated.

Postcondition

On success the sink consumed the string's bytes.

The terminating NUL is never written.

Note

Not thread-safe with respect to the same stream.

Since

0.1.0

Definition at line 138 of file ra8_io_stream.c.

References internal_validate(), k_ra8_err_invalid_size, k_ra8_io_puts_max, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_io_stream_write(), and s_tag.

Referenced by demo_print(), internal_cli_usage_network_options(), internal_demo_print(), internal_diagnostic(), internal_emit_match(), internal_prepare_args(), internal_prepare_credentials(), internal_put_text(), internal_report_header(), internal_report_row(), internal_run_report(), internal_swap_run_one(), internal_swap_uart_print(), internal_write_parts(), main(), priv_mdl_cli_put_parts(), priv_mdl_stream_text(), priv_viewer_output_capacity(), priv_viewer_output_error(), priv_viewer_output_index_error(), priv_viewer_output_open_error(), priv_viewer_output_opened(), priv_viewer_output_text(), priv_viewer_output_tile(), priv_viewer_output_usage(), and priv_viewer_output_wrote().

ra8_io_stream_write()

ra8_err_t ra8_io_stream_write ( ra8_io_stream_t * s, const uint8_t * buf, uint32_t len, uint32_t * out_written )

nodiscard

Write len bytes to the bound sink.

Forwards to the sink's write primitive. out_written (if non-NULL) receives the number of bytes the sink accepted, which may be less than len for a bounded sink (e.g. a full RAM buffer).

Parameters

[in]	s	Bound stream handle.
[in]	buf	Source bytes.
[in]	len	Number of bytes to write.
[out]	out_written	Bytes accepted by the sink, or NULL if not needed.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	All len bytes accepted.
k_ra8_err_null_ptr	s or buf was NULL.
k_ra8_err_not_initialized	No sink is bound to s.
k_ra8_err_no_mem	A bounded sink could not accept all bytes.
k_ra8_err_protocol_error	Backend reported an impossible count or success after a short write.

Precondition

A sink has been bound into s.

buf is readable for len bytes.

Postcondition

On success the sink has consumed all len bytes.

*out_written (when provided) holds the accepted byte count unless a backend published an impossible over-request count, in which case it is preserved and k_ra8_err_protocol_error is returned.

Note

Not thread-safe with respect to the same stream.

Since

0.1.0

Definition at line 94 of file ra8_io_stream.c.

References ra8_io_stream_t::ctx, ra8_io_stream_t::iface, internal_validate(), k_ra8_err_protocol_error, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_io_stream_iface::write.

Referenced by internal_io_log_byte(), internal_swap_replay_capture(), ra8_camera_codec_encode_to_stream(), ra8_io_stream_put_hex(), ra8_io_stream_put_u32(), ra8_io_stream_put_u64(), ra8_io_stream_putc(), and ra8_io_stream_puts().