RA8 PDM-IF audio-source backend implementation. More...

#include "ra8_audio_source_pdm.h"
#include <stdint.h>
#include <string.h>
#include "ra8_audio_internal.h"
#include "ra8_time.h"

Include dependency graph for ra8_audio_source_pdm.c:

Enumerations
enum	ra8_audio_pdm_alignment_t : uintptr_t { k_pdm_source_alignment_mask = 3U }

Functions
static ra8_err_t	internal_pdm_fill (uint8_t channel, int32_t *samples, uint32_t count, uint32_t attempts)
	Fill a sample span from the PDM FIFO.
static ra8_err_t	internal_pdm_get_info (void ctx, ra8_audio_source_info_t out_info)
	Report the initialized PDM source geometry.
static void	internal_pdm_stream_data (void ctx, const int32_t samples, uint32_t count)
	Assemble FIFO chunks into the caller's fixed-size audio frame.
static ra8_err_t	internal_pdm_capture (void ctx, const ra8_audio_buffer_t buffer, ra8_audio_frame_t *out_frame)
	Capture one fixed-size PDM frame by polling.
static ra8_err_t	internal_pdm_stop (void *ctx)
	Stop and deinitialize the PDM source.
static ra8_err_t	internal_pdm_stream_start (void ctx, const ra8_audio_buffer_t buffer, ra8_audio_frame_callback_t callback, void *callback_ctx)
	Bind persistent scratch and enable PDM FIFO interrupts.
static ra8_err_t	internal_pdm_validate_cfg (const ra8_audio_source_pdm_cfg_t cfg, uint32_t out_frame_bytes)
	Validate PDM source geometry and compute its frame size.
static ra8_err_t	internal_pdm_prepare_hardware (const ra8_audio_source_pdm_cfg_t *cfg)
	Initialize, settle, and prime one PDM hardware channel.
ra8_err_t	ra8_audio_source_pdm_init (ra8_audio_source_t source, ra8_audio_source_pdm_state_t state, const ra8_audio_source_pdm_cfg_t *cfg)
	Configure, start, settle, and bind one PDM audio source.

Variables
static const ra8_audio_source_iface_t	s_pdm_source_iface

Detailed Description

RA8 PDM-IF audio-source backend implementation.

Adapts bounded PDM polling and interrupt streams to the generic audio facade while retaining all buffers and mutable state with callers.

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_source_pdm.c.

Enumeration Type Documentation

◆ ra8_audio_pdm_alignment_t

enum ra8_audio_pdm_alignment_t : uintptr_t

Enumerator
k_pdm_source_alignment_mask	PCM-S32LE buffer alignment mask.

Definition at line 24 of file ra8_audio_source_pdm.c.

Function Documentation

◆ internal_pdm_capture()

ra8_err_t internal_pdm_capture	(	void *	ctx,
		const ra8_audio_buffer_t *	buffer,
		ra8_audio_frame_t *	out_frame )

static

Capture one fixed-size PDM frame by polling.

Fills the caller buffer and publishes the configured PCM geometry and timestamp.

Parameters

[in,out]	ctx	Initialized PDM source state.
[in]	buffer	Caller-owned aligned output buffer.
[out]	out_frame	Descriptor for the captured frame.

Returns: Repository error code.

Return values

k_ra8_ok	One complete frame was captured.
k_ra8_err_not_initialized	The source is not initialized.
k_ra8_err_invalid_size	The output buffer is too small.
k_ra8_err_invalid_arg	The output buffer is misaligned.

Precondition: buffer->data remains writable for the duration of capture.; The PDM channel was started and read-enabled during initialization.

Postcondition: On success, out_frame->data aliases the caller buffer.; On failure, no successful frame descriptor is published.

Note: FIFO and timeout errors are propagated from internal_pdm_fill.

Since: 0.1.0

Definition at line 162 of file ra8_audio_source_pdm.c.

References ra8_audio_buffer_t::capacity, ra8_audio_source_pdm_state_t::channel, ra8_audio_source_info_t::channels, ra8_audio_buffer_t::data, ra8_audio_source_info_t::format, ra8_audio_source_info_t::frame_bytes, ra8_audio_source_pdm_state_t::info, ra8_audio_source_pdm_state_t::initialized, internal_pdm_fill(), k_pdm_source_alignment_mask, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_ok, ra8_audio_source_pdm_state_t::poll_attempts, ra8_time_ms(), ra8_audio_source_info_t::sample_rate_hz, ra8_audio_source_info_t::samples_per_frame, and ra8_audio_source_info_t::valid_bits.

