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

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.

Functions

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 *cir_buf_wrap(void *ptr, void *buf_addr, void *buf_end)

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

Parameters:

  • ptr – Pointer

  • buf_addr – Start address of the circular buffer.

  • buf_end – End address of the circular buffer.

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_avail_frames_aligned(const struct audio_stream *source, const struct audio_stream *sink)

Computes maximum number of frames aligned 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_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 int cir_buf_bytes_without_wrap(void *ptr, void *buf_end)

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

Parameters:

  • ptr – Read or write pointer og circular buffer.

  • buf_end – End address of circular buffer.

Returns:

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

static inline int cir_buf_samples_without_wrap_s32(void *ptr, void *buf_end)

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

Parameters:

  • ptr – Read or write pointer og circular buffer.

  • buf_end – End address of circular buffer.

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_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(void *src, void *src_addr, 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 void 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)
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.

uint8_t byte_align_req
uint8_t frame_align_req
struct sof_audio_stream_params runtime_stream_params