Audio Buffer & Stream Management API#

The Audio Buffer and Stream Management API governs intermediate audio data storage, circular stream pointer tracking, inter-component buffer negotiation, and lockless cross-core ring buffer streaming.

Buffer Subsystem Architecture#

SOF audio buffers decouple processing components, absorbing execution jitter and rate differences:

+-------------------+                               +-------------------+
| Upstream Copier   |                               | Downstream Mixer  |
| (Source Component)|                               | (Sink Component)  |
+---------+---------+                               +---------^---------+
          |                                                   |
          | audio_stream_produce()      audio_stream_consume()|
          v                                                   |
+---------+---------------------------------------------------+---------+
|                       struct comp_buffer                              |
|  - id, size, free, avail, flags                                       |
|  - source -> upstream comp_dev        sink -> downstream comp_dev    |
|  - stream (struct audio_stream)                                       |
|    * r_ptr, w_ptr (circular byte/frame pointers)                      |
|    * addr, end_addr (underlying audio memory buffer)                  |
+-----------------------------------------------------------------------+

Buffer Types & Usage Profiles#

  1. Interconnect Buffers (`struct comp_buffer`): Allocated in internal SRAM via buffer_alloc() or rballoc(). Connects adjacent components within a pipeline. Supports transaction callbacks (BUFF_CB_TYPE_*) to notify consumers when fresh audio data is written.

  2. Abstract Audio Buffers (`struct sof_audio_buffer`): Unified buffer descriptor providing polymorphic operations (struct audio_buffer_ops) across legacy component buffers (BUFFER_TYPE_LEGACY_BUFFER) and lockless ring buffers (BUFFER_TYPE_RING_BUFFER).

  3. Lockless Ring Buffers (`struct ring_buffer`): Designed for cross-core audio streaming (such as Inter-Domain Communication between Core 0 and secondary DSP cores). Lockless atomic read/write head updates eliminate spinlock contention between cores.

  4. Circular Audio Streams (`struct audio_stream`): Format-aware circular buffer tracking sample rates, channels, and bit depths, enabling sample-accurate and frame-accurate data production and consumption.

C API Reference#

group Audio Buffer & Stream Infrastructure

Interconnect buffers, circular stream buffers, abstract audio buffers, and lockless ring buffers.

Trace macros

struct tr_ctx buffer_tr#
buf_get_id(buf_ptr)#

Retrieves subid (comp id) from the buffer.

trace_buf_get_tr_ctx(buf_ptr)#

Retrieves trace context from the buffer.

buf_err(buf_ptr, __e, ...)#

Trace error message from buffer.

buf_warn(buf_ptr, __e, ...)#

Trace warning message from buffer.

buf_info(buf_ptr, __e, ...)#

Trace info message from buffer.

buf_dbg(buf_ptr, __e, ...)#

Trace debug message from buffer.

Buffer type identifiers

BUFFER_TYPE_LEGACY_BUFFER#

Legacy comp_buffer type (pipeline 1.0).

BUFFER_TYPE_RING_BUFFER#

Lockless async circular ring buffer type (cross-core).

Buffer callback types

BUFF_CB_TYPE_PRODUCE#

Callback triggered on buffer produce.

BUFF_CB_TYPE_CONSUME#

Callback triggered on buffer consume.

Buffer parameter update modes

BUFFER_UPDATE_IF_UNSET#

Update buffer parameters only if currently unset.

BUFFER_UPDATE_FORCE#

Force update buffer parameters regardless of current state.

Buffer parameter bitmasks

BUFF_PARAMS_FRAME_FMT#

Buffer parameter bitmask: frame format.

BUFF_PARAMS_BUFFER_FMT#

Buffer parameter bitmask: buffer format.

BUFF_PARAMS_RATE#

Buffer parameter bitmask: sample rate.

BUFF_PARAMS_CHANNELS#

Buffer parameter bitmask: channels count.

Buffer memory sharing usage

BUFFER_USAGE_SHARED#

Buffer used by multiple DSP cores and/or HW blocks.

BUFFER_USAGE_NOT_SHARED#

Buffer only used by one HW block.

Defines

audio_stream_read_frag(buffer, idx, size)#

Retrieves readable address of a sample at specified index (see versions of this macro specialized for various sample types).

Once the consumer finishes reading samples from the buffer, it should “commit” the operation and update the buffer state by calling audio_stream_consume().

See also

audio_stream_get_frag().

See also

audio_stream_consume().

See also

comp_update_buffer_consume().

Note

Components should call comp_update_buffer_consume().

Parameters:

  • buffer – Buffer.

  • idx – Index of sample.

  • size – Size of sample in bytes.

Returns:

Pointer to the sample.

audio_stream_read_frag_s16(buffer, idx)#

Retrieves readable address of a signed 16-bit sample at specified index.

See also

audio_stream_get_frag().

Parameters:

  • buffer – Buffer.

  • idx – Index of sample.

Returns:

Pointer to the sample.

audio_stream_read_frag_s32(buffer, idx)#

Retrieves readable address of a signed 32-bit sample at specified index.

See also

audio_stream_get_frag().

Parameters:

  • buffer – Buffer.

  • idx – Index of sample.

Returns:

Pointer to the sample.

audio_stream_write_frag(buffer, idx, size)#

Retrieves writeable address of a sample at specified index (see versions of this macro specialized for various sample types).

Once the producer finishes writing samples to the buffer, it should “commit” the operation and update the buffer state by calling audio_stream_produce().

See also

audio_stream_get_frag().

See also

audio_stream_produce().

See also

comp_update_buffer_produce().

Note

Components should call comp_update_buffer_produce().

Parameters:

  • buffer – Buffer.

  • idx – Index of sample.

  • size – Size of sample in bytes.