◆ internal_pdm_fill()

ra8_err_t internal_pdm_fill	(	uint8_t	channel,
		int32_t *	samples,
		uint32_t	count,
		uint32_t	attempts )

static

Fill a sample span from the PDM FIFO.

Performs a bounded number of HAL reads until the requested count is collected.

Parameters

[in]	channel	PDM hardware channel.
[out]	samples	Caller-owned destination sample span.
[in]	count	Number of samples required.
[in]	attempts	Maximum FIFO-read attempts.

Returns: Repository error code.

Return values

k_ra8_ok	The requested sample count was collected.
k_ra8_err_hw_timeout	The attempt budget expired first.

Precondition: samples addresses writable storage for count samples.; attempts is nonzero for a useful acquisition attempt.

Postcondition: On success, all count sample positions are initialized.; No samples beyond the requested span are written.

Note: HAL read errors are returned unchanged.

Since: 0.1.0

Definition at line 46 of file ra8_audio_source_pdm.c.

References k_ra8_err_hw_timeout, k_ra8_ok, and ra8_pdm_read().

Referenced by internal_pdm_capture(), and internal_pdm_prepare_hardware().

◆ internal_pdm_get_info()

ra8_err_t internal_pdm_get_info	(	void *	ctx,
		ra8_audio_source_info_t *	out_info )

static

Report the initialized PDM source geometry.

Copies cached configuration metadata without accessing PDM hardware.

Parameters

[in]	ctx	PDM source state supplied during initialization.
[out]	out_info	Destination for audio source metadata.

Returns: Repository error code.

Return values

k_ra8_ok	Metadata was copied successfully.
k_ra8_err_not_initialized	The source state is absent or inactive.

Precondition: ctx is null or points to a PDM source-state object.; out_info points to writable storage when the source is initialized.

Postcondition: On success, out_info equals the cached source information.; PDM hardware and state remain unchanged.

Note: The facade supplies a nonnull output pointer.

Since: 0.1.0

Definition at line 78 of file ra8_audio_source_pdm.c.

References ra8_audio_source_pdm_state_t::info, ra8_audio_source_pdm_state_t::initialized, k_ra8_err_not_initialized, k_ra8_ok, and RA8_INTERNAL.

◆ internal_pdm_prepare_hardware()

ra8_err_t internal_pdm_prepare_hardware ( const ra8_audio_source_pdm_cfg_t * cfg )

static

Initialize, settle, and prime one PDM hardware channel.

Initializes the HAL, applies channel configuration, starts capture, enables FIFO reads, and discards the requested settling samples.

Parameters

[in] cfg Validated source configuration.

Returns: Repository error code.

Return values

k_ra8_ok	The PDM channel is running and ready for capture.
other	Propagated HAL or bounded-read error.

Precondition: cfg passed internal_pdm_validate_cfg.; No other owner is using the selected PDM channel.

Postcondition: On success the selected channel remains started with reads enabled.; On failure initialized PDM hardware is stopped and deinitialized.

Note: Discard reads use the caller-provided bounded polling budget.

Since: 0.1.0

Definition at line 354 of file ra8_audio_source_pdm.c.

References ra8_audio_source_pdm_cfg_t::channel, ra8_audio_source_pdm_cfg_t::discard_samples, internal_pdm_fill(), k_ra8_ok, ra8_audio_source_pdm_cfg_t::pdm, ra8_audio_source_pdm_cfg_t::poll_attempts, ra8_delay_ms(), RA8_INTERNAL, ra8_pdm_configure(), ra8_pdm_deinit(), ra8_pdm_init(), ra8_pdm_read_enable(), ra8_pdm_start(), ra8_pdm_stop(), and ra8_audio_source_pdm_cfg_t::settle_ms.

Referenced by ra8_audio_source_pdm_init().

◆ internal_pdm_stop()

ra8_err_t internal_pdm_stop ( void * ctx )

static

Stop and deinitialize the PDM source.

Stops acquisition before releasing the shared PDM peripheral state.

Parameters

[in,out] ctx Initialized PDM source state.

