generic.h

Go to the documentation of this file.

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright(c) 2020 - 2023 Intel Corporation. All rights reserved.
 *
 *
 * \file generic.h
 * \brief Generic Module API header file
 * \author Marcin Rajwa <marcin.rajwa@linux.intel.com>
 * \author Adrian Warecki <adrian.warecki@intel.com>
 *
 */
 
#ifndef __SOF_AUDIO_MODULE_GENERIC__
#define __SOF_AUDIO_MODULE_GENERIC__
 
#include <rtos/mutex.h>
#include <sof/objpool.h>
#include <sof/ut.h>
#include <sof/audio/component.h>
#include <sof/audio/sink_api.h>
#include <sof/audio/source_api.h>
#include <sof/ipc/msg.h>
#include "module_interface.h"
 
#include <sof/compiler_attributes.h>
 
/*
 * helpers to determine processing type
 * Needed till all the modules use PROCESSING_MODE_SINK_SOURCE
 */
#define IS_PROCESSING_MODE_AUDIO_STREAM(mod) ((mod)->proc_type == MODULE_PROCESS_TYPE_STREAM)
#define IS_PROCESSING_MODE_RAW_DATA(mod) ((mod)->proc_type == MODULE_PROCESS_TYPE_RAW)
#define IS_PROCESSING_MODE_SINK_SOURCE(mod) ((mod)->proc_type == MODULE_PROCESS_TYPE_SOURCE_SINK)
 
#if CONFIG_IPC_MAJOR_4
#define IPC_MOD_CMD(v)
#elif CONFIG_IPC_MAJOR_3
#define IPC_MOD_CMD(v) .cmd = v,
#endif
 
/* Zephyr's tr_*() macros ignore the trace context, no need to store it */
#if CONFIG_ZEPHYR_LOG
#define SET_MODULE_ADAPTER_TCTX(tr)
#else
#define SET_MODULE_ADAPTER_TCTX(tr) .tctx = &(tr),
#endif
 
/*
 * \brief Macro to declare a module adapter component.
 * \param adapter - name of the module.
 * \param uuid - UUID of the module.
 * \param tr - trace context for the module.
 *
 * This macro declares a module component with the specified name, UUID, and trace context.
 * It initializes the component module structure with the appropriate type, UID, and
 * struct module_interface operations.
 */