Returns:

Pointer to the space for sample.

audio_stream_write_frag_s16(buffer, idx)#

Retrieves writeable address of a signed 16-bit sample at specified index.

See also

audio_stream_get_frag().

Parameters:

  • buffer – Buffer.

  • idx – Index of sample.

Returns:

Pointer to the space for sample.

audio_stream_write_frag_s32(buffer, idx)#

Retrieves writeable address of a signed 32-bit sample at specified index.

See also

audio_stream_get_frag().

Parameters:

  • buffer – Buffer.

  • idx – Index of sample.

Returns:

Pointer to the space for sample.

audio_stream_get_frag(buffer, ptr, idx, sample_size)#

Retrieves address of sample (space for sample) at specified index within the buffer.

Index is interpreted as an offset relative to the specified pointer, rollover is ensured.

Parameters:

  • buffer – Circular buffer.

  • ptr – Pointer to start from, it may be either read or write pointer.

  • idx – Index of the sample.

  • sample_size – Size of the sample in bytes.

Returns:

Pointer to the sample.

buffer_from_list(ptr, dir)#

Retrieve enclosing comp_buffer from a list node depending on traversal direction.

Parameters:

  • ptr – [in] List item pointer.

  • dir – [in] Pipeline traversal direction (PPL_DIR_DOWNSTREAM or PPL_DIR_UPSTREAM).

Returns:

Pointer to enclosing struct comp_buffer.

buffer_set_cb(buffer, func, data, type)#

Set transaction callback on a component buffer.

Parameters:

  • buffer – [inout] Target component buffer.

  • func – [in] Callback function pointer.

  • data – [in] Callback user data.

  • type – [in] Callback trigger type (BUFF_CB_TYPE_*).

Functions

static inline struct sof_sink *audio_buffer_get_sink(struct sof_audio_buffer *buffer)#

Return pointer to sink interface of audio buffer.

Parameters:

  • buffer – [in] Pointer to audio buffer.

Returns:

Pointer to sink interface.

static inline struct sof_source *audio_buffer_get_source(struct sof_audio_buffer *buffer)#

Return pointer to source interface of audio buffer.

Parameters:

  • buffer – [in] Pointer to audio buffer.

Returns:

Pointer to source interface.

static inline bool audio_buffer_is_shared(struct sof_audio_buffer *buffer)#

Check if audio buffer is shared across cores.

Parameters:

  • buffer – [in] Pointer to audio buffer.

Returns:

True if shared, false otherwise.

static inline bool audio_buffer_hw_params_configured(struct sof_audio_buffer *buffer)#

Check if buffer hardware parameters are configured.

Parameters:

  • buffer – [in] Pointer to audio buffer.

Returns:

True if configured, false otherwise.

static inline void audio_buffer_set_hw_params_configured(struct sof_audio_buffer *buffer)#

Mark buffer hardware parameters as configured (state set to READY).

Parameters:

  • buffer – [inout] Pointer to audio buffer.

static inline void audio_buffer_reset_params(struct sof_audio_buffer *buffer)#

Reset buffer parameters state to initial.

Parameters:

  • buffer – [inout] Pointer to audio buffer.

static inline enum sof_audio_buffer_state audio_buffer_get_state(const struct sof_audio_buffer *buffer)#

Retrieve current buffer state.

Parameters:

  • buffer – [in] Pointer to audio buffer.

Returns:

Current buffer state (enum sof_audio_buffer_state).

static inline void audio_buffer_set_state(struct sof_audio_buffer *buffer, enum sof_audio_buffer_state state)#

Set buffer state.

Parameters:

  • buffer – [inout] Pointer to audio buffer.

  • state – [in] New state to assign.

static inline void audio_buffer_set_eos(struct sof_audio_buffer *buffer)#

Mark buffer state as end-of-stream (EOS).

Parameters:

  • buffer – [inout] Pointer to audio buffer.

static inline uint16_t audio_buffer_get_chmap(struct sof_audio_buffer *buffer, size_t index)#

Retrieve channel map value for a given channel index.

Parameters:

  • buffer – [in] Pointer to audio buffer.

  • index – [in] Channel index.

Returns:

Channel map value.

static inline void audio_buffer_set_chmap(struct sof_audio_buffer *buffer, size_t index, uint16_t value)#

Set channel map value for a given channel index.

Parameters:

  • buffer – [inout] Pointer to audio buffer.

  • index – [in] Channel index.

  • value – [in] Channel map value to set.

static inline struct sof_audio_stream_params *audio_buffer_get_stream_params(struct sof_audio_buffer *buffer)#

Retrieve pointer to runtime stream parameters.

Parameters:

  • buffer – [in] Pointer to audio buffer.

Returns:

Pointer to runtime stream parameters.

static inline struct sof_audio_buffer *sof_audio_buffer_from_sink(struct sof_sink *sink)#

Retrieve enclosing sof_audio_buffer from sink interface pointer.

NOTE: Ensure that sink is really embedded within a sof_audio_buffer; otherwise an invalid derived pointer will be returned.

Parameters:

  • sink – [in] Pointer to sink interface.

Returns:

Pointer to enclosing struct sof_audio_buffer.

static inline struct sof_audio_buffer *sof_audio_buffer_from_source(struct sof_source *source)#

Retrieve enclosing sof_audio_buffer from source interface pointer.

NOTE: Ensure that source is really embedded within a sof_audio_buffer; otherwise an invalid derived pointer will be returned.

Parameters:

  • source – [in] Pointer to source interface.

Returns:

Pointer to enclosing struct sof_audio_buffer.

