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
- See
- 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.
- 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.
- 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
- See
- 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.
- 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.
- 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
-
uint32_t size¶
-
audio_stream_read_frag(buffer, idx, size)¶