#define DECLARE_MODULE_ADAPTER(adapter, uuid, tr) \
static const struct comp_driver comp_##adapter##_module = { \
    .type = SOF_COMP_MODULE_ADAPTER, \
    .uid = SOF_RT_UUID(uuid), \
    SET_MODULE_ADAPTER_TCTX(tr) \
    .ops = { \
        .create = module_adapter_new, \
        .prepare = module_adapter_prepare, \
        .params = module_adapter_params, \
        .copy = module_adapter_copy, \
        IPC_MOD_CMD(module_adapter_cmd) \
        .trigger = module_adapter_trigger, \
        .reset = module_adapter_reset, \
        .free = module_adapter_free, \
        .set_large_config = module_set_large_config,\
        .get_large_config = module_get_large_config,\
        .get_attribute = module_adapter_get_attribute,\
        .set_attribute = module_adapter_set_attribute,\
        .bind = module_adapter_bind,\
        .unbind = module_adapter_unbind,\
        .get_total_data_processed = module_adapter_get_total_data_processed,\
        .dai_get_hw_params = module_adapter_get_hw_params,\
        .position = module_adapter_position,\
        .dai_ts_config = module_adapter_ts_config_op,\
        .dai_ts_start = module_adapter_ts_start_op,\
        .dai_ts_stop = module_adapter_ts_stop_op,\
        .dai_ts_get = module_adapter_ts_get_op,\
    }, \
    .adapter_ops = &(adapter), \
}; \
\
static struct comp_driver_info comp_module_##adapter##_info = { \
    .drv = &comp_##adapter##_module, \
}; \
\
UT_STATIC void sys_comp_module_##adapter##_init(void) \
{ \
    comp_register(&comp_module_##adapter##_info); \
} \
\
DECLARE_MODULE(sys_comp_module_##adapter##_init)
 
enum module_state {
    MODULE_DISABLED,    
    MODULE_INITIALIZED, 
    MODULE_IDLE,        
    MODULE_PROCESSING,  
};
 
struct module_param {
    uint32_t id;
    uint32_t size;      
    int32_t data[];     
};
 
struct module_resources {
    struct objpool_head objpool;
    size_t heap_usage;
    size_t heap_high_water_mark;
    struct mod_alloc_ctx *alloc;
};
 
enum mod_resource_type {
    MOD_RES_UNINITIALIZED = 0,
    MOD_RES_HEAP,
    MOD_RES_BLOB_HANDLER,
    MOD_RES_FAST_GET,
};
 
struct module_resource {
    union {
        void *ptr; 
        struct comp_data_blob_handler *bhp; 
        const void *sram_ptr; 
    };
    size_t size; 
    enum mod_resource_type type; 
};
 
struct module_processing_data {
    uint32_t in_buff_size; 
    uint32_t out_buff_size; 
    uint32_t avail; 
    uint32_t produced; 
    uint32_t consumed; 
    uint32_t init_done; 
    bool eos_reached; 
    bool eos_notification_sent; 
    void *in_buff; 
    void *out_buff; 
};
 
/*
 * Definition used to extend structure definitions to include fields for exclusive use by SOF.
 * This is a temporary solution used until work on separating a common interface for loadable
 * modules is completed.
 */
#define SOF_MODULE_API_PRIVATE
 
#include <module/module/base.h>
 
/*****************************************************************************/
/* Module generic interfaces                             */
/*****************************************************************************/
int module_load_config(struct comp_dev *dev, const void *cfg, size_t size);
int module_init(struct processing_module *mod);
#if defined(__ZEPHYR__) && defined(CONFIG_SOF_FULL_ZEPHYR_APPLICATION)
__syscall void *mod_balloc_align(struct processing_module *mod, size_t size, size_t alignment);
#else
void *z_impl_mod_balloc_align(struct processing_module *mod, size_t size, size_t alignment);
#define mod_balloc_align z_impl_mod_balloc_align
#endif
 
void mod_resource_init(struct processing_module *mod);
 
void mod_heap_info(struct processing_module *mod, size_t *size, uintptr_t *start);
 
#if defined(__ZEPHYR__) && defined(CONFIG_SOF_FULL_ZEPHYR_APPLICATION)
__syscall void *mod_alloc_ext(struct processing_module *mod, uint32_t flags, size_t size,
                  size_t alignment);
__syscall int mod_free(struct processing_module *mod, const void *ptr);
 
__syscall void mod_free_all(struct processing_module *mod);
#else
void *z_impl_mod_alloc_ext(struct processing_module *mod, uint32_t flags, size_t size,
               size_t alignment);
int z_impl_mod_free(struct processing_module *mod, const void *ptr);
void z_impl_mod_free_all(struct processing_module *mod);
#define mod_alloc_ext z_impl_mod_alloc_ext
#define mod_free z_impl_mod_free
#define mod_free_all z_impl_mod_free_all
#endif
 
static inline void *mod_alloc_align(struct processing_module *mod, size_t size, size_t alignment)
{
    return mod_alloc_ext(mod, SOF_MEM_FLAG_USER, size, alignment);
}
 
static inline void *mod_balloc(struct processing_module *mod, size_t size)
{
    return mod_balloc_align(mod, size, 0);
}
 
static inline void *mod_alloc(struct processing_module *mod, size_t size)
{
    return mod_alloc_align(mod, size, 0);
}
 
static inline void *mod_zalloc(struct processing_module *mod, size_t size)
{
    void *ret = mod_alloc(mod, size);
 
    if (ret)
        memset(ret, 0, size);
 
    return ret;
}
 
static inline struct ipc_msg *mod_ipc_msg_w_ext_init(struct processing_module *mod,
                             uint32_t header,
                             uint32_t extension,
                             uint32_t size)
{
    struct ipc_msg *msg;
 
    /* msg->list is linked into ipc->msg_list and handled cross-core: must be uncached */
    msg = mod_alloc_ext(mod, SOF_MEM_FLAG_USER | SOF_MEM_FLAG_COHERENT, sizeof(*msg), 0);
    if (!msg)
        return NULL;
 
    memset(msg, 0, sizeof(*msg));
 
    if (size) {
        msg->tx_data = mod_alloc_ext(mod, SOF_MEM_FLAG_USER | SOF_MEM_FLAG_COHERENT,
                         size, 0);
        if (!msg->tx_data) {
            mod_free(mod, msg);
            return NULL;
        }
        memset(msg->tx_data, 0, size);
    }
 
    msg->header = header;
    msg->extension = extension;
    msg->tx_size = size;
    list_init(&msg->list);
 
    return msg;
}
 
static inline struct ipc_msg *mod_ipc_msg_init(struct processing_module *mod,
                           uint32_t header, uint32_t size)
{
    return mod_ipc_msg_w_ext_init(mod, header, 0, size);
}
 
static inline void mod_ipc_msg_free(struct processing_module *mod,
                    struct ipc_msg *msg)
{
    if (!msg)
        return;
 
    ipc_msg_list_remove(msg);
 
    mod_free(mod, msg->tx_data);
    mod_free(mod, msg);
}
 
#if CONFIG_COMP_BLOB
#if defined(__ZEPHYR__) && defined(CONFIG_SOF_FULL_ZEPHYR_APPLICATION)
__syscall struct comp_data_blob_handler *mod_data_blob_handler_new(struct processing_module *mod);
__syscall int mod_data_blob_set(struct processing_module *mod,
                enum module_cfg_fragment_position pos, uint32_t data_offset_size,
                const uint8_t *fragment, size_t fragment_size);
#else
struct comp_data_blob_handler *z_impl_mod_data_blob_handler_new(struct processing_module *mod);
int z_impl_mod_data_blob_set(struct processing_module *mod,
                 enum module_cfg_fragment_position pos, uint32_t data_offset_size,
                 const uint8_t *fragment, size_t fragment_size);
#define mod_data_blob_handler_new z_impl_mod_data_blob_handler_new
#define mod_data_blob_set z_impl_mod_data_blob_set
#endif
void mod_data_blob_handler_free(struct processing_module *mod, struct comp_data_blob_handler *dbh);
#endif
#if CONFIG_FAST_GET
#if defined(__ZEPHYR__) && defined(CONFIG_SOF_FULL_ZEPHYR_APPLICATION)
__syscall const void *mod_fast_get(struct processing_module *mod, const void * const dram_ptr,
                   size_t size);
#else
const void *z_impl_mod_fast_get(struct processing_module *mod, const void * const dram_ptr,
                size_t size);
#define mod_fast_get z_impl_mod_fast_get
#endif
void mod_fast_put(struct processing_module *mod, const void *sram_ptr);
#endif
int module_prepare(struct processing_module *mod,
           struct sof_source **sources, int num_of_sources,
           struct sof_sink **sinks, int num_of_sinks);
 
static inline
bool generic_module_is_ready_to_process(struct processing_module *mod,
                    struct sof_source **sources,
                    int num_of_sources,
                    struct sof_sink **sinks,
                    int num_of_sinks)
{
    int i;
 
    for (i = 0; i < num_of_sources; i++)
        if (source_get_data_available(sources[i]) < source_get_min_available(sources[i]))
            return false;
 
    for (i = 0; i < num_of_sinks; i++)
        if (sink_get_free_size(sinks[i]) < sink_get_min_free_space(sinks[i]))
            return false;
 
    return true;
}
 
static inline
bool module_is_ready_to_process(struct processing_module *mod,
                struct sof_source **sources,
                int num_of_sources,
                struct sof_sink **sinks,
                int num_of_sinks)
{
    const struct module_interface *const ops = mod->dev->drv->adapter_ops;
 
    /* LL module has to be always ready for processing */
    if (mod->dev->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_LL)
        return true;
 
    if (ops->is_ready_to_process)
        return ops->is_ready_to_process(mod, sources, num_of_sources, sinks, num_of_sinks);
    /* default action - the module is ready if there's enough data for processing and enough
     * space to store result. IBS/OBS as declared in init_instance
     */
    return generic_module_is_ready_to_process(mod, sources, num_of_sources, sinks,
                          num_of_sinks);
}
 
int module_process_sink_src(struct processing_module *mod,
                struct sof_source **sources, int num_of_sources,
                struct sof_sink **sinks, int num_of_sinks);
int module_process_legacy(struct processing_module *mod,
              struct input_stream_buffer *input_buffers, int num_input_buffers,
              struct output_stream_buffer *output_buffers,
              int num_output_buffers);
int module_reset(struct processing_module *mod);
int module_free(struct processing_module *mod);
int module_set_configuration(struct processing_module *mod,
                 uint32_t config_id,
                 enum module_cfg_fragment_position pos, size_t data_offset_size,
                 const uint8_t *fragment, size_t fragment_size, uint8_t *response,
                 size_t response_size);
int module_bind(struct processing_module *mod, const struct bind_info *bind_data);
int module_unbind(struct processing_module *mod, const struct bind_info *unbind_data);
 
struct comp_dev *module_adapter_new(const struct comp_driver *drv,
                    const struct comp_ipc_config *config, const void *spec);
struct userspace_context;
struct comp_dev *module_adapter_new_ext(const struct comp_driver *drv,
                    const struct comp_ipc_config *config, const void *spec,
                    void *mod_priv, struct userspace_context *user_ctx,
                    const struct module_interface *ops);
int module_adapter_prepare(struct comp_dev *dev);
int module_adapter_params(struct comp_dev *dev, struct sof_ipc_stream_params *params);
int module_adapter_copy(struct comp_dev *dev);
int module_adapter_cmd(struct comp_dev *dev, int cmd, void *data, int max_data_size);
int module_adapter_trigger(struct comp_dev *dev, int cmd);
void module_adapter_free(struct comp_dev *dev);
int module_adapter_reset(struct comp_dev *dev);
 
size_t module_adapter_heap_usage(struct processing_module *mod, size_t *hwm);
 
#if CONFIG_IPC_MAJOR_3
static inline
int module_adapter_get_attribute(struct comp_dev *dev, uint32_t type, void *value)
{
    return -EINVAL;
}
 
static inline
int module_adapter_set_attribute(struct comp_dev *dev, uint32_t type, void *value)
{
    return -EINVAL;
}
 
static inline
int module_set_large_config(struct comp_dev *dev, uint32_t param_id, bool first_block,
                bool last_block, uint32_t data_offset, const char *data)
{
    return 0;
}
 
static inline
int module_get_large_config(struct comp_dev *dev, uint32_t param_id, bool first_block,
                bool last_block, uint32_t *data_offset, char *data)
{
    return 0;
}
 
static inline
int module_adapter_bind(struct comp_dev *dev, const struct bind_info *bind_data)
{
    return 0;
}
 
static inline
int module_adapter_unbind(struct comp_dev *dev, const struct bind_info *unbind_data)
{
    return 0;
}
 
static inline
uint64_t module_adapter_get_total_data_processed(struct comp_dev *dev,
                         uint32_t stream_no, bool input)
{
    return 0;
}
 
static inline int module_process_endpoint(struct processing_module *mod,
                      struct input_stream_buffer *input_buffers,
                      int num_input_buffers,
                      struct output_stream_buffer *output_buffers,
                      int num_output_buffers)
{
    return module_process_legacy(mod, input_buffers, num_input_buffers,
                     output_buffers, num_output_buffers);
}
 
#else
int module_set_large_config(struct comp_dev *dev, uint32_t param_id, bool first_block,
                bool last_block, uint32_t data_offset, const char *data);
int module_get_large_config(struct comp_dev *dev, uint32_t param_id, bool first_block,
                bool last_block, uint32_t *data_offset, char *data);
int module_adapter_get_attribute(struct comp_dev *dev, uint32_t type, void *value);
int module_adapter_set_attribute(struct comp_dev *dev, uint32_t type, void *value);
int module_adapter_bind(struct comp_dev *dev, const struct bind_info *bind_data);
int module_adapter_unbind(struct comp_dev *dev, const struct bind_info *unbind_data);
uint64_t module_adapter_get_total_data_processed(struct comp_dev *dev,
                         uint32_t stream_no, bool input);
 
static inline int module_process_endpoint(struct processing_module *mod,
                      struct input_stream_buffer *input_buffers,
                      int num_input_buffers,
                      struct output_stream_buffer *output_buffers,
                      int num_output_buffers)
{
    const struct module_interface *const ops = mod->dev->drv->adapter_ops;
 
    return ops->process_audio_stream(mod, input_buffers, num_input_buffers,
                     output_buffers, num_output_buffers);
}
 
#endif
 
int module_adapter_get_hw_params(struct comp_dev *dev, struct sof_ipc_stream_params *params,
                 int dir);
int module_adapter_position(struct comp_dev *dev, struct sof_ipc_stream_posn *posn);
int module_adapter_ts_config_op(struct comp_dev *dev);
int module_adapter_ts_start_op(struct comp_dev *dev);
int module_adapter_ts_stop_op(struct comp_dev *dev);
#if CONFIG_ZEPHYR_NATIVE_DRIVERS
int module_adapter_ts_get_op(struct comp_dev *dev, struct dai_ts_data *tsd);
#else
int module_adapter_ts_get_op(struct comp_dev *dev, struct timestamp_data *tsd);
#endif
 
void module_update_buffer_position(struct input_stream_buffer *input_buffers,
                   struct output_stream_buffer *output_buffers,
                   uint32_t frames);
struct module_ext_init_data;
#if CONFIG_IPC_MAJOR_4
int module_ext_init_decode(const struct comp_driver *drv, struct module_ext_init_data *ext_data,
               struct ipc_config_process *spec);
#else
static inline
int module_ext_init_decode(const struct comp_driver *drv, struct module_ext_init_data *ext_data,
               struct ipc_config_process *spec)
{
    return 0;
}
#endif
int module_adapter_init_data(struct comp_dev *dev,
                 struct module_config *dst,
                 const struct comp_ipc_config *config,
                 const void *spec);
void module_adapter_reset_data(struct module_config *dst);
void module_adapter_check_data(struct processing_module *mod, struct comp_dev *dev,
                   struct comp_buffer *sink);
void module_adapter_set_params(struct processing_module *mod, struct sof_ipc_stream_params *params);
int module_adapter_set_state(struct processing_module *mod, struct comp_dev *dev,
                 int cmd);
int module_adapter_sink_src_prepare(struct comp_dev *dev);
 
uint32_t module_get_deadline(struct processing_module *mod);
 
static inline uint32_t module_get_lpt(struct processing_module *mod)
{
    /* return worst case of LPT - a module period. See zephyr_dp_schedule.c for description */
    return mod->dev->period;
}
 
#if defined(__ZEPHYR__) && defined(CONFIG_SOF_FULL_ZEPHYR_APPLICATION)
#include <zephyr/syscalls/generic.h>
#endif
 
#endif /* __SOF_AUDIO_MODULE_GENERIC__ */