Returns: Repository error code.

Return values

k_ra8_ok	Hardware stopped and deinitialized successfully.
k_ra8_err_not_initialized	The source is absent or inactive.

Precondition: ctx is null or points to retained PDM source state.; No caller starts a new stream concurrently.

Postcondition: On success, the state is marked uninitialized.; On stop failure, deinitialization is not attempted.

Note: HAL errors are returned unchanged.

Since: 0.1.0

Definition at line 212 of file ra8_audio_source_pdm.c.

References ra8_audio_source_pdm_state_t::channel, ra8_audio_source_pdm_state_t::initialized, k_ra8_err_not_initialized, k_ra8_ok, RA8_INTERNAL, ra8_pdm_deinit(), and ra8_pdm_stop().

◆ internal_pdm_stream_data()

void internal_pdm_stream_data	(	void *	ctx,
		const int32_t *	samples,
		uint32_t	count )

static

Assemble FIFO chunks into the caller's fixed-size audio frame.

Copies each interrupt span into persistent caller-owned assembly storage and publishes frames whenever the configured count is met.

Parameters

[in,out]	ctx	PDM source state.
[in]	samples	Borrowed signed samples from the HAL.
[in]	count	Sample count in samples.

Precondition: Called only while the source stream is active.; samples addresses at least count readable samples.

Postcondition: Every complete configured frame invokes the caller callback once.; Partial trailing samples remain buffered for the next interrupt.

Note: Runs in interrupt context and performs only bounded copies.

Since: 0.1.0

Definition at line 105 of file ra8_audio_source_pdm.c.

References ra8_audio_source_info_t::channels, ra8_audio_source_info_t::format, ra8_audio_source_info_t::frame_bytes, ra8_audio_source_pdm_state_t::info, memcpy(), RA8_INTERNAL, ra8_time_ms(), ra8_audio_source_info_t::sample_rate_hz, ra8_audio_source_info_t::samples_per_frame, ra8_audio_source_pdm_state_t::stream_callback, ra8_audio_source_pdm_state_t::stream_ctx, ra8_audio_source_pdm_state_t::stream_data, ra8_audio_source_pdm_state_t::stream_filled, ra8_audio_source_pdm_state_t::stream_timestamp_ms, ra8_audio_source_pdm_state_t::streaming, and ra8_audio_source_info_t::valid_bits.

Referenced by internal_pdm_stream_start().

◆ internal_pdm_stream_start()

ra8_err_t internal_pdm_stream_start	(	void *	ctx,
		const ra8_audio_buffer_t *	buffer,
		ra8_audio_frame_callback_t	callback,
		void *	callback_ctx )

static

Bind persistent scratch and enable PDM FIFO interrupts.

Records the callback context and delegates bounded FIFO delivery to the HAL.

Parameters

[in,out]	ctx	Initialized PDM source state.
[in]	buffer	Caller-owned aligned frame assembly buffer.
[in]	callback	Function invoked for each complete audio frame.
[in,out]	callback_ctx	Opaque context passed to callback.

Returns: Repository error code.

Return values

k_ra8_ok	Interrupt streaming started.
k_ra8_err_not_initialized	The source is absent or inactive.
k_ra8_err_exists	Streaming is already active.
k_ra8_err_invalid_arg	The assembly buffer is misaligned.

Precondition: buffer->data remains writable until the source is stopped.; callback remains callable until the source is stopped.

Postcondition: On success, the source is marked streaming.; On failure, retained stream pointers are cleared.

Note: The callback executes from the PDM interrupt path.

Since: 0.1.0

Definition at line 251 of file ra8_audio_source_pdm.c.

References ra8_audio_source_pdm_state_t::channel, ra8_audio_buffer_t::data, ra8_audio_source_pdm_state_t::initialized, internal_pdm_stream_data(), ra8_audio_source_pdm_state_t::irq_priority, k_pdm_source_alignment_mask, k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ok, RA8_INTERNAL, ra8_pdm_stream_enable(), ra8_audio_source_pdm_state_t::stream_callback, ra8_audio_source_pdm_state_t::stream_ctx, ra8_audio_source_pdm_state_t::stream_data, ra8_audio_source_pdm_state_t::stream_filled, ra8_audio_source_pdm_state_t::stream_timestamp_ms, and ra8_audio_source_pdm_state_t::streaming.