void audio_buffer_init(struct sof_audio_buffer *buffer, uint32_t buffer_type, bool is_shared, const struct source_ops *source_ops, const struct sink_ops *sink_ops, const struct audio_buffer_ops *audio_buffer_ops, struct sof_audio_stream_params *audio_stream_params)#

Initialize audio buffer structure and virtual operation tables.

Parameters:

  • buffer – [inout] Pointer to audio buffer.

  • buffer_type – [in] Buffer type identifier (BUFFER_TYPE_*).

  • is_shared – [in] True if buffer is shared between cores.

  • source_ops – Pointer to source operations table.

  • sink_ops – Pointer to sink operations table.

  • audio_buffer_ops – Pointer to audio buffer operations table.

  • audio_stream_params – [inout] Pointer to audio stream parameters.

void audio_buffer_free(struct sof_audio_buffer *buffer)#

Free audio buffer and all allocated resources.

Parameters:

  • buffer – [inout] Pointer to audio buffer to free.

static inline void audio_buffer_reset(struct sof_audio_buffer *buffer)#

Reset all buffer data and positions leaving configuration intact.

Parameters:

  • buffer – [inout] Pointer to audio buffer.

int audio_buffer_source_set_ipc_params(struct sof_source *source, struct sof_ipc_stream_params *params, bool force_update)#

Set IPC stream parameters via source interface wrapper.

Parameters:

  • source – [inout] Pointer to source interface.

  • params – [in] Stream parameters to apply.

  • force_update – [in] If true, overwrite parameters unconditionally.

Returns:

0 on success, or negative error code on failure.

int audio_buffer_source_on_audio_format_set(struct sof_source *source)#

Audio format set callback via source interface wrapper.

Parameters:

  • source – [inout] Pointer to source interface.

Returns:

0 on success, or negative error code on failure.

int audio_buffer_source_set_alignment_constants(struct sof_source *source, const uint32_t byte_align, const uint32_t frame_align_req)#

Set alignment constraints via source interface wrapper.

Parameters:

  • source – [inout] Pointer to source interface.

  • byte_align – [in] Byte alignment requirement in bytes.

  • frame_align_req – [in] Frame alignment requirement in frames.

Returns:

0 on success, or negative error code on failure.

int audio_buffer_sink_set_ipc_params(struct sof_sink *sink, struct sof_ipc_stream_params *params, bool force_update)#

Set IPC stream parameters via sink interface wrapper.

Parameters:

  • sink – [inout] Pointer to sink interface.

  • params – [in] Stream parameters to apply.

  • force_update – [in] If true, overwrite parameters unconditionally.

Returns:

0 on success, or negative error code on failure.

int audio_buffer_sink_on_audio_format_set(struct sof_sink *sink)#

Audio format set callback via sink interface wrapper.

Parameters:

  • sink – [inout] Pointer to sink interface.

Returns:

0 on success, or negative error code on failure.

int audio_buffer_sink_set_alignment_constants(struct sof_sink *sink, const uint32_t byte_align, const uint32_t frame_align_req)#

Set alignment constraints via sink interface wrapper.

Parameters:

  • sink – [inout] Pointer to sink interface.

  • byte_align – [in] Byte alignment requirement in bytes.

  • frame_align_req – [in] Frame alignment requirement in frames.

Returns:

0 on success, or negative error code on failure.

uint32_t audio_buffer_sink_get_lft(struct sof_sink *sink)#

Get linear free time (LFT) duration in microseconds from sink interface wrapper.

Parameters:

  • sink – [in] Pointer to sink interface.

Returns:

Buffered duration in microseconds (us_in_buffer) calculated from source available data and sample rate.

void audio_stream_recalc_align(struct audio_stream *stream)#
static inline void *audio_stream_get_rptr(const struct audio_stream *buf)#
static inline void *audio_stream_get_wptr(const struct audio_stream *buf)#
static inline void *audio_stream_get_end_addr(const struct audio_stream *buf)#
static inline void *audio_stream_get_addr(const struct audio_stream *buf)#
static inline uint32_t audio_stream_get_size(const struct audio_stream *buf)#
static inline uint32_t audio_stream_get_avail(const struct audio_stream *buf)#
static inline uint32_t audio_stream_get_free(const struct audio_stream *buf)#
static inline enum sof_ipc_frame audio_stream_get_frm_fmt(const struct audio_stream *buf)#
static inline enum sof_ipc_frame audio_stream_get_valid_fmt(const struct audio_stream *buf)#
static inline uint32_t audio_stream_get_rate(const struct audio_stream *buf)#
static inline uint32_t audio_stream_get_channels(const struct audio_stream *buf)#
static inline bool audio_stream_get_underrun(const struct audio_stream *buf)#
static inline uint32_t audio_stream_get_buffer_fmt(const struct audio_stream *buf)#
static inline bool audio_stream_get_overrun(const struct audio_stream *buf)#
static inline void audio_stream_set_rptr(struct audio_stream *buf, void *val)#
static inline void audio_stream_set_wptr(struct audio_stream *buf, void *val)#
static inline void audio_stream_set_end_addr(struct audio_stream *buf, void *val)#
static inline void audio_stream_set_addr(struct audio_stream *buf, void *val)#
static inline void audio_stream_set_size(struct audio_stream *buf, uint32_t val)#
static inline void audio_stream_set_avail(struct audio_stream *buf, uint32_t val)#
static inline void audio_stream_set_free(struct audio_stream *buf, uint32_t val)#
static inline void audio_stream_set_frm_fmt(struct audio_stream *buf, enum sof_ipc_frame val)#
static inline void audio_stream_set_valid_fmt(struct audio_stream *buf, enum sof_ipc_frame val)#
static inline void audio_stream_set_rate(struct audio_stream *buf, uint32_t val)#
static inline void audio_stream_set_channels(struct audio_stream *buf, uint16_t val)#
static inline void audio_stream_set_underrun(struct audio_stream *buf, bool underrun_permitted)#
static inline void audio_stream_set_overrun(struct audio_stream *buf, bool overrun_permitted)#
static inline void audio_stream_set_buffer_fmt(struct audio_stream *buf, uint32_t buffer_fmt)#
static inline uint32_t audio_stream_frame_bytes(const struct audio_stream *buf)#

