module_interface Struct Reference

3rd party processing module interface More...

#include <src/include/module/module/interface.h>

Data Fields
int(*	init )(struct processing_module *mod)
	Module specific initialization procedure, called as part of module_adapter component creation in .new().
int(*	prepare )(struct processing_module *mod, struct sof_source **sources, int num_of_sources, struct sof_sink **sinks, int num_of_sinks)
	(optional) Module specific prepare procedure, called as part of module_adapter component preparation in .prepare().
bool(*	is_ready_to_process )(struct processing_module *mod, struct sof_source **sources, int num_of_sources, struct sof_sink **sinks, int num_of_sinks)
	(optional) return true if the module is ready to process This procedure should check if the module is ready for immediate processing.
int(*	process )(struct processing_module *mod, struct sof_source **sources, int num_of_sources, struct sof_sink **sinks, int num_of_sinks)
	Module specific processing procedure This procedure is responsible to consume samples provided by the module_adapter and produce/output the processed ones back to module_adapter.
int(*	process_audio_stream )(struct processing_module *mod, struct input_stream_buffer *input_buffers, int num_input_buffers, struct output_stream_buffer *output_buffers, int num_output_buffers)
	process_audio_stream (depreciated)
int(*	process_raw_data )(struct processing_module *mod, struct input_stream_buffer *input_buffers, int num_input_buffers, struct output_stream_buffer *output_buffers, int num_output_buffers)
	process_raw_data (depreciated)
int(*	set_config_param )(struct processing_module *mod, uint32_t param_id_data)
	(optional) Set module configuration parameter
int(*	get_config_param )(struct processing_module *mod, uint32_t *param_id_data)
	(optional) Get module configuration parameter
int(*	set_configuration )(struct processing_module *mod, uint32_t config_id, enum module_cfg_fragment_position pos, uint32_t data_offset_size, const uint8_t *fragment, size_t fragment_size, uint8_t *response, size_t response_size)
	(optional) Set module configuration for the given configuration ID
int(*	get_configuration )(struct processing_module *mod, uint32_t config_id, uint32_t *data_offset_size, uint8_t *fragment, size_t fragment_size)
	(optional) Get module runtime configuration for the given configuration ID
int(*	set_processing_mode )(struct processing_module *mod, enum module_processing_mode mode)
	(IADK) Set processing mode for the module
enum module_processing_mode(*	get_processing_mode )(struct processing_module *mod)
	(IADK) Get the current processing mode for the module
int(*	reset )(struct processing_module *mod)
	(optional) Module specific reset procedure, called as part of module_adapter component reset in .reset().
int(*	free )(struct processing_module *mod)
	(optional) Module specific free procedure, called as part of module_adapter component free in .free().
int(*	bind )(struct processing_module *mod, const struct bind_info *bind_data)
	(optional) Module specific bind procedure, called when modules are bound with each other.
int(*	unbind )(struct processing_module *mod, const struct bind_info *unbind_data)
	(optional) Module specific unbind procedure, called when modules are disconnected from one another.
int(*	trigger )(struct processing_module *mod, int cmd)
	(optional) Module specific trigger procedure, called when modules are triggered.

Detailed Description

3rd party processing module interface

Module operations can be optimized for performance (default - no action) or for memory and power efficiency (opt in using __cold). It is recommended that module authors review their modules for non time sensitive code and mark it using __cold based on the descriptions below. This will ensure modules maintain peak performance and peak power/memory efficiency. Similarly cold read-only data can be marked with __cold_rodata. In cases where a subset of cold data has to be accessed from hot paths, it can be copied to fast memory, using the fast_get() API and then released using fast_put().

Field Documentation

bind

int(* module_interface::bind) (struct processing_module *mod, const struct bind_info *bind_data)

(optional) Module specific bind procedure, called when modules are bound with each other.

Usually can be __cold

free

int(* module_interface::free) (struct processing_module *mod)

(optional) Module specific free procedure, called as part of module_adapter component free in .free().

This should free all memory allocated during module initialization. Usually can be __cold

get_config_param

int(* module_interface::get_config_param) (struct processing_module *mod, uint32_t *param_id_data)

(optional) Get module configuration parameter

Using Module Config Get command, host driver may send a parameter that fits into the header (a very short one), packed along with parameter id.

param_id_data specifies both ID of the parameter, defined by the module and value of the parameter. It is up to the module how to distribute bits to ID and value of the parameter.

get_configuration

int(* module_interface::get_configuration) (struct processing_module *mod, uint32_t config_id, uint32_t *data_offset_size, uint8_t *fragment, size_t fragment_size)

(optional) Get module runtime configuration for the given configuration ID

If the complete configuration message is greater than MAX_BLOB_SIZE bytes, the transmission will be split into several smaller fragments. In this case the ADSP System will perform multiple calls to GetConfiguration() until completion of the configuration message retrieval.

Note

config_id indicates ID of the configuration message only on the first fragment retrieval, otherwise it is set to 0. Usually can be __cold

get_processing_mode

enum module_processing_mode(* module_interface::get_processing_mode) (struct processing_module *mod)

(IADK) Get the current processing mode for the module

init

int(* module_interface::init) (struct processing_module *mod)

Module specific initialization procedure, called as part of module_adapter component creation in .new().

Usually can be __cold

is_ready_to_process

bool(* module_interface::is_ready_to_process) (struct processing_module *mod, struct sof_source **sources, int num_of_sources, struct sof_sink **sinks, int num_of_sinks)

(optional) return true if the module is ready to process This procedure should check if the module is ready for immediate processing.

NOTE! the call MUST NOT perform any time consuming operations

this procedure will always return true for LL module

For DP there's a default implementation that will do a simple check if there's at least IBS bytes of data on first source and at least OBS free space on first sink

In case more sophisticated check is needed the method should be implemented in the module. Usually shouldn't be __cold

prepare

int(* module_interface::prepare) (struct processing_module *mod, struct sof_source **sources, int num_of_sources, struct sof_sink **sinks, int num_of_sinks)

(optional) Module specific prepare procedure, called as part of module_adapter component preparation in .prepare().

Usually can be __cold

process

int(* module_interface::process) (struct processing_module *mod, struct sof_source **sources, int num_of_sources, struct sof_sink **sinks, int num_of_sinks)

Module specific processing procedure This procedure is responsible to consume samples provided by the module_adapter and produce/output the processed ones back to module_adapter.

there are 3 versions of the procedure, the difference is the format of input/output data

the module MUST implement one and ONLY one of them

process_audio_stream and process_raw_data are depreciated and will be removed once pipeline learns to use module API directly (without module adapter) modules that need such processing should use proper wrappers

process

• sources are handlers to source API struct source*[]
• sinks are handlers to sink API struct sink*[]

Usually shouldn't be __cold

process_audio_stream

int(* module_interface::process_audio_stream) (struct processing_module *mod, struct input_stream_buffer *input_buffers, int num_input_buffers, struct output_stream_buffer *output_buffers, int num_output_buffers)

process_audio_stream (depreciated)

• sources are input_stream_buffer[]
  • sources[].data is a pointer to audio_stream structure
• sinks are output_stream_buffer[]
  • sinks[].data is a pointer to audio_stream structure

It can be used by modules that support 1:1, 1:N, N:1 sources:sinks configuration.

Usually shouldn't be __cold

process_raw_data

int(* module_interface::process_raw_data) (struct processing_module *mod, struct input_stream_buffer *input_buffers, int num_input_buffers, struct output_stream_buffer *output_buffers, int num_output_buffers)

process_raw_data (depreciated)

• sources are input_stream_buffer[]
  • sources[].data is a pointer to raw audio data
• sinks are output_stream_buffer[]
  • sinks[].data is a pointer to raw audio data

Usually shouldn't be __cold

reset

int(* module_interface::reset) (struct processing_module *mod)

(optional) Module specific reset procedure, called as part of module_adapter component reset in .reset().

This should reset all parameters to their initial stage and free all memory allocated during prepare(). Usually shouldn't be __cold since it's called from pipeline_reset() from ipc4_pipeline_trigger()

set_config_param

int(* module_interface::set_config_param) (struct processing_module *mod, uint32_t param_id_data)

(optional) Set module configuration parameter

Using Module Config Set command, host driver may send a parameter that fits into the header (a very short one), packed along with parameter id.

param_id_data specifies both ID of the parameter, defined by the module and value of the parameter. It is up to the module how to distribute bits to ID and value of the parameter.

set_configuration

int(* module_interface::set_configuration) (struct processing_module *mod, uint32_t config_id, enum module_cfg_fragment_position pos, uint32_t data_offset_size, const uint8_t *fragment, size_t fragment_size, uint8_t *response, size_t response_size)

(optional) Set module configuration for the given configuration ID

If the complete configuration message is greater than MAX_BLOB_SIZE bytes, the transmission will be split into several smaller fragments. In this case the ADSP System will perform multiple calls to SetConfiguration() until completion of the configuration message sending.

Note

config_id indicates ID of the configuration message only on the first fragment sending, otherwise it is set to 0. Usually can be __cold

set_processing_mode

int(* module_interface::set_processing_mode) (struct processing_module *mod, enum module_processing_mode mode)

(IADK) Set processing mode for the module

trigger

int(* module_interface::trigger) (struct processing_module *mod, int cmd)

(optional) Module specific trigger procedure, called when modules are triggered.

Usually shouldn't be __cold. If a module implements this method, even if it only handles commands, running in non-LL context, it will still be called from the high priority LL context, which will cause a short jump to DRAM to check for supported commands.

unbind

int(* module_interface::unbind) (struct processing_module *mod, const struct bind_info *unbind_data)

(optional) Module specific unbind procedure, called when modules are disconnected from one another.

Usually can be __cold

---

The documentation for this struct was generated from the following file:

• src/include/module/module/interface.h