◆ internal_pdm_validate_cfg()

ra8_err_t internal_pdm_validate_cfg	(	const ra8_audio_source_pdm_cfg_t *	cfg,
		uint32_t *	out_frame_bytes )

static

Validate PDM source geometry and compute its frame size.

Checks every bounded configuration field and rejects a frame-size multiplication that cannot fit the public 32-bit byte count.

Parameters

[in]	cfg	Candidate source configuration.
[out]	out_frame_bytes	Computed PCM frame size on success.

Returns: Repository error code.

Return values

k_ra8_ok	Configuration geometry is valid.
k_ra8_err_invalid_arg	One bounded configuration field is invalid.
k_ra8_err_invalid_size	The frame byte count exceeds 32 bits.

Precondition: cfg points to a readable configuration.; out_frame_bytes points to writable storage.

Postcondition: On success out_frame_bytes contains the exact S32LE frame size.; The supplied configuration remains unchanged.

Note: This helper does not access PDM hardware.

Since: 0.1.0

Definition at line 310 of file ra8_audio_source_pdm.c.

References ra8_audio_source_pdm_cfg_t::channel, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, k_ra8_pdm_ch_count, ra8_audio_source_pdm_cfg_t::poll_attempts, RA8_INTERNAL, ra8_audio_source_pdm_cfg_t::sample_rate_hz, ra8_audio_source_pdm_cfg_t::samples_per_frame, and ra8_audio_source_pdm_cfg_t::valid_bits.

Referenced by ra8_audio_source_pdm_init().

◆ ra8_audio_source_pdm_init()

ra8_err_t ra8_audio_source_pdm_init	(	ra8_audio_source_t *	source,
		ra8_audio_source_pdm_state_t *	state,
		const ra8_audio_source_pdm_cfg_t *	cfg )

nodiscard

Configure, start, settle, and bind one PDM audio source.

Parameters

[out]	source	Generic source handle.
[out]	state	Caller-owned backend state.
[in]	cfg	PDM filter and fixed-frame policy.

Returns: Error code.

Return values

k_ra8_ok	Source is running and bound.
k_ra8_err_null_ptr	An argument was nullptr.
k_ra8_err_invalid_arg	Configuration is invalid.
other	Propagated PDM HAL error.

Precondition: PDM pins are routed and ra8_time_init has run.; source and state out-live all later operations.

Postcondition: On success no heap is used and captures return PCM-S32LE.; On error hardware is stopped/deinitialized on a best-effort basis.

Note: Not thread-safe with respect to the PDM-IF block.

Since: 0.1.0

Definition at line 384 of file ra8_audio_source_pdm.c.

References ra8_audio_source_pdm_cfg_t::channel, internal_pdm_prepare_hardware(), internal_pdm_validate_cfg(), ra8_audio_source_pdm_cfg_t::irq_priority, k_ra8_audio_format_pcm_s32le, k_ra8_err_null_ptr, k_ra8_ok, ra8_audio_source_pdm_cfg_t::poll_attempts, s_pdm_source_iface, ra8_audio_source_pdm_cfg_t::sample_rate_hz, ra8_audio_source_pdm_cfg_t::samples_per_frame, and ra8_audio_source_pdm_cfg_t::valid_bits.

Referenced by c6_cam_audio_start(), and pdm_demo_pdm_or_halt().

Variable Documentation

◆ s_pdm_source_iface

const ra8_audio_source_iface_t s_pdm_source_iface

static

Initial value:

                                                         = {
  .get_info     = internal_pdm_get_info,
  .capture      = internal_pdm_capture,
  .stream_start = internal_pdm_stream_start,
  .stop         = internal_pdm_stop,
}

Definition at line 286 of file ra8_audio_source_pdm.c.

Referenced by ra8_audio_source_pdm_init().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_audio_pdm_alignment_t

Function Documentation

◆ internal_pdm_capture()

◆ internal_pdm_fill()

◆ internal_pdm_get_info()

◆ internal_pdm_prepare_hardware()

◆ internal_pdm_stop()

◆ internal_pdm_stream_data()

◆ internal_pdm_stream_start()

◆ internal_pdm_validate_cfg()

◆ ra8_audio_source_pdm_init()

Variable Documentation

◆ s_pdm_source_iface