# HIFI5接口文档

## Modules API

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

```c++
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用来创建内部自己需要。

### 控制接口
【函数声明】
```c++
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处理对应命令，完成整个控制流程。

### 数据接口

【函数声明】
```c++
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参数，表示一帧需要处理的数据内容。
每帧数据的结构体如下：
```c++
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接口

【函数声明】
```c++
/* 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接口

【函数声明】
```c++
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接口

【函数声明】
```c++
uint32_t (*stack_size)(struct plugin_module *modptr);
```
【参数描述】

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

【说明】

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

【返回值】

栈空间大小

【功能描述】

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


## 返回值说明

```c++
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
};
```
