中文 EN

4.3.29.4. HIFI5 Interface Documentation

Modules API

Module is a basic data processing module. The fundamental operators of a Module are as follows:

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 special use */
    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)(struct plugin_module *modptr);
} module_ops_t;

The structure of the Module itself is created by the framework. The create/destroy interfaces in module_ops are provided for the module to initialize and clean up its internal resources.

Control Interface

【Function Declaration】

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

【Parameter Description】

[IN]: struct plugin_module * modptr, pointer to the module itself.

[IN]: ele_msg_p msg_ptr, command message structure.

【Description】

This interface is invoked by the framework at OPEN/CLOSE/START/STOP/SET_PARAM timing points.

ELE_OPEN: Module open, typically used for initialization tasks.
ELE_CLOSE: Module close.
ELE_START: Start (typically, hardware driver modules enable DMA transfer, interrupts, etc.).
ELE_STOP: Stop.
ELE_SET_PARAM: Set parameters.
ELE_GET_PARAM: Get parameters.

【Return Value】

Success: SYS_OK
Failure: SYS_ERR

【Function Description】

Sends a command to the Module.

The basic command sequence is:
OPEN -> START -> STOP -> CLOSE.
SET_PARAM and GET_PARAM are asynchronous operations that can be called at any time during the module’s lifecycle.

These sub-commands are sent to the module at corresponding stages of the audio pipeline. The module processes these commands to complete the entire control flow.

Data Interface

【Function Declaration】

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

【Parameter Description】

[IN]: struct plugin_module * modptr, pointer to the module itself.

[IN]: sample_p data_ptr, pointer to the data structure.

【Description】

The process interface handles data streams. The parameter sample_p data_ptr represents one frame of data to be processed.

The structure of each data frame is defined as follows:

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;/*!< interleaved samples */
    } samples;
} sample_t __attribute__((aligned(8)));

In the module’s process function, the data in the samples member must be read, processed, and then written back to the same samples structure.

【Return Value】

Success: SYS_OK
Failure: SYS_ERR

【Function Description】

Data processing interface, serves as the entry point for algorithm execution.

Create/Destroy Hook Interface

【Function Declaration】

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

【Parameter Description】

[IN]: struct plugin_module * modptr, pointer to the module itself.

【Description】

The create hook is called by the framework after the module is created.

The destroy hook is called by the framework before the module is destroyed.

【Return Value】

Success: SYS_OK
Failure: SYS_ERR

【Function Description】

These interfaces are invoked during system create/destroy operations and are intended for modules with special requirements. Modules without such needs may leave these interfaces unimplemented.

Get Module Memory Size Interface

【Function Declaration】

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

【Parameter Description】

[IN]: void *work_param, working parameters.

[IN]: uint32_t size, size of the parameters.

【Description】

Some modules require a distinct private memory space for each instance, used to store private data. The module must implement this interface. The framework will allocate a fixed memory block based on the return value of this function, and the address will be stored in priv_data.

【Return Value】

Size of required private memory space.

【Function Description】

Returns the size of private memory space required by the module, so the framework can allocate it accordingly.

Get Stack Memory Size Interface

【Function Declaration】

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

【Parameter Description】

[IN]: struct plugin_module * modptr, pointer to the module itself.

【Description】

Some algorithms require large stack space (recommended not to exceed 16KB). By default, the built-in thread stack size is 8KB. When an algorithm requires more stack space, this interface must be implemented to inform the framework of the required stack size.

【Return Value】

Stack size in bytes.

【Function Description】

Returns the stack size required by the module, so the framework can allocate it accordingly.

ARM-side IPC Call API

Besides being invoked by voice pipelines inside the SSF framework, DSP firmware can also be actively called by ARM-side user-space programs via IPC to issue algorithm tasks. The ARM-side call interfaces are provided by two headers: hb_dsp_mgr.h (DSP lifecycle and memory management) and hb_ipcf_hal.h (IPC channel send/receive). Link -ldsp -lhbipcfhal -lhbmem when compiling.

Typical call order:

hb_dsp_init → hb_dsp_mem_alloc(×N) → (hb_ipcfhal_getchan_byjson + hb_ipcfhal_init)(×N)
  → hb_dsp_start → [send thread] hb_ipcfhal_send / [recv thread] hb_ipcfhal_recv
  → hb_ipcfhal_deinit(×N) → hb_dsp_stop → hb_dsp_mem_free(×N) → hb_dsp_deinit

Interface descriptions:

Interface	Function
hb_dsp_init	Initializes the DSP environment.
hb_dsp_mem_alloc	Allocates memory for DSP operations; returns virtual address and IOVA.
hb_ipcfhal_getchan_byjson	Retrieves an IPC channel from a JSON configuration file.
hb_ipcfhal_init	Initializes the IPC channel.
hb_dsp_start	Loads and starts the DSP firmware.
hb_ipcfhal_send	ARM side sends task parameters to the DSP via IPC (called in the send thread).
hb_ipcfhal_recv	ARM side receives the DSP processing result via IPC (called in the receive thread).
hb_ipcfhal_deinit	Releases the IPC channel.
hb_dsp_stop	Stops DSP processing.
hb_dsp_mem_free	Frees previously allocated memory.
hb_dsp_deinit	Deinitializes the DSP environment.

IPC channel parameters are specified via a JSON configuration file, with fields including log_level, config_num, config_num_max, and per-channel config_x containing name/instance/channel/pkg_size_max/fifo_size/fifo_type/ipcf_dev_path/ipcf_dev_name. For field descriptions and an example, see sample_dsp User Guide.

For a complete runnable example (argument parsing, dual-channel send/receive threads, error recovery, and resource release), see sample_dsp User Guide. Experiencing this flow with the prebuilt firmware requires no DSP secondary-development authorization; to modify DSP-side algorithms, you must apply for adsp source authorization — see HIFI5 User Guide.

The exact prototypes of the above interfaces are subject to the SDK headers hb_dsp_mgr.h / hb_ipcf_hal.h; this section is organized according to the actual usage in sample_dsp.

Return Value Description

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
};