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

audio_stream_get_frag().

See

audio_stream_consume().

See

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

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

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

audio_stream_get_frag().

See

audio_stream_produce().

See

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

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

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

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

Applies parameters to the buffer.

Parameters

• buffer – Buffer.

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

Returns

0 if succeeded, error code otherwise.

static inline uint32_t audio_stream_frame_bytes(const struct audio_stream __sparse_cache *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 __sparse_cache *buf)

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

Parameters

buf – Component buffer.

Returns

Size of sample in bytes.

static inline uint32_t audio_stream_frame_align_get(const uint32_t byte_align, const uint32_t frame_align_req, uint32_t frame_size)

Return the frames that meet the align requirement of both byte_align and frame_align_req.

Parameters

• byte_align – Processing byte alignment requirement.

• frame_align_req – Processing frames alignment requirement.

• frame_size – Size of the frame in bytes.

Returns

frame number.

static inline void audio_stream_init_alignment_constants(const uint32_t byte_align, const uint32_t frame_align_req, struct audio_stream __sparse_cache *stream)

Set frame_align_shift and frame_align of stream according to byte_align and frame_align_req alignment requirement.

Once the channel number,frame size are determined，the frame_align and frame_align_shift are determined too. these two feature will be used in audio_stream_get_avail_frames_aligned to calculate the available frames. it should be called in component prepare or param functions only once before stream copy. if someone forgets to call this first, there would be unexampled error such as nothing is copied at all.

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 uint32_t audio_stream_period_bytes(const struct audio_stream __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *source, const struct audio_stream __sparse_cache *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 __sparse_cache *source, const struct audio_stream __sparse_cache *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 __sparse_cache *source, const struct audio_stream __sparse_cache *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 __sparse_cache *source, const struct audio_stream __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *buffer)

Resets the buffer.

Parameters

buffer – Buffer to reset.

static inline void audio_stream_init(struct audio_stream __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 int audio_stream_samples_without_wrap_s16(const struct audio_stream __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 __sparse_cache *source, uint32_t ioffset, struct audio_stream __sparse_cache *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 audio_stream_copy_from_linear(const void *linear_source, int ioffset, struct audio_stream __sparse_cache *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 __sparse_cache *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 __sparse_cache *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 audio_stream_fmt_conversion(enum ipc4_bit_depth depth, enum ipc4_bit_depth valid, enum sof_ipc_frame __sparse_cache *frame_fmt, enum sof_ipc_frame __sparse_cache *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.

enum sof_ipc_frame frame_fmt

Sample data format.

enum sof_ipc_frame valid_sample_fmt

uint32_t rate

Number of data frames per second [Hz].

uint16_t channels

Number of samples in each frame.

uint16_t frame_align

alignment limit of stream copy, this value indicates how many integer frames which can meet both byte align and frame align requirement.

it should be set in component prepare or param functions

uint16_t frame_align_shift

alignment limit of stream copy, alignment is the frame_align_shift-th power of 2 bytes.

it should be set in component prepare or param functions

bool overrun_permitted

indicates whether overrun is permitted

bool underrun_permitted

indicates whether underrun is permitted