audio_stream.h

Go to the documentation of this file.

/* SPDX-License-Identifier: BSD-3-Clause
 *
 * Copyright(c) 2020 - 2023 Intel Corporation. All rights reserved.
 *
 * Author: Karol Trzcinski <karolx.trzcinski@linux.intel.com>
 */

 
#ifndef __SOF_AUDIO_AUDIO_STREAM_H__
#define __SOF_AUDIO_AUDIO_STREAM_H__
 
#include <sof/audio/format.h>
#include <sof/audio/sink_api.h>
#include <sof/audio/source_api.h>
#include <sof/compiler_attributes.h>
#include <rtos/panic.h>
#include <sof/math/numbers.h>
#include <sof/lib/dma.h>
#include <rtos/alloc.h>
#include <rtos/cache.h>
#include <ipc/stream.h>
#include <ipc4/base-config.h>
#include <module/audio/audio_stream.h>
 
#include <stdbool.h>
#include <stdint.h>


struct audio_stream {
    /* runtime data */
    uint32_t size;  
    uint32_t avail; 
    uint32_t free;  
    void *w_ptr;    
    void *r_ptr;    
    void *addr; 
    void *end_addr; 
    uint8_t byte_align_req;
    uint8_t frame_align_req;
 
 
    /* runtime stream params */
    struct sof_audio_stream_params runtime_stream_params;
};
 
/* A pointer to data in a ring buffer. Just for convenience to reduce the number of typical
 * processing function parameters: e.g., just 3 parameters (in, out ptr, and size) instead of 7.
 */
struct cir_buf_ptr {
    void *buf_start;
    void *buf_end;
    void *ptr;
};
 
void audio_stream_recalc_align(struct audio_stream *stream);
 
static inline void *audio_stream_get_rptr(const struct audio_stream *buf)
{
    return buf->r_ptr;
}
 
static inline void *audio_stream_get_wptr(const struct audio_stream *buf)
{
    return buf->w_ptr;
}
 
static inline void *audio_stream_get_end_addr(const struct audio_stream *buf)
{
    return buf->end_addr;
}
 
static inline void *audio_stream_get_addr(const struct audio_stream *buf)
{
    return buf->addr;
}
 
static inline uint32_t audio_stream_get_size(const struct audio_stream *buf)
{
    return buf->size;
}
 
static inline uint32_t audio_stream_get_avail(const struct audio_stream *buf)
{
    return buf->avail;
}
 
static inline uint32_t audio_stream_get_free(const struct audio_stream *buf)
{
    return buf->free;
}
 
static inline enum sof_ipc_frame audio_stream_get_frm_fmt(const struct audio_stream *buf)
{
    return buf->runtime_stream_params.frame_fmt;
}
 
static inline enum sof_ipc_frame audio_stream_get_valid_fmt(const struct audio_stream *buf)
{
    return buf->runtime_stream_params.valid_sample_fmt;
}
 
static inline uint32_t audio_stream_get_rate(const struct audio_stream *buf)
{
    return buf->runtime_stream_params.rate;
}
 
static inline uint32_t audio_stream_get_channels(const struct audio_stream *buf)
{
    return buf->runtime_stream_params.channels;
}
 
static inline bool audio_stream_get_underrun(const struct audio_stream *buf)
{
    return buf->runtime_stream_params.underrun_permitted;
}
 
static inline uint32_t audio_stream_get_buffer_fmt(const struct audio_stream *buf)
{
    return buf->runtime_stream_params.buffer_fmt;
}
 
static inline bool audio_stream_get_overrun(const struct audio_stream *buf)
{
    return buf->runtime_stream_params.overrun_permitted;
}
 
static inline void audio_stream_set_rptr(struct audio_stream *buf, void *val)
{
    buf->r_ptr = val;
}
 
static inline void audio_stream_set_wptr(struct audio_stream *buf, void *val)
{
    buf->w_ptr = val;
}
 
static inline void audio_stream_set_end_addr(struct audio_stream *buf, void *val)
{
    buf->end_addr = val;
}
 