Calculates period size in bytes based on component stream’s parameters.

Parameters:

  • buf – Component buffer.

Returns:

Period size in bytes.

static inline uint32_t audio_stream_sample_bytes(const struct audio_stream *buf)#

Calculates sample size in bytes based on component stream’s parameters.

Parameters:

  • buf – Component buffer.

Returns:

Size of sample in bytes.

void audio_stream_set_align(const uint32_t byte_align, const uint32_t frame_align_req, struct audio_stream *stream)#

Set processing alignment requirements.

Sets the sample byte alignment and aligned frame count required for processing done on this stream. This function may be called at any time, the internal constants are recalculated if the frame/sample size changes.

See also

audio_stream_avail_frames_aligned().

Parameters:

  • byte_align – Processing byte alignment requirement.

  • frame_align_req – Processing frames alignment requirement.

  • stream – Sink or source stream structure which to be set.

static inline int audio_stream_set_params(struct audio_stream *buffer, struct sof_ipc_stream_params *params)#

Applies parameters to the buffer.

Parameters:

  • buffer – Audio stream buffer.

  • params – Parameters (frame format, rate, number of channels).

Returns:

0 if succeeded, error code otherwise.

static inline uint32_t audio_stream_period_bytes(const struct audio_stream *buf, uint32_t frames)#

Calculates period size in bytes based on component stream’s parameters.

Parameters:

  • buf – Component buffer.

  • frames – Number of processing frames.

Returns:

Period size in bytes.

static inline void *audio_stream_wrap(const struct audio_stream *buffer, void *ptr)#

Verifies the pointer and performs rollover when reached the end of the buffer.

Parameters:

  • buffer – Buffer accessed by the pointer.

  • ptr – Pointer

Returns:

Pointer, adjusted if necessary.

static inline void *audio_stream_rewind_wrap(const struct audio_stream *buffer, void *ptr)#

Verifies the pointer and performs rollover when reached the end of the buffer.

Parameters:

  • buffer – Buffer accessed by the pointer.

  • ptr – Pointer

Returns:

Pointer, adjusted if necessary.

static inline uint32_t audio_stream_get_avail_bytes(const struct audio_stream *stream)#

Calculates available data in bytes, handling underrun_permitted behaviour.

Parameters:

  • stream – Stream pointer

Returns:

amount of data available for processing in bytes

static inline uint32_t audio_stream_get_avail_samples(const struct audio_stream *stream)#

Calculates available data in samples, handling underrun_permitted behaviour.

Parameters:

  • stream – Stream pointer

Returns:

amount of data available for processing in samples

static inline uint32_t audio_stream_get_avail_frames(const struct audio_stream *stream)#

Calculates available data in frames, handling underrun_permitted behaviour.

Parameters:

  • stream – Stream pointer

Returns:

amount of data available for processing in frames

static inline uint32_t audio_stream_get_free_bytes(const struct audio_stream *stream)#

Calculates free space in bytes, handling overrun_permitted behaviour.

Parameters:

  • stream – Stream pointer

Returns:

amount of space free in bytes

static inline uint32_t audio_stream_get_free_samples(const struct audio_stream *stream)#

Calculates free space in samples, handling overrun_permitted behaviour.

Parameters:

  • stream – Stream pointer

Returns:

amount of space free in samples

static inline uint32_t audio_stream_get_free_frames(const struct audio_stream *stream)#

Calculates free space in frames, handling overrun_permitted behaviour.

Parameters:

  • stream – Stream pointer

Returns:

amount of space free in frames

static inline int audio_stream_can_copy_bytes(const struct audio_stream *source, const struct audio_stream *sink, uint32_t bytes)#

Verifies whether specified number of bytes can be copied from source buffer to sink buffer.

Parameters:

  • source – Source buffer.

  • sink – Sink buffer.

  • bytes – Number of bytes to copy.

Returns:

0 if there is enough data in source and enough free space in sink.

Returns:

1 if there is not enough free space in sink.

Returns:

-1 if there is not enough data in source.

static inline uint32_t audio_stream_get_copy_bytes(const struct audio_stream *source, const struct audio_stream *sink)#

Computes maximum number of bytes that can be copied from source buffer to sink buffer, verifying number of bytes available in source vs.

free space available in sink.

Parameters:

  • source – Source buffer.

  • sink – Sink buffer.

Returns:

Number of bytes.

static inline uint32_t audio_stream_avail_frames(const struct audio_stream *source, const struct audio_stream *sink)#

Computes maximum number of frames that can be copied from source buffer to sink buffer, verifying number of available source frames vs.

free space available in sink.

Parameters:

  • source – Source buffer.

  • sink – Sink buffer.

Returns:

Number of frames.

static inline uint32_t audio_stream_align_frames_round_down(const struct audio_stream *stream, uint32_t frames)#

Rounds down a frame count to meet the alignment constraint of the stream.

Parameters:

  • stream – Audio stream with alignment requirements set.

  • frames – Frame count to round down.

Returns:

Largest aligned frame count less than or equal to frames.

static inline uint32_t audio_stream_align_frames_round_up(const struct audio_stream *stream, uint32_t frames)#

Rounds up a frame count to meet the alignment constraint of the stream.

Parameters:

  • stream – Audio stream with alignment requirements set.

  • frames – Frame count to round up.

Returns:

Smallest aligned frame count greater than or equal to frames.

static inline uint32_t audio_stream_align_frames_round_nearest(const struct audio_stream *stream, uint32_t frames)#

Rounds to nearest a frame count to meet the alignment constraint of the stream.

Parameters:

  • stream – Audio stream with alignment requirements set.

  • frames – Frame count to round to nearest.

Returns:

Aligned frame count.

static inline uint32_t audio_stream_avail_frames_aligned(const struct audio_stream *source, const struct audio_stream *sink)#

Computes maximum number of frames aligned with source align criteria that can be copied from source buffer to sink buffer, verifying number of available source frames vs.

free space available in sink.

Parameters:

  • source – Buffer of source.

  • sink – Buffer of sink.

Returns:

Number of frames.

static inline void audio_stream_produce(struct audio_stream *buffer, uint32_t bytes)#

Updates the buffer state after writing to the buffer.

Parameters:

  • buffer – Buffer to update.

  • bytes – Number of written bytes.

static inline void audio_stream_consume(struct audio_stream *buffer, uint32_t bytes)#

Updates the buffer state after reading from the buffer.

Parameters:

  • buffer – Buffer to update.

  • bytes – Number of read bytes.

static inline void audio_stream_sync_to_hw(struct audio_stream *stream, const struct dma_status *dma_status)#

Replicates the hardware state of the DMA buffer as a struct audio_stream.

Parameters:

  • stream – Stream to update.

  • dma_status – DMA buffer hardware state (struct dma_status from Zephyr).

static inline void audio_stream_reset(struct audio_stream *buffer)#

Resets the buffer.

Parameters:

  • buffer – Buffer to reset.

void audio_stream_init(struct audio_stream *audio_stream, void *buff_addr, uint32_t size)#

Initializes the buffer with specified memory block and size.

Parameters:

  • audio_stream – the audio_stream a to initialize.

  • buff_addr – Address of the memory block to assign.

  • size – Size of the memory block in bytes.

static inline void audio_stream_invalidate(struct audio_stream *buffer, uint32_t bytes)#

Invalidates (in DSP d-cache) the buffer in range [r_ptr, r_ptr+bytes], with rollover if necessary.

Parameters:

  • buffer – Buffer.

  • bytes – Size of the fragment to invalidate.

static inline void audio_stream_writeback(struct audio_stream *buffer, uint32_t bytes)#

Writes back (from DSP d-cache) the buffer in range [w_ptr, w_ptr+bytes], with rollover if necessary.

Parameters:

  • buffer – Buffer.

  • bytes – Size of the fragment to write back.

static inline int audio_stream_bytes_without_wrap(const struct audio_stream *source, const void *ptr)#

Calculates numbers of bytes to buffer wrap.

Parameters:

  • source – Stream to get information from.

  • ptr – Read or write pointer from source

Returns:

Number of data samples to buffer wrap.

static inline int audio_stream_rewind_bytes_without_wrap(const struct audio_stream *source, const void *ptr)#

Calculates numbers of bytes to buffer wrap when reading stream backwards from current sample pointed by ptr towards begin.

Parameters:

  • source – Stream to get information from.

  • ptr – Read or write pointer from source

Returns:

Number of bytes to buffer wrap. For number of samples calculate need to add size of sample to returned bytes count.

static inline uint32_t *audio_stream_rewind_wptr_by_bytes(const struct audio_stream *source, const uint32_t bytes)#

Calculate position of write pointer to the position before the data was copied to source buffer.

Parameters:

  • source – Stream to get information from.

  • bytes – Number of bytes copied to source buffer.

Returns:

Previous position of the write pointer.

static inline int audio_stream_samples_without_wrap_s16(const struct audio_stream *source, const void *ptr)#

Calculates numbers of s16 samples to buffer wrap when buffer is read forward towards end address.

Parameters:

  • source – Stream to get information from.

  • ptr – Read or write pointer from source

Returns:

Number of data s16 samples until circular wrap need at end

static inline int audio_stream_samples_without_wrap_s24(const struct audio_stream *source, const void *ptr)#

Calculates numbers of s24 samples to buffer wrap when buffer is read forward towards end address.

Parameters:

  • source – Stream to get information from.

  • ptr – Read or write pointer from source

Returns:

Number of data s24 samples until circular wrap need at end

static inline int audio_stream_samples_without_wrap_s32(const struct audio_stream *source, const void *ptr)#

Calculates numbers of s32 samples to buffer wrap when buffer is read forward towards end address.

Parameters:

  • source – Stream to get information from.

  • ptr – Read or write pointer from source

Returns:

Number of data s32 samples until circular wrap need at end

static inline uint32_t audio_stream_frames_without_wrap(const struct audio_stream *source, const void *ptr)#

Calculates numbers of frames to buffer wrap and return minimum of calculated value.

Parameters:

  • source – Stream to get information from.

  • ptr – Read or write pointer from source

Returns:

Number of data frames to buffer wrap.

int audio_stream_copy(const struct audio_stream *source, uint32_t ioffset, struct audio_stream *sink, uint32_t ooffset, uint32_t samples)#

Copies data from source buffer to sink buffer.

Parameters:

  • source – Source buffer.

  • ioffset – Offset (in samples) in source buffer to start reading from.

  • sink – Sink buffer.

  • ooffset – Offset (in samples) in sink buffer to start writing to.

  • samples – Number of samples to copy.

Returns:

number of processed samples.

void cir_buf_copy(const void *src, const void *src_addr, const void *src_end, void *dst, void *dst_addr, void *dst_end, size_t byte_size)#

Copies data from one circular buffer to another circular buffer.

Parameters:

  • src – Source pointer of source circular buffer.

  • src_addr – Start address of source circular buffer.

  • src_end – End address of source circular buffer.

  • dst – Sink pointer of source circular buffer.

  • dst_addr – Start address of sink circular buffer

  • dst_end – End address of sink circular buffer.

  • byte_size – Number of bytes to copy.

void audio_stream_copy_from_linear(const void *linear_source, int ioffset, struct audio_stream *sink, int ooffset, unsigned int samples)#

Copies data from linear source buffer to circular sink buffer.

Parameters:

  • linear_source – Source buffer.

  • ioffset – Offset (in samples) in source buffer to start reading from.

  • sink – Sink buffer.

  • ooffset – Offset (in samples) in sink buffer to start writing to.

  • samples – Number of samples to copy.

void audio_stream_copy_to_linear(const struct audio_stream *source, int ioffset, void *linear_sink, int ooffset, unsigned int samples)#

Copies data from circular source buffer to linear sink buffer.

Parameters:

  • source – Source buffer.

  • ioffset – Offset (in samples) in source buffer to start reading from.

  • linear_sink – Sink buffer.

  • ooffset – Offset (in samples) in sink buffer to start writing to.

  • samples – Number of samples to copy.

static inline int audio_stream_set_zero(struct audio_stream *buffer, uint32_t bytes)#

Writes zeros in range [w_ptr, w_ptr+bytes], with rollover if necessary.

Parameters:

  • buffer – Buffer.

  • bytes – Size of the fragment to write zero.

Returns:

0 if there is enough free space in buffer.

Returns:

1 if there is not enough free space in buffer.

static inline void cir_buf_set_zero(void *ptr, void *buf_addr, void *buf_end, uint32_t bytes)#

Writes zeros to circular buffer in range [ptr, ptr+bytes] with rollover if necessary.

Parameters:

  • ptr – Pointer inside circular biffer to start writing from.

  • buf_addr – Start of the circular buffer.

  • buf_end – End of the circular buffer.

  • bytes – Size of the fragment to write zeros.

static inline int audio_stream_fmt_conversion(enum ipc4_bit_depth depth, enum ipc4_bit_depth valid, enum sof_ipc_frame *frame_fmt, enum sof_ipc_frame *valid_fmt, enum ipc4_sample_type type)#
static inline struct comp_dev *comp_buffer_get_source_component(const struct comp_buffer *buffer)#

Get component providing data to the buffer.

Parameters:

  • buffer – [in] Interconnect buffer.

Returns:

Pointer to source component device, or NULL if none.

static inline struct comp_dev *comp_buffer_get_sink_component(const struct comp_buffer *buffer)#

Get component consuming data from the buffer.

Parameters:

  • buffer – [in] Interconnect buffer.

Returns:

Pointer to sink component device, or NULL if none.

static inline void comp_buffer_set_source_component(struct comp_buffer *buffer, struct comp_dev *comp)#

Set component providing data to the buffer.

Parameters:

  • buffer – [inout] Interconnect buffer.

  • comp – [in] Source component device.

static inline void comp_buffer_set_sink_component(struct comp_buffer *buffer, struct comp_dev *comp)#

Set component consuming data from the buffer.

Parameters:

  • buffer – [inout] Interconnect buffer.

  • comp – [in] Sink component device.

static inline void comp_buffer_reset_source_list(struct comp_buffer *buffer)#

Reset buffer source list node.

Parameters:

  • buffer – [inout] Interconnect buffer.

static inline void comp_buffer_reset_sink_list(struct comp_buffer *buffer)#

Reset buffer sink list node.

Parameters:

  • buffer – [inout] Interconnect buffer.

struct comp_buffer *buffer_alloc(struct mod_alloc_ctx *alloc, size_t size, uint32_t flags, uint32_t align, bool is_shared)#

Allocate a pipeline component audio buffer with explicit size and alignment.

Parameters:

  • alloc – [inout] Allocation context (heap and optional vregion).

  • size – [in] Required buffer capacity in bytes.

  • flags – [in] Memory allocation flags (SOF_MEM_FLAG_…).

  • align – [in] Memory alignment requirement in bytes.

  • is_shared – [in] True if the buffer memory is shared across processing domains.

Returns:

Pointer to allocated comp_buffer, or NULL on failure.

struct comp_buffer *buffer_alloc_range(struct mod_alloc_ctx *alloc, size_t preferred_size, size_t minimum_size, uint32_t flags, uint32_t align, bool is_shared)#

Allocate a pipeline component buffer with an elastic size range.

Parameters:

  • alloc – [inout] Allocation context.

  • preferred_size – [in] Desired optimal buffer capacity in bytes.

  • minimum_size – [in] Minimum acceptable buffer capacity in bytes.

  • flags – [in] Memory allocation flags (SOF_MEM_FLAG_…).

  • align – [in] Memory alignment requirement in bytes.

  • is_shared – [in] True if the buffer memory is shared across processing domains.

Returns:

Pointer to allocated comp_buffer, or NULL on failure.

struct comp_buffer *buffer_new(struct mod_alloc_ctx *alloc, const struct sof_ipc_buffer *desc, bool is_shared)#

Instantiate a pipeline component buffer from an IPC configuration descriptor.

Parameters:

  • alloc – [inout] Allocation context.

  • desc – [in] IPC buffer descriptor containing size, flags, and configuration.

  • is_shared – [in] True if the buffer memory is shared across processing domains.

Returns:

Pointer to newly instantiated comp_buffer, or NULL on failure.

int buffer_set_size(struct comp_buffer *buffer, uint32_t size, uint32_t alignment)#

Resize an existing pipeline component buffer.

Parameters:

  • buffer – [inout] Pointer to comp_buffer to resize.

  • size – [in] New buffer capacity in bytes.

  • alignment – [in] Required memory alignment in bytes.

Returns:

0 on success, or negative error code on failure.

int buffer_set_size_range(struct comp_buffer *buffer, size_t preferred_size, size_t minimum_size, uint32_t alignment)#

Resize a pipeline component buffer within a preferred-to-minimum range.

Parameters:

  • buffer – [inout] Pointer to comp_buffer to resize.

  • preferred_size – [in] Desired optimal buffer capacity in bytes.

  • minimum_size – [in] Minimum acceptable buffer capacity in bytes.

  • alignment – [in] Required memory alignment in bytes.

Returns:

0 on success, or negative error code on failure.

static inline struct comp_buffer *comp_buffer_get_from_source(struct sof_source *source)#

Retrieve enclosing comp_buffer from an audio source interface pointer.

Parameters:

  • source – [in] Pointer to audio source interface.

Returns:

Pointer to enclosing struct comp_buffer.

static inline struct comp_buffer *comp_buffer_get_from_sink(struct sof_sink *sink)#

Retrieve enclosing comp_buffer from an audio sink interface pointer.

Parameters:

  • sink – [in] Pointer to audio sink interface.

Returns:

Pointer to enclosing struct comp_buffer.

static inline void buffer_free(struct comp_buffer *buffer)#

Free an interconnect component buffer and its underlying memory.

Parameters:

  • buffer – [inout] Component buffer to free.

void buffer_zero(struct comp_buffer *buffer)#

Zero-fill the entire payload of an interconnect buffer.

Parameters:

  • buffer – [inout] Component buffer to zero.

void comp_update_buffer_produce(struct comp_buffer *buffer, uint32_t bytes)#

Notify buffer that audio data has been produced by a component.

Parameters:

  • buffer – [inout] Component buffer written to.

  • bytes – [in] Number of bytes produced.

void comp_update_buffer_consume(struct comp_buffer *buffer, uint32_t bytes)#

Notify buffer that audio data has been consumed by a component.

Parameters:

  • buffer – [inout] Component buffer read from.

  • bytes – [in] Number of bytes consumed.

int buffer_set_params(struct comp_buffer *buffer, struct sof_ipc_stream_params *params, bool force_update)#

Set audio stream parameters on a component buffer.

Parameters:

  • buffer – [inout] Component buffer to configure.

  • params – [in] Stream parameters to apply.

  • force_update – [in] If true, overwrite existing parameters unconditionally.

Returns:

0 on success, or negative error code on failure.

bool buffer_params_match(struct comp_buffer *buffer, struct sof_ipc_stream_params *params, uint32_t flag)#

Test if buffer stream parameters match requested parameters.

Parameters:

  • buffer – [in] Component buffer to check.

  • params – [in] Stream parameters to compare.

  • flag – [in] Bitmask specifying which parameters to check (BUFF_PARAMS_*).

Returns:

True if matching, false otherwise.

static inline void buffer_stream_invalidate(struct comp_buffer *buffer, uint32_t bytes)#

Invalidate cache for a shared buffer stream if incoherent.

Parameters:

  • buffer – [inout] Component buffer.

  • bytes – [in] Number of bytes to invalidate.

static inline void buffer_stream_writeback(struct comp_buffer *buffer, uint32_t bytes)#

Write back cache for a shared buffer stream if incoherent.

Parameters:

  • buffer – [in] Component buffer.

  • bytes – [in] Number of bytes to write back.

int buffer_attach(struct comp_buffer *buffer, struct list_item *head, int dir)#

Attach a new buffer at the beginning of a component buffer list.

Locking: Must be called with interrupts disabled (or userspace LL system mutex held). The caller takes care to protect list heads. “head” must really be the head of the list, not a list node within another buffer, as its cache is not synchronized and must not be embedded in an object using the coherent API.

Parameters:

  • buffer – [inout] Component buffer to attach.

  • head – [inout] List head to prepend buffer to.

  • dir – [in] Traversal direction (PPL_DIR_DOWNSTREAM or PPL_DIR_UPSTREAM).

Returns:

0 on success, or -EALREADY if the buffer is already linked in this direction.

void buffer_detach(struct comp_buffer *buffer, struct list_item *head, int dir)#

Detach a buffer from anywhere in a component buffer list.

Locking: Must be called with interrupts disabled (or userspace LL system mutex held). “head” is the head of the list, assumed not to require cache synchronization. The caller takes care to protect list heads.

Parameters:

  • buffer – [inout] Component buffer to detach.

  • head – [inout] List head buffer is attached to.

  • dir – [in] Traversal direction (PPL_DIR_DOWNSTREAM or PPL_DIR_UPSTREAM).

static inline struct comp_dev *buffer_get_comp(struct comp_buffer *buffer, int dir)#

Get component connected to buffer in specified traversal direction.

Parameters:

  • buffer – [in] Component buffer.

  • dir – [in] Traversal direction (PPL_DIR_DOWNSTREAM or PPL_DIR_UPSTREAM).

Returns:

Pointer to connected component device.

static inline uint32_t buffer_pipeline_id(const struct comp_buffer *buffer)#

Retrieve pipeline ID associated with a component buffer.

Parameters:

  • buffer – [in] Component buffer.

Returns:

Pipeline ID.

static inline void buffer_init_stream(struct comp_buffer *buffer, size_t size)#

Initialize circular stream buffer descriptor for a component buffer.

Parameters:

  • buffer – [inout] Component buffer to initialize stream for.

  • size – [in] Capacity of the circular stream in bytes.

struct ring_buffer *ring_buffer_create(struct comp_dev *dev, size_t min_available, size_t min_free_space, bool is_shared, uint32_t id)#

Create and allocate a lockless async circular ring buffer.

Parameters:

  • dev – [inout] Pointer to component device creating this buffer.

  • min_available – [in] Minimum data available required by source API consumer.

  • min_free_space – [in] Minimum buffer space required by sink API producer.

  • is_shared – [in] True if buffer memory is shared across processing cores.

  • id – [in] Stream identifier accessible via sink/source interface.

Returns:

Pointer to newly allocated ring_buffer, or NULL on failure.

struct audio_buffer_ops#
#include <src/include/sof/audio/audio_buffer.h>

Audio buffer virtual operations table.

Public Members

void (*free)(struct sof_audio_buffer *buffer)#

Free all structures allocated by buffer implementation and the buffer itself.

MANDATORY: audio_buffer_free() invokes this callback unconditionally.

Param buffer:

[inout] Buffer to free.

void (*reset)(struct sof_audio_buffer *buffer)#

Clean all buffer data and reset positions to initial state, keeping configuration.

OPTIONAL: procedure is to be called only when buffer is not in use.

Param buffer:

[inout] Buffer to reset.

int (*on_audio_format_set)(struct sof_audio_buffer *buffer)#

Notification callback invoked on audio format modification.

Param buffer:

[inout] Buffer whose format changed.

Retval 0:

On success.

Retval negative:

If new parameters are not supported.

int (*audio_set_ipc_params)(struct sof_audio_buffer *buffer, struct sof_ipc_stream_params *params, bool force_update)#

Configure IPC stream parameters on buffer.

Param buffer:

[inout] Buffer to configure.

Param params:

[in] Stream parameters to apply.

Param force_update:

[in] If true, overwrite parameters unconditionally.

Return:

0 on success, negative error code on failure.

int (*set_alignment_constants)(struct sof_audio_buffer *buffer, const uint32_t byte_align, const uint32_t frame_align_req)#

Configure alignment constraints on buffer.

Param buffer:

[inout] Buffer to configure.

Param byte_align:

[in] Byte alignment requirement in bytes.

Param frame_align_req:

[in] Frame alignment requirement in frames.

Return:

0 on success, negative error code on failure.

struct sof_audio_buffer#
#include <src/include/sof/audio/audio_buffer.h>

Base class for all audio buffers.

All audio buffers must inherit from it.

Public Members

CORE_CHECK_STRUCT_FIELD
uint32_t buffer_type#

Type of the buffer (BUFFER_TYPE_*).

bool is_shared#

Buffer structure is shared between 2 cores.

struct sof_audio_stream_params *audio_stream_params#

Pointer to effective runtime stream parameters.

struct sof_source _source_api#

Source API interface handler.

struct sof_sink _sink_api#

Sink API interface handler.

const struct audio_buffer_ops *ops#

Virtual methods table.

bool walking#

Indicates if the buffer is being walked in pipeline graph.

struct mod_alloc_ctx *alloc#

Allocation context.

struct audio_stream#
#include <src/include/sof/audio/audio_stream.h>

Audio stream is a circular buffer aware of audio format of the data in the buffer so provides API for reading and writing not only bytes, but also samples and frames.

Audio stream does not perform any memory allocations. A client (a component buffer or dma) must allocate the memory for the underlying data buffer and provide it to the initialization routine.

Once the client is done with reading/writing the data, it must commit the consumption/production and update the buffer state by calling audio_stream_consume()/audio_stream_produce() (just a single call following series of reads/writes).

Public Members

uint32_t size#

Runtime buffer size in bytes (period multiple).

uint32_t avail#

Available bytes for reading.

uint32_t free#

Free bytes for writing.

void *w_ptr#

Buffer write pointer.

void *r_ptr#

Buffer read position.

void *addr#

Buffer base address.

void *end_addr#

Buffer end address.

uint8_t byte_align_req#
uint8_t frame_align_req#
struct sof_audio_stream_params runtime_stream_params#
struct cir_buf_ptr#
#include <src/include/sof/audio/audio_stream.h>

Public Members

void *buf_start#
void *buf_end#
void *ptr#
struct comp_buffer#
#include <src/include/sof/audio/buffer.h>

Audio component interconnect buffer connecting two pipeline components.

Public Members

struct sof_audio_buffer audio_buffer#

Unified audio buffer base class.

struct audio_stream stream#

Legacy audio stream representation.

uint32_t flags#

Buffer flags.

uint32_t core#

DSP core ID managing this buffer.

struct tr_ctx tctx#

Trace context.

struct comp_dev *source#

Source component feeding this buffer.

struct comp_dev *sink#

Sink component consuming from this buffer.

struct list_item source_list#

List node in source component’s buffer list.

struct list_item sink_list#

List node in sink component’s buffer list.

struct list_item buffers_list#

List of buffers used in raw data processing.

struct buffer_cb_transact#
#include <src/include/sof/audio/buffer.h>

Transaction descriptor passed to buffer probe callbacks.

Public Members

struct comp_buffer *buffer#

Buffer being transacted.

uint32_t transaction_amount#

Number of bytes transacted.

void *transaction_begin_address#

Starting address of transaction.

struct ring_buffer#
#include <src/include/sof/audio/ring_buffer.h>

Lockless asynchronous circular ring buffer structure.

Public Members

struct sof_audio_buffer audio_buffer#

Embedded audio buffer base structure.

size_t data_buffer_size#

Total allocated data buffer capacity in bytes.

uint8_t *_data_buffer#

Pointer to circular data buffer memory.

size_t _write_offset#

Producer write offset in bytes.

size_t _read_offset#

Consumer read offset in bytes.

On this page