Audio Stream API

Location: include/sof/audio/audio_stream.h

group audio_stream_api

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().
Return

Pointer to the sample.

Parameters

  • buffer: Buffer.

  • idx: Index of sample.

  • size: Size of sample in bytes.

Note

Components should call comp_update_buffer_consume().

See

audio_stream_get_frag().

See

audio_stream_consume().

See

comp_update_buffer_consume().

audio_stream_read_frag_s16(buffer, idx)

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

Return

Pointer to the sample.

See

audio_stream_get_frag().

Parameters

  • buffer: Buffer.

  • idx: Index of sample.

audio_stream_read_frag_s32(buffer, idx)

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

Return

Pointer to the sample.

See

audio_stream_get_frag().

Parameters

  • buffer: Buffer.

  • idx: Index of 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().
Return

Pointer to the space for sample.

Parameters

  • buffer: Buffer.

  • idx: Index of sample.

  • size: Size of sample in bytes.

Note

Components should call comp_update_buffer_produce().

See

audio_stream_get_frag().

See

audio_stream_produce().

See

comp_update_buffer_produce().

audio_stream_write_frag_s16(buffer, idx)

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

Return

Pointer to the space for sample.

See

audio_stream_get_frag().

Parameters

  • buffer: Buffer.

  • idx: Index of sample.

audio_stream_write_frag_s32(buffer, idx)

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

Return

Pointer to the space for sample.

See

audio_stream_get_frag().

Parameters

  • buffer: Buffer.

  • idx: Index of 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.

Return

Pointer to the sample.

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.

Functions

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

Applies parameters to the buffer.

Return

0 if succeeded, error code otherwise.

Parameters

  • buffer: Buffer.

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

static inline uint32_t audio_stream_frame_bytes(const struct audio_stream *buf)

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

Return

Period size in bytes.

Parameters

  • buf: Component buffer.

static inline uint32_t audio_stream_sample_bytes(const struct audio_stream *buf)

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

Return

Size of sample in bytes.

Parameters

  • buf: Component buffer.

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.

Return

Period size in bytes.

Parameters

  • buf: Component buffer.

  • frames: Number of processing frames.

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.

Return

Pointer, adjusted if necessary.

Parameters

  • buffer: Buffer accessed by the pointer.

  • ptr: Pointer

static inline uint32_t audio_stream_get_avail_bytes(const struct audio_stream *stream)

Calculates available data in bytes, handling underrun_permitted behaviour.

Return

amount of data available for processing in bytes

Parameters

  • stream: Stream pointer

static inline uint32_t audio_stream_get_avail_samples(const struct audio_stream *stream)

Calculates available data in samples, handling underrun_permitted behaviour.

Return

amount of data available for processing in samples

Parameters

  • stream: Stream pointer

static inline uint32_t audio_stream_get_avail_frames(const struct audio_stream *stream)

Calculates available data in frames, handling underrun_permitted behaviour.

Return

amount of data available for processing in frames

Parameters

  • stream: Stream pointer

static inline uint32_t audio_stream_get_free_bytes(const struct audio_stream *stream)

Calculates free space in bytes, handling overrun_permitted behaviour.

Return

amount of space free in bytes

Parameters

  • stream: Stream pointer

static inline uint32_t audio_stream_get_free_samples(const struct audio_stream *stream)

Calculates free space in samples, handling overrun_permitted behaviour.

Return

amount of space free in samples

Parameters

  • stream: Stream pointer

static inline uint32_t audio_stream_get_free_frames(const struct audio_stream *stream)

Calculates free space in frames, handling overrun_permitted behaviour.

Return

amount of space free in frames

Parameters

  • stream: Stream pointer

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.

Return

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

Return

1 if there is not enough free space in sink.

Return

-1 if there is not enough data in source.

Parameters

  • source: Source buffer.

  • sink: Sink buffer.

  • bytes: Number of bytes to copy.

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.

Return

Number of bytes.

Parameters

  • source: Source buffer.

  • sink: Sink buffer.

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.

Return

Number of frames.

Parameters

  • source: Source buffer.

  • sink: Sink buffer.

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_reset(struct audio_stream *buffer)

Resets the buffer.

Parameters

  • buffer: Buffer to reset.

static inline void audio_stream_init(struct audio_stream *buffer, void *buff_addr, uint32_t size)

Initializes the buffer with specified memory block and size.

Parameters

  • buffer: Buffer 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 and return minimum of calculated value and given bytes number.

Return

Number of data samples to buffer wrap or given samples number.

Parameters

  • source: Stream to get information from.

  • ptr: Read or write pointer from source

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.

Return

Number of data frames to buffer wrap.

Parameters

  • source: Stream to get information from.

  • ptr: Read or write pointer from source

static inline 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.

Return

number of processed samples.

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.

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.

Return

0 if there is enough free space in buffer.

Return

1 if there is not enough free space in buffer.

Parameters

  • buffer: Buffer.

  • bytes: Size of the fragment to write zero.

struct audio_stream
#include <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.

enum sof_ipc_frame frame_fmt

Sample data format.

uint32_t rate

Number of data frames per second [Hz].

uint16_t channels

Number of samples in each frame.

bool overrun_permitted

indicates whether overrun is permitted

bool underrun_permitted

indicates whether underrun is permitted