static inline void audio_stream_set_addr(struct audio_stream *buf, void *val)
{
    buf->addr = val;
}
 
static inline void audio_stream_set_size(struct audio_stream *buf, uint32_t val)
{
    buf->size = val;
}
 
static inline void audio_stream_set_avail(struct audio_stream *buf, uint32_t val)
{
    buf->avail = val;
}
 
static inline void audio_stream_set_free(struct audio_stream *buf, uint32_t val)
{
    buf->free = val;
}
 
static inline void audio_stream_set_frm_fmt(struct audio_stream *buf,
                        enum sof_ipc_frame val)
{
    buf->runtime_stream_params.frame_fmt = val;
    audio_stream_recalc_align(buf);
}
 
static inline void audio_stream_set_valid_fmt(struct audio_stream *buf,
                          enum sof_ipc_frame val)
{
    buf->runtime_stream_params.valid_sample_fmt = val;
}
 
static inline void audio_stream_set_rate(struct audio_stream *buf, uint32_t val)
{
    buf->runtime_stream_params.rate = val;
}
 
static inline void audio_stream_set_channels(struct audio_stream *buf, uint16_t val)
{
    buf->runtime_stream_params.channels = val;
    audio_stream_recalc_align(buf);
}
 
static inline void audio_stream_set_underrun(struct audio_stream *buf,
                         bool underrun_permitted)
{
    buf->runtime_stream_params.underrun_permitted = underrun_permitted;
}
 
static inline void audio_stream_set_overrun(struct audio_stream *buf,
                        bool overrun_permitted)
{
    buf->runtime_stream_params.overrun_permitted = overrun_permitted;
}
 
static inline void audio_stream_set_buffer_fmt(struct audio_stream *buf,
                           uint32_t buffer_fmt)
{
    buf->runtime_stream_params.buffer_fmt = buffer_fmt;
}

#define audio_stream_read_frag(buffer, idx, size) \
    audio_stream_get_frag(buffer, (buffer)->r_ptr, idx, size)

#define audio_stream_read_frag_s16(buffer, idx) \
    audio_stream_get_frag(buffer, (buffer)->r_ptr, idx, sizeof(int16_t))

#define audio_stream_read_frag_s32(buffer, idx) \
    audio_stream_get_frag(buffer, (buffer)->r_ptr, idx, sizeof(int32_t))

#define audio_stream_write_frag(buffer, idx, size) \
    audio_stream_get_frag(buffer, (buffer)->w_ptr, idx, size)

#define audio_stream_write_frag_s16(buffer, idx) \
    audio_stream_get_frag(buffer, (buffer)->w_ptr, idx, sizeof(int16_t))

#define audio_stream_write_frag_s32(buffer, idx) \
    audio_stream_get_frag(buffer, (buffer)->w_ptr, idx, sizeof(int32_t))

#define audio_stream_get_frag(buffer, ptr, idx, sample_size) \
    audio_stream_wrap(buffer, (char *)(ptr) + ((idx) * (sample_size)))

static inline uint32_t audio_stream_frame_bytes(const struct audio_stream *buf)
{
    return get_frame_bytes(buf->runtime_stream_params.frame_fmt,
                   buf->runtime_stream_params.channels);
}

static inline uint32_t audio_stream_sample_bytes(const struct audio_stream *buf)
{
    return get_sample_bytes(buf->runtime_stream_params.frame_fmt);
}

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

static inline int audio_stream_set_params(struct audio_stream *buffer,
                      struct sof_ipc_stream_params *params)
{
    if (!params)
        return -EINVAL;
 
    buffer->runtime_stream_params.frame_fmt = (enum sof_ipc_frame)params->frame_fmt;
    buffer->runtime_stream_params.rate = params->rate;
    buffer->runtime_stream_params.channels = params->channels;
 
    audio_stream_recalc_align(buffer);
 
    return 0;
}

static inline uint32_t audio_stream_period_bytes(const struct audio_stream *buf, uint32_t frames)
{
    return frames * audio_stream_frame_bytes(buf);
}

