中文 EN

4.3.29.4. HIFI5接口文档

Modules API

Module是基本数据处理模块，Module的基本操作符如下：

typedef struct module_ops {
    int32_t (*cmd)(struct plugin_module *modptr, ele_msg_p msg_ptr);
    int32_t (*process)(struct plugin_module *modptr, sample_p data_ptr);

    /* this hook is for specitial used */
    int32_t (*create)(struct plugin_module *modptr);
    int32_t (*destroy)(struct plugin_module *modptr);

    uint32_t (*priv_size)(void *work_param, uint32_t size);
    uint32_t (*stack_size)(sttuct plugin_module *modptr);
} module_ops_t;

Module自身的结构由框架创建，module_ops中的create/destory接口，是给module用来创建内部自己需要。

控制接口

【函数声明】

int32_t (*cmd)(struct plugin_module * modptr, ele_msg_p msg_ptr);

【参数描述】

[IN] ：struct plugin_module * modptr，模块自身指针。

[IN]：ele_msg_p msg_ptr，命令消息结构体。

【说明】

框架层在OPEN/CLOSE/START/STOP/SET_PARAM的时间点调用到该接口。

ELE_OPEN: 模块打开，通常是一些初始化等动作
ELE_CLOSE: 模块关闭
ELE_START: 开始 (通常是硬件驱动模块在此时开启DMA传输、开启中断等操作)
ELE_STOP: 停止
ELE_SET_PARAM: 设置参数
ELE_GET_PARAM: 获取参数

【返回值】

操作成功：SYS_OK

操作失败：SYS_ERR

【功能描述】

发送命令给Module

基本命令时序如下： OPEN->START->STOP->CLOSE。SET_PARAM/GET_PARAM是异步过程，在整个运行周期内都可能被调用。

上述子命令会在audio pipeline对应阶段被发送到module，module处理对应命令，完成整个控制流程。

数据接口

【函数声明】

int32_t (*process)(struct plugin_module * modptr, sample_p data_ptr);

【参数描述】

[IN] ：struct plugin_module * modptr，模块自身指针

[IN]：sample_p data_ptr，数据结构体指针

【说明】

process接口处理数据流，sample_p data_ptr参数，表示一帧需要处理的数据内容。 每帧数据的结构体如下：

typedef struct sample {
    sample_attr_t attr;
    uint32_t ch_count;
    uint32_t sample_count;
    struct sample_data {
        sample_type_t **noninterleaved;/*!< noninterleaved samples: noninterleaved[ch_count][sample_count] */
        char *interleaved;/*!< interlaved samples */
    } samples;
} sample_t __attribute__((aligned(8)));

在module的process处理函数中，需要读取上述的samples成员的数据，需要将处理完成之后的数据写回到samples。

【返回值】

操作成功：SYS_OK

操作失败：SYS_ERR

【功能描述】

数据处理接口，是算法调用的入口

创建/销毁Hook接口

【函数声明】

/* this hook is called after module's creating */
int32_t (*create)(struct plugin_module *modptr);
/* this hook is call before module's destroy */
int32_t (*destroy)(struct plugin_module *modptr);

【参数描述】

[IN] ：struct plugin_module * modptr，模块自身指针

【说明】

create_hook在框架层创建module后调用。

destroy_hook在框架层销毁module前调用。

【返回值】

操作成功：SYS_OK

操作失败：SYS_ERR

【功能描述】

上述接口在系统create/destroy时被调用，给有特别需求的module使用，如果没有这类需求，可以不用实现该接口。

获取模块的内存size接口

【函数声明】

uint32_t (*priv_size)(void *work_param, uint32_t size);

【参数描述】

[IN] ：void *work_param, 工作参数

[IN] ：uint32_t size, 参数大小

【说明】

有一部分module需要在每个实例打开的时候创建一个不同的私有内存空间，用于保存module的私有数据。module需要实现此接口，框架层会根据该接口的返回值，分配好固定内存，其地址将会被存放在priv_data中。

【返回值】

操作成功：SYS_OK

操作失败：SYS_ERR

【功能描述】

返回模块所需要私有空间的大小，以便框架层能够按需分配。

获取栈内存size接口

【函数声明】

uint32_t (*stack_size)(struct plugin_module *modptr);

【参数描述】

[IN] ：struct plugin_module * modptr，模块自身指针

【说明】

部分算法用到非常大的栈空间（建议不超过16K），默认情况下，内置的线程默认的栈空间是8K。当算法所需要的栈空间大于此内存时，需要实现这个接口，用于告知框架层整个算法所需要的栈空间大小。

【返回值】

栈空间大小

【功能描述】

返回模块所需要栈空间的大小，以便框架层能够按需分配。

ARM 侧 IPC 调用 API

DSP 固件除了在 SSF 框架内被语音 pipeline 调用外，也可由 ARM 侧用户态程序通过 IPC 主动发起算法任务。ARM 侧调用接口由 hb_dsp_mgr.h（DSP 生命周期与内存管理）和 hb_ipcf_hal.h（IPC 通道收发）两组头文件提供，编译时链接 -ldsp -lhbipcfhal -lhbmem。

典型调用顺序如下：

hb_dsp_init → hb_dsp_mem_alloc(×N) → (hb_ipcfhal_getchan_byjson + hb_ipcfhal_init)(×N)
  → hb_dsp_start → [发送线程] hb_ipcfhal_send / [接收线程] hb_ipcfhal_recv
  → hb_ipcfhal_deinit(×N) → hb_dsp_stop → hb_dsp_mem_free(×N) → hb_dsp_deinit

各接口说明：

接口	功能
hb_dsp_init	初始化 DSP 环境。
hb_dsp_mem_alloc	为 DSP 操作分配内存，返回虚拟地址与 IOVA。
hb_ipcfhal_getchan_byjson	按 JSON 配置文件获取 IPC 通道。
hb_ipcfhal_init	初始化 IPC 通道。
hb_dsp_start	加载并启动 DSP 固件。
hb_ipcfhal_send	ARM 侧通过 IPC 向 DSP 发送任务参数（在发送线程中调用）。
hb_ipcfhal_recv	ARM 侧通过 IPC 接收 DSP 处理结果（在接收线程中调用）。
hb_ipcfhal_deinit	释放 IPC 通道。
hb_dsp_stop	停止 DSP 处理。
hb_dsp_mem_free	释放之前分配的内存。
hb_dsp_deinit	DSP 环境反初始化。

IPC 通道参数通过 JSON 配置文件指定，字段包括 log_level、config_num、config_num_max 以及每个 config_x 的 name/instance/channel/pkg_size_max/fifo_size/fifo_type/ipcf_dev_path/ipcf_dev_name，字段说明与示例参见 sample_dsp 使用说明。

完整的可运行示例（含参数解析、双通道收发线程、错误恢复与资源释放）参见 sample_dsp 使用说明。使用预置固件体验该流程无需 DSP 二次开发授权；若需修改 DSP 侧算法，则需申请 adsp 源码授权，参见 HIFI5 用户指南。

上述接口的精确原型以 SDK 头文件 hb_dsp_mgr.h / hb_ipcf_hal.h 为准；此处按 sample_dsp 的实际调用方式整理。

返回值说明

enum sys_error {
    SYS_OK = 0,
    SYS_ERR = -1,
    SYS_ERR_SEM = -2,
    SYS_ERR_MEM = -3,
    SYS_ERR_TRANSFER = -4,
    SYS_ERR_TIMEOUT = -5
};