ra8_audio.c File Reference

Validation and dispatch for the transport-neutral audio facade. More...

#include "ra8_audio.h"
#include <stdint.h>
#include "ra8_audio_internal.h"

Include dependency graph for ra8_audio.c:

Go to the source code of this file.

Functions
static uint32_t	internal_audio_container_bytes (ra8_audio_format_t format)
	Return the PCM container width in bytes.
ra8_err_t	ra8_audio_frame_validate (const ra8_audio_frame_t *frame)
	Validate one PCM frame view.
ra8_err_t	ra8_audio_source_get_info (ra8_audio_source_t *source, ra8_audio_source_info_t *out_info)
	Query a bound source's fixed output contract.
static ra8_err_t	internal_audio_frame_matches_info (const ra8_audio_frame_t *frame, const ra8_audio_source_info_t *info)
	Verify a captured frame matches its source metadata.
static ra8_err_t	internal_audio_capture_args_valid (const ra8_audio_source_t *source, const ra8_audio_buffer_t *buffer, ra8_audio_frame_t *out_frame)
	Validate capture arguments before touching source geometry.
ra8_err_t	ra8_audio_source_capture (ra8_audio_source_t *source, const ra8_audio_buffer_t *buffer, ra8_audio_frame_t *out_frame)
	Capture one fixed-size PCM frame into caller-owned storage.
ra8_err_t	ra8_audio_source_stream_start (ra8_audio_source_t *source, const ra8_audio_buffer_t *buffer, ra8_audio_frame_callback_t callback, void *ctx)
	Start asynchronous fixed-frame delivery into caller-owned scratch.
ra8_err_t	ra8_audio_source_stop (ra8_audio_source_t *source)
	Stop and release a bound source backend.

Detailed Description

Validation and dispatch for the transport-neutral audio facade.

Enforces PCM geometry and caller-owned-buffer contracts before dispatching capture, streaming, and stop operations to a backend.

Tag

[Ring 4 / Service] {World: NS}

Copyright

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

Since

0.1.0

Definition in file ra8_audio.c.

Function Documentation

internal_audio_capture_args_valid()

ra8_err_t internal_audio_capture_args_valid ( const ra8_audio_source_t * source, const ra8_audio_buffer_t * buffer, ra8_audio_frame_t * out_frame )

static

Validate capture arguments before touching source geometry.

Confirms every caller-owned pointer is non-null, the source is bound to a capture-capable interface, and the caller's buffer is usable. Zeroes out_frame once every pointer is known non-null, matching the failure contract of ra8_audio_source_capture itself.

Parameters

[in]	source	Candidate audio source handle.
[in]	buffer	Candidate caller-owned capture buffer.
[out]	out_frame	Candidate output frame descriptor; zeroed on success.

Returns

Repository error code.

Return values

k_ra8_ok	Every argument is present and the buffer is usable.
k_ra8_err_null_ptr	A required pointer, or the buffer's data, is null.
k_ra8_err_not_initialized	The source has no bound capture backend.

Precondition

source, buffer, and out_frame may be null; this function validates them.

No capture is in progress on source.

Postcondition

On success out_frame is zeroed.

Success guarantees source->iface->capture is callable.

Note

Not thread-safe; caller serializes access to source.

Since

0.1.0

Definition at line 161 of file ra8_audio.c.

References ra8_audio_buffer_t::capacity, ra8_audio_source_iface::capture, ra8_audio_buffer_t::data, ra8_audio_source_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and RA8_INTERNAL.

Referenced by ra8_audio_source_capture().

internal_audio_container_bytes()

uint32_t internal_audio_container_bytes ( ra8_audio_format_t format )

static

Return the PCM container width in bytes.

Maps each supported PCM storage format to its fixed byte width.

Parameters

[in]

format

Audio sample storage format to inspect.

Returns

Container width in bytes.

Return values

0	The format is not supported.

Precondition

format is a value representable by ra8_audio_format_t.

No audio source operation is in progress through this helper.

Postcondition

The supplied format value is unchanged.

No global or caller-owned state is modified.

Note

This reports storage width, not the number of valid sample bits.

Since

0.1.0

Definition at line 35 of file ra8_audio.c.

References k_ra8_audio_format_pcm_s16le, k_ra8_audio_format_pcm_s32le, and RA8_INTERNAL.

Referenced by ra8_audio_frame_validate().

internal_audio_frame_matches_info()

ra8_err_t internal_audio_frame_matches_info ( const ra8_audio_frame_t * frame, const ra8_audio_source_info_t * info )

static

Verify a captured frame matches its source metadata.

Compares byte size, sample geometry, rate, channel count, valid-bit width, and format as independent invariants.

Parameters

[in]	frame	Captured frame descriptor.
[in]	info	Source metadata returned before capture.

Returns

Repository error code.

Return values

k_ra8_ok	Every frame field matches the source metadata.
k_ra8_err_invalid_state	At least one field differs.

Precondition

Both pointers address readable descriptors.

The frame already passed ra8_audio_frame_validate.

Postcondition

Both descriptors remain unchanged.

Success proves the source honored its advertised geometry.

Note

The caller clears rejected output descriptors.

Since

0.1.0

Definition at line 119 of file ra8_audio.c.

References ra8_audio_frame_t::bytes, ra8_audio_frame_t::channels, ra8_audio_source_info_t::channels, ra8_audio_frame_t::format, ra8_audio_source_info_t::format, ra8_audio_source_info_t::frame_bytes, k_ra8_err_invalid_state, k_ra8_ok, RA8_INTERNAL, ra8_audio_frame_t::sample_count, ra8_audio_frame_t::sample_rate_hz, ra8_audio_source_info_t::sample_rate_hz, ra8_audio_source_info_t::samples_per_frame, ra8_audio_frame_t::valid_bits, and ra8_audio_source_info_t::valid_bits.

Referenced by ra8_audio_source_capture().

ra8_audio_frame_validate()

ra8_err_t ra8_audio_frame_validate ( const ra8_audio_frame_t * frame )

nodiscard

Validate one PCM frame view.

Parameters

[in]

frame

Candidate frame.

Returns

Error code.

Return values

k_ra8_ok	Frame metadata and byte coverage are valid.
k_ra8_err_null_ptr	frame or frame->data is nullptr.
k_ra8_err_invalid_arg	Format or scalar metadata is invalid.
k_ra8_err_invalid_size	Byte coverage does not match metadata.

Precondition

When non-NULL, frame->data is readable for frame->bytes bytes.

Postcondition

No state is modified.

Note

Thread-safe; reads only its argument.

Since

0.1.0

Definition at line 47 of file ra8_audio.c.

References ra8_audio_frame_t::bytes, ra8_audio_frame_t::channels, ra8_audio_frame_t::data, ra8_audio_frame_t::format, internal_audio_container_bytes(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_audio_frame_t::sample_count, ra8_audio_frame_t::sample_rate_hz, and ra8_audio_frame_t::valid_bits.

Referenced by ra8_audio_source_capture(), and ra8_audio_source_memory_init().

ra8_audio_source_capture()

ra8_err_t ra8_audio_source_capture ( ra8_audio_source_t * source, const ra8_audio_buffer_t * buffer, ra8_audio_frame_t * out_frame )

nodiscard

Capture one fixed-size PCM frame into caller-owned storage.

Parameters

[in,out]	source	Bound source handle.
[in]	buffer	Writable PCM storage.
[out]	out_frame	Receives a borrowed immutable frame view.

Returns

Error code.

Return values

k_ra8_ok	One complete frame captured.
k_ra8_err_null_ptr	An argument or buffer pointer was nullptr.
k_ra8_err_not_initialized	No source backend is bound.
k_ra8_err_invalid_size	Buffer cannot hold the source frame.
other	Propagated backend error.

Precondition

No other call uses source or buffer.

Postcondition

On success out_frame->data == buffer->data and validates.

On error out_frame is zeroed.

Note

Not thread-safe with respect to the same source or buffer.

Since

0.1.0

Definition at line 190 of file ra8_audio.c.

References ra8_audio_buffer_t::capacity, ra8_audio_source_iface::capture, ra8_audio_source_t::ctx, ra8_audio_buffer_t::data, ra8_audio_frame_t::data, ra8_audio_source_info_t::frame_bytes, ra8_audio_source_iface::get_info, ra8_audio_source_t::iface, internal_audio_capture_args_valid(), internal_audio_frame_matches_info(), k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, and ra8_audio_frame_validate().

Referenced by pdm_demo_run_window().

ra8_audio_source_get_info()

ra8_err_t ra8_audio_source_get_info ( ra8_audio_source_t * source, ra8_audio_source_info_t * out_info )

nodiscard

Query a bound source's fixed output contract.

Parameters

[in,out]	source	Bound source handle.
[out]	out_info	Receives source metadata.

Returns

Error code.

Return values

k_ra8_ok	Metadata returned.
k_ra8_err_null_ptr	An argument was nullptr.
k_ra8_err_not_initialized	No source backend is bound.
other	Propagated backend error.

Precondition

out_info points to writable storage.

Postcondition

On error out_info is zeroed.

Note

Not thread-safe with respect to the same source.

Since

0.1.0

Definition at line 85 of file ra8_audio.c.

References ra8_audio_source_t::ctx, ra8_audio_source_iface::get_info, ra8_audio_source_t::iface, k_ra8_err_not_initialized, and k_ra8_err_null_ptr.

ra8_audio_source_stop()

ra8_err_t ra8_audio_source_stop ( ra8_audio_source_t * source )

nodiscard

Stop and release a bound source backend.

Parameters

[in,out]

source

Bound source handle.

Returns

Error code.

Return values

k_ra8_ok	Backend stopped and handle cleared.
k_ra8_err_null_ptr	source was nullptr.
k_ra8_err_not_initialized	No source backend is bound.
other	Propagated backend error; the handle remains bound for retry.

Precondition

No capture is in progress.

Postcondition

On success source is reset to an unbound state.

Note

Not thread-safe with respect to the same source.

Since

0.1.0

Definition at line 265 of file ra8_audio.c.

References ra8_audio_source_t::ctx, ra8_audio_source_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and ra8_audio_source_iface::stop.

Referenced by c6_cam_audio_start().

ra8_audio_source_stream_start()

ra8_err_t ra8_audio_source_stream_start ( ra8_audio_source_t * source, const ra8_audio_buffer_t * buffer, ra8_audio_frame_callback_t callback, void * ctx )

nodiscard

Start asynchronous fixed-frame delivery into caller-owned scratch.

Parameters

[in,out]	source	Bound source handle.
[in]	buffer	Persistent writable frame storage.
[in]	callback	Complete-frame callback.
[in]	ctx	Opaque callback context; may be nullptr.

Returns

Error code.

Return values

k_ra8_ok	Streaming started.
k_ra8_err_null_ptr	Required argument or buffer pointer was nullptr.
k_ra8_err_not_initialized	Source is unbound.
k_ra8_err_not_supported	Backend has no streaming operation.
k_ra8_err_invalid_size	Buffer cannot hold one source frame.
other	Propagated backend error.

Precondition

buffer and its storage out-live the stream.

Postcondition

Complete frames are delivered until ra8_audio_source_stop.

Note

Callback execution context is backend-specific and must be respected.

Since

0.1.0

Definition at line 228 of file ra8_audio.c.

References ra8_audio_buffer_t::capacity, ra8_audio_source_t::ctx, ra8_audio_buffer_t::data, ra8_audio_source_info_t::frame_bytes, ra8_audio_source_iface::get_info, ra8_audio_source_t::iface, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, and ra8_audio_source_iface::stream_start.

Referenced by c6_cam_audio_start().