static inline void *audio_stream_wrap(const struct audio_stream *buffer, void *ptr)
{
    if (ptr >= buffer->end_addr)
        ptr = (char *)buffer->addr +
            ((char *)ptr - (char *)buffer->end_addr);
 
    assert((intptr_t)ptr <= (intptr_t)buffer->end_addr);
 
    return ptr;
}

static inline void *audio_stream_rewind_wrap(const struct audio_stream *buffer, void *ptr)
{
    if (ptr < buffer->addr)
        ptr = (char *)buffer->end_addr - ((char *)buffer->addr - (char *)ptr);
 
    assert((intptr_t)ptr >= (intptr_t)buffer->addr);
 
    return ptr;
}

static inline uint32_t
audio_stream_get_avail_bytes(const struct audio_stream *stream)
{
    /*
     * In case of underrun-permitted stream, report buffer full instead of
     * empty. This way, any data present in such stream is processed at
     * regular pace, but buffer will never be seen as completely empty by
     * clients, and in turn will not cause underrun/XRUN.
     */
    if (stream->runtime_stream_params.underrun_permitted)
        return stream->avail != 0 ? stream->avail : stream->size;
 
    return stream->avail;
}

static inline uint32_t
audio_stream_get_avail_samples(const struct audio_stream *stream)
{
    return audio_stream_get_avail_bytes(stream) /
        audio_stream_sample_bytes(stream);
}

static inline uint32_t
audio_stream_get_avail_frames(const struct audio_stream *stream)
{
    return audio_stream_get_avail_bytes(stream) /
        audio_stream_frame_bytes(stream);
}

static inline uint32_t
audio_stream_get_free_bytes(const struct audio_stream *stream)
{
    /*
     * In case of overrun-permitted stream, report buffer empty instead of
     * full. This way, if there's any actual free space for data it is
     * processed at regular pace, but buffer will never be seen as
     * completely full by clients, and in turn will not cause overrun/XRUN.
     */
    if (stream->runtime_stream_params.overrun_permitted)
        return stream->free != 0 ? stream->free : stream->size;
 
    return stream->free;
}

static inline uint32_t
audio_stream_get_free_samples(const struct audio_stream *stream)
{
    return audio_stream_get_free_bytes(stream) /
        audio_stream_sample_bytes(stream);
}

static inline uint32_t
audio_stream_get_free_frames(const struct audio_stream *stream)
{
    return audio_stream_get_free_bytes(stream) /
        audio_stream_frame_bytes(stream);
}

static inline int audio_stream_can_copy_bytes(const struct audio_stream *source,
                          const struct audio_stream *sink,
                          uint32_t bytes)
{
    /* check for underrun */
    if (audio_stream_get_avail_bytes(source) < bytes)
        return -1;
 
    /* check for overrun */
    if (audio_stream_get_free_bytes(sink) < bytes)
        return 1;
 
    /* we are good to copy */
    return 0;
}

static inline uint32_t
audio_stream_get_copy_bytes(const struct audio_stream *source,
                const struct audio_stream *sink)
{
    uint32_t avail = audio_stream_get_avail_bytes(source);
    uint32_t free = audio_stream_get_free_bytes(sink);
 
    if (avail > free)
        return free;
    else
        return avail;
}

static inline uint32_t
audio_stream_avail_frames(const struct audio_stream *source,
              const struct audio_stream *sink)
{
    uint32_t src_frames = audio_stream_get_avail_frames(source);
    uint32_t sink_frames = audio_stream_get_free_frames(sink);
 
    return MIN(src_frames, sink_frames);
}

static inline uint32_t audio_stream_align_frames_round_down(const struct audio_stream *stream,
                                uint32_t frames)
{
    uint16_t align = stream->runtime_stream_params.align_frame_cnt;
 
    return ROUND_DOWN(frames, align);
}

static inline uint32_t audio_stream_align_frames_round_up(const struct audio_stream *stream,
                              uint32_t frames)
{
    uint16_t align = stream->runtime_stream_params.align_frame_cnt;
    uint32_t aligned_frames = ROUND_DOWN(frames, align);
 
    if (aligned_frames < frames)
        aligned_frames += align;
 
    return aligned_frames;
}

static inline uint32_t audio_stream_align_frames_round_nearest(const struct audio_stream *stream,
                                   uint32_t frames)
{
    uint16_t align = stream->runtime_stream_params.align_frame_cnt;
 
    return ROUND_DOWN(frames + (align >> 1), align);
}

static inline uint32_t
audio_stream_avail_frames_aligned(const struct audio_stream *source,
                  const struct audio_stream *sink)
{
    uint32_t src_frames = audio_stream_get_avail_frames(source);
    uint32_t sink_frames = audio_stream_get_free_frames(sink);
    uint32_t n = MIN(src_frames, sink_frames);
 
    return audio_stream_align_frames_round_down(source, n);
}

static inline void audio_stream_produce(struct audio_stream *buffer, uint32_t bytes)
{
    buffer->w_ptr = audio_stream_wrap(buffer,
                      (char *)buffer->w_ptr + bytes);
 
    /* "overwrite" old data in circular wrap case */
    if (bytes > audio_stream_get_free_bytes(buffer))
        buffer->r_ptr = buffer->w_ptr;
 
    /* calculate available bytes */
    if (buffer->r_ptr < buffer->w_ptr)
        buffer->avail = (char *)buffer->w_ptr - (char *)buffer->r_ptr;
    else if (buffer->r_ptr == buffer->w_ptr)
        buffer->avail = buffer->size; /* full */
    else
        buffer->avail = buffer->size -
            ((char *)buffer->r_ptr - (char *)buffer->w_ptr);
 
    /* calculate free bytes */
    buffer->free = buffer->size - buffer->avail;
}

static inline void audio_stream_consume(struct audio_stream *buffer, uint32_t bytes)
{
    buffer->r_ptr = audio_stream_wrap(buffer,
                      (char *)buffer->r_ptr + bytes);
 
    /* calculate available bytes */
    if (buffer->r_ptr < buffer->w_ptr)
        buffer->avail = (char *)buffer->w_ptr - (char *)buffer->r_ptr;
    else if (buffer->r_ptr == buffer->w_ptr)
        buffer->avail = 0; /* empty */
    else
        buffer->avail = buffer->size -
            ((char *)buffer->r_ptr - (char *)buffer->w_ptr);
 
    /* calculate free bytes */
    buffer->free = buffer->size - buffer->avail;
}
 
#ifdef __ZEPHYR__
static inline void audio_stream_sync_to_hw(struct audio_stream *stream,
                       const struct dma_status *dma_status)
{
    uintptr_t buf_start = (uintptr_t)audio_stream_get_addr(stream);
 
    /* Note: It is assumed here that dma_status values are reported as bytes. However,
     * this is actually platform-specific. Although unlikely, they could be, for example,
     * words on some particular platform, and changes should be made here to address
     * such case.
     */
 
    assert(dma_status->write_position < audio_stream_get_size(stream));
    assert(dma_status->read_position < audio_stream_get_size(stream));
    assert(dma_status->pending_length <= audio_stream_get_size(stream));
    assert(dma_status->free <= audio_stream_get_size(stream));
 
    audio_stream_set_wptr(stream, (void *)(buf_start + dma_status->write_position));
    audio_stream_set_rptr(stream, (void *)(buf_start + dma_status->read_position));
    audio_stream_set_avail(stream, dma_status->pending_length);
    audio_stream_set_free(stream, dma_status->free);
}
#endif  /* __ZEPHYR__ */

static inline void audio_stream_reset(struct audio_stream *buffer)
{
    /* reset read and write pointer to buffer bas */
    buffer->w_ptr = buffer->addr;
    buffer->r_ptr = buffer->addr;
 
    /* free space is buffer size */
    buffer->free = buffer->size;
 
    /* there are no avail samples at reset */
    buffer->avail = 0;
}

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

static inline void audio_stream_invalidate(struct audio_stream *buffer, uint32_t bytes)
{
    uint32_t head_size = bytes;
    uint32_t tail_size = 0;
 
    /* check for potential wrap */
    if ((char *)buffer->r_ptr + bytes > (char *)buffer->end_addr) {
        head_size = (char *)buffer->end_addr - (char *)buffer->r_ptr;
        tail_size = bytes - head_size;
    }
 
    dcache_invalidate_region((__sparse_force void __sparse_cache *)buffer->r_ptr, head_size);
    if (tail_size)
        dcache_invalidate_region((__sparse_force void __sparse_cache *)buffer->addr,
                     tail_size);
}

static inline void audio_stream_writeback(struct audio_stream *buffer, uint32_t bytes)
{
    uint32_t head_size = bytes;
    uint32_t tail_size = 0;
 
    /* check for potential wrap */
    if ((char *)buffer->w_ptr + bytes > (char *)buffer->end_addr) {
        head_size = (char *)buffer->end_addr - (char *)buffer->w_ptr;
        tail_size = bytes - head_size;
    }
 
    dcache_writeback_region((__sparse_force void __sparse_cache *)buffer->w_ptr, head_size);
    if (tail_size)
        dcache_writeback_region((__sparse_force void __sparse_cache *)buffer->addr,
                    tail_size);
}

static inline int
audio_stream_bytes_without_wrap(const struct audio_stream *source, const void *ptr)
{
    assert((intptr_t)source->end_addr >= (intptr_t)ptr);
    return (intptr_t)source->end_addr - (intptr_t)ptr;
}

static inline int
audio_stream_rewind_bytes_without_wrap(const struct audio_stream *source, const void *ptr)
{
    assert((intptr_t)ptr >= (intptr_t)source->addr);
    int to_begin = (intptr_t)ptr - (intptr_t)source->addr;
    return to_begin;
}

static inline uint32_t
*audio_stream_rewind_wptr_by_bytes(const struct audio_stream *source, const uint32_t bytes)
{
    void *wptr = audio_stream_get_wptr(source);
    int to_begin = audio_stream_rewind_bytes_without_wrap(source, wptr);
 
    assert((intptr_t)wptr >= (intptr_t)source->addr);
    assert((intptr_t)source->end_addr > (intptr_t)wptr);
 
    if (to_begin > bytes)
        return (uint32_t *)((intptr_t)wptr - bytes);
    else
        return (uint32_t *)((intptr_t)source->end_addr - (bytes - to_begin));
}

static inline int
audio_stream_samples_without_wrap_s16(const struct audio_stream *source, const void *ptr)
{
    int to_end = (int16_t *)source->end_addr - (int16_t *)ptr;
 
    assert((intptr_t)source->end_addr >= (intptr_t)ptr);
    return to_end;
}

static inline int
audio_stream_samples_without_wrap_s24(const struct audio_stream *source, const void *ptr)
{
    int to_end = (int32_t *)source->end_addr - (int32_t *)ptr;
 
    assert((intptr_t)source->end_addr >= (intptr_t)ptr);
    return to_end;
}

static inline int
audio_stream_samples_without_wrap_s32(const struct audio_stream *source, const void *ptr)
{
    int to_end = (int32_t *)source->end_addr - (int32_t *)ptr;
 
    assert((intptr_t)source->end_addr >= (intptr_t)ptr);
    return to_end;
}

static inline int cir_buf_bytes_without_wrap(const void *ptr, const void *buf_end)
{
    assert((intptr_t)buf_end >= (intptr_t)ptr);
    return (intptr_t)buf_end - (intptr_t)ptr;
}

static inline uint32_t
audio_stream_frames_without_wrap(const struct audio_stream *source, const void *ptr)
{
    uint32_t bytes = audio_stream_bytes_without_wrap(source, ptr);
    uint32_t frame_bytes = audio_stream_frame_bytes(source);
 
    return bytes / frame_bytes;
}

int audio_stream_copy(const struct audio_stream *source, uint32_t ioffset,
              struct audio_stream *sink, uint32_t ooffset, uint32_t 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);

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

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

static inline int audio_stream_set_zero(struct audio_stream *buffer, uint32_t bytes)
{
    uint32_t head_size = bytes;
    uint32_t tail_size = 0;
 
    /* check for overrun */
    if (audio_stream_get_free_bytes(buffer) < bytes)
        return 1;
 
    /* check for potential wrap */
    if ((char *)buffer->w_ptr + bytes > (char *)buffer->end_addr) {
        head_size = (char *)buffer->end_addr - (char *)buffer->w_ptr;
        tail_size = bytes - head_size;
    }
 
    memset(buffer->w_ptr, 0, head_size);
    if (tail_size)
        memset(buffer->addr, 0, tail_size);
 
    return 0;
}

static inline void cir_buf_set_zero(void *ptr, void *buf_addr, void *buf_end, uint32_t bytes)
{
    uint32_t head_size = bytes;
    uint32_t tail_size = 0;
 
    /* check for potential wrap */
    if ((char *)ptr + bytes > (char *)buf_end) {
        head_size = (char *)buf_end - (char *)ptr;
        tail_size = bytes - head_size;
    }
 
    memset(ptr, 0, head_size);
    if (tail_size)
        memset(buf_addr, 0, tail_size);
}
 
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)
{
    int ret = -EINVAL;
    *frame_fmt = SOF_IPC_FRAME_INVALID;
    *valid_fmt = SOF_IPC_FRAME_INVALID;
 
    switch (type) {
    case IPC4_TYPE_FLOAT:
#ifdef CONFIG_FORMAT_FLOAT
        if (depth == 32 && valid == 32) {
            *frame_fmt = SOF_IPC_FRAME_FLOAT;
            *valid_fmt = SOF_IPC_FRAME_FLOAT;
            ret = 0;
        }
#endif
        break;
    case IPC4_TYPE_MSB_INTEGER:
    case IPC4_TYPE_LSB_INTEGER:
    case IPC4_TYPE_SIGNED_INTEGER:
        if (depth == 24 && valid == 24) {
#ifdef CONFIG_FORMAT_S24_3LE
            *frame_fmt = SOF_IPC_FRAME_S24_3LE;
            *valid_fmt = SOF_IPC_FRAME_S24_3LE;
            ret = 0;
#endif
        } else {
            /* IPC4_DEPTH_16BIT (16) <---> SOF_IPC_FRAME_S16_LE (0)
             * IPC4_DEPTH_24BIT (24) <---> SOF_IPC_FRAME_S24_4LE (1)
             * IPC4_DEPTH_32BIT (32) <---> SOF_IPC_FRAME_S32_LE (2)
             */
            *frame_fmt = (enum sof_ipc_frame)((depth >> 3) - 2);
            *valid_fmt = (enum sof_ipc_frame)((valid >> 3) - 2);
            ret = 0;
        }
        break;
    case IPC4_TYPE_UNSIGNED_INTEGER:
#ifdef CONFIG_FORMAT_U8
        if (depth == 8 && valid == 8) {
            *frame_fmt = SOF_IPC_FRAME_U8;
            *valid_fmt = SOF_IPC_FRAME_U8;
            ret = 0;
        }
#endif /* CONFIG_FORMAT_U8 */
        break;
    case IPC4_TYPE_A_LAW:
#ifdef CONFIG_FORMAT_A_LAW
        if (depth == 8 && valid == 8) {
            *frame_fmt = SOF_IPC_FRAME_A_LAW;
            *valid_fmt = SOF_IPC_FRAME_A_LAW;
            ret = 0;
        }
#endif
        break;
    case IPC4_TYPE_MU_LAW:
#ifdef CONFIG_FORMAT_MU_LAW
        if (depth == 8 && valid == 8) {
            *frame_fmt = SOF_IPC_FRAME_MU_LAW;
            *valid_fmt = SOF_IPC_FRAME_MU_LAW;
            ret = 0;
        }
#endif
        break;
    }
    return ret;
}

 
#endif /* __SOF_AUDIO_AUDIO_STREAM_H__ */