Component API

This section is intended for all component developers. It documents the basic component driver and component device API that must be implemented by every component. It also documents functions that are commonly used by effects components, or blocks inserted in the middle of the pipeline to process enhance the audio signal.

Another Component API Ext section documents macros and functions that are used by the infrastructure and specialized components like host, dai, and kpb.

Location: include/sof/audio/component.h

group Component API

Standard Component Stream Commands

TODO: use IPC versions after 1.1

Most component stream commands match one-to-one IPC stream trigger commands. However we add two PRE_ and two POST_ commands to the set. They are issued internally without matching IPC commands. A single START IPC command is translated into a sequence of PRE_START and START component commands, etc. POST_* commands aren’t used so far.

enum [anonymous]

Values:

enumerator COMP_TRIGGER_STOP: Stop component stream.

enumerator COMP_TRIGGER_START: Start component stream.

enumerator COMP_TRIGGER_PAUSE: Pause the component stream.

enumerator COMP_TRIGGER_RELEASE: Release paused component stream.

enumerator COMP_TRIGGER_RESET: Reset component.

enumerator COMP_TRIGGER_PREPARE: Prepare component.

enumerator COMP_TRIGGER_XRUN: XRUN component.

enumerator COMP_TRIGGER_PRE_START: Prepare to start component stream.

enumerator COMP_TRIGGER_PRE_RELEASE: Prepare to release paused component stream.

enumerator COMP_TRIGGER_POST_STOP: Finalize stop component stream.

enumerator COMP_TRIGGER_POST_PAUSE: Finalize pause component stream.

enumerator COMP_TRIGGER_NO_ACTION: No action required.

Audio Component States

COMP_STATE_NOT_EXIST: Component does not exist.

COMP_STATE_INIT: Component being initialised.

COMP_STATE_READY: Component inactive, but ready.

COMP_STATE_SUSPEND: Component suspended.

COMP_STATE_PREPARE: Component prepared.

COMP_STATE_PAUSED: Component paused.

COMP_STATE_ACTIVE: Component active.

COMP_STATE_PRE_ACTIVE: Component after early initialisation.

Standard Component Control Commands

“Value” commands are standard ones, known to the driver while “Data” commands are opaque blobs transferred by the driver.

TODO: see also: ref to ipc data structures for commands.

COMP_CMD_SET_VALUE: Set value to component.

COMP_CMD_GET_VALUE: Get value from component.

COMP_CMD_SET_DATA: Set data to component.

COMP_CMD_GET_DATA: Get data from component.

MMAP IPC status

COMP_CMD_IPC_MMAP_RPOS: Host read position.

COMP_CMD_IPC_MMAP_PPOS: DAI presentation position.

COMP_CMD_IPC_MMAP_VOL(chan): Volume.

Component status

COMP_STATUS_STATE_ALREADY_SET: Comp set state status.

Component attribute types

COMP_ATTR_COPY_TYPE: Comp copy type attribute.

COMP_ATTR_HOST_BUFFER: Comp host buffer attribute.

COMP_ATTR_COPY_DIR: Comp copy direction.

COMP_ATTR_VDMA_INDEX: Comp index of the virtual DMA at the gateway.

COMP_ATTR_BASE_CONFIG: Component base config.

Trace macros

trace_comp_drv_get_tr_ctx(drv_p): Retrieves trace context from the component driver.

trace_comp_drv_get_id(drv_p): Retrieves id (-1 = undefined) from the component driver.

trace_comp_drv_get_subid(drv_p): Retrieves subid (-1 = undefined) from the component driver.

trace_comp_get_tr_ctx(comp_p): Retrieves trace context from the component device.

trace_comp_get_id(comp_p): Retrieves id (pipe id) from the component device.

trace_comp_get_subid(comp_p): Retrieves subid (comp id) from the component device.

comp_cl_err(drv_p, __e, ...): Trace error message from component driver (no comp instance)

comp_cl_warn(drv_p, __e, ...): Trace warning message from component driver (no comp instance)

comp_cl_info(drv_p, __e, ...): Trace info message from component driver (no comp instance)

comp_cl_dbg(drv_p, __e, ...): Trace debug message from component driver (no comp instance)

comp_err(comp_p, __e, ...): Trace error message from component device.

comp_warn(comp_p, __e, ...): Trace warning message from component device.

comp_info(comp_p, __e, ...): Trace info message from component device.

comp_dbg(comp_p, __e, ...): Trace debug message from component device.

comp_perf_info(pcd, comp_p)

comp_perf_avg_info(pcd, comp_p)

Defines

COMP_PROCESSING_DOMAIN_LL

COMP_PROCESSING_DOMAIN_DP

comp_dev_for_each_producer(_dev, _producer)

comp_dev_for_each_producer_safe(_dev, _producer, _next_producer)

comp_dev_for_each_consumer(_dev, _consumer)

comp_dev_for_each_consumer_safe(_dev, _consumer, _next_consumer)

Enums

enum comp_endpoint_type

Type of endpoint this component is connected to in a pipeline.

Values:

enumerator COMP_ENDPOINT_HOST: Connected to host dma.

enumerator COMP_ENDPOINT_DAI: Connected to dai dma.

enumerator COMP_ENDPOINT_NODE: No dma connection.

enum comp_copy_type

Type of next dma copy mode, changed on runtime.

Supported by host as COMP_ATTR_COPY_TYPE parameter to comp_set_attribute().

Values:

enumerator COMP_COPY_INVALID: Invalid.

enumerator COMP_COPY_NORMAL: Normal.

enumerator COMP_COPY_BLOCKING: Blocking.

enumerator COMP_COPY_ONE_SHOT: One-shot.

Functions

static inline struct comp_buffer *comp_dev_get_first_data_producer(struct comp_dev *component): Get a pointer to the first comp_buffer object providing data to the component The function will return NULL if there’s no data provider.

static inline struct comp_buffer *comp_dev_get_next_data_producer(struct comp_dev *component, struct comp_buffer *producer): Get a pointer to the next comp_buffer object providing data to the component The function will return NULL if there’re no more data providers _save version also checks if producer != NULL.

static inline struct comp_buffer *comp_dev_get_next_data_producer_safe(struct comp_dev *component, struct comp_buffer *producer)

static inline struct comp_buffer *comp_dev_get_first_data_consumer(struct comp_dev *component): Get a pointer to the first comp_buffer object receiving data from the component The function will return NULL if there’s no data consumers.

static inline struct comp_buffer *comp_dev_get_next_data_consumer(struct comp_dev *component, struct comp_buffer *consumer): Get a pointer to the next comp_buffer object receiving data from the component The function will return NULL if there’re no more data consumers _safe version also checks if consumer is != NULL.

static inline struct comp_buffer *comp_dev_get_next_data_consumer_safe(struct comp_dev *component, struct comp_buffer *consumer)

struct comp_ops

#include <component.h>

Audio component operations.

All component operations must return 0 for success, negative values for errors and 1 to stop the pipeline walk operation unless specified otherwise in the operation documentation.

Public Members

struct comp_dev *(*create)(const struct comp_driver *drv, const struct comp_ipc_config *ipc_config, const void *spec)

Creates a new component device.

All required data objects should be allocated from the run-time heap (SOF_MEM_ZONE_RUNTIME). Any component-specific private data is allocated separately and pointer is connected to the comp_dev::private by using comp_set_drvdata() and later retrieved by comp_get_drvdata().

All parameters should be initialized to their default values.

Param drv:: Parent component driver.
Param ipc_config:: Component parameters.
Param spec:: Pointer to initialization data
Return:: Pointer to the new component device.

void (*free)(struct comp_dev *dev)

Called to delete the specified component device.

All data structures previously allocated on the run-time heap must be freed by the implementation of free().

Param dev:: Component device to be deleted.

int (*params)(struct comp_dev *dev, struct sof_ipc_stream_params *params)

Sets component audio stream parameters.

Infrastructure calls comp_verify_params() if this handler is not defined, therefore it should be left NULL if no extra steps are required.

Param dev:: Component device.
Param params:: Audio (PCM) stream parameters to be set.

int (*dai_get_hw_params)(struct comp_dev *dev, struct sof_ipc_stream_params *params, int dir)

Fetches hardware stream parameters.

Mandatory for components that allocate DAI.

Param dev:: Component device.
Param params:: Receives copy of stream parameters retrieved from DAI hw settings.
Param dir:: Stream direction (see enum sof_ipc_stream_direction).

int (*dai_config)(struct dai_data *dd, struct comp_dev *dev, struct ipc_config_dai *dai_config, const void *dai_spec_config)

Configures attached DAI.

Mandatory for components that allocate DAI.

Param dev:: Component device.
Param dai_config:: DAI configuration.

int (*trigger)(struct comp_dev *dev, int cmd)

Trigger, atomic - used to start/stop/pause stream operations.

Param dev:: Component device.
Param cmd:: Command, one of COMP_TRIGGER_…

int (*prepare)(struct comp_dev *dev)

Prepares component after params are set.

Prepare should be used to get the component ready for starting processing after it’s hw_params are known or after an XRUN.

Param dev:: Component device.

int (*reset)(struct comp_dev *dev)

Resets component.

Resets the component state and any hw_params to default component state. Should also free any resources acquired during hw_params.

Param dev:: Component device.

int (*copy)(struct comp_dev *dev)

Copy and process stream data from source to sink buffers.

Param dev:: Component device.
Return:: Number of copied frames.

int (*position)(struct comp_dev *dev, struct sof_ipc_stream_posn *posn)

Retrieves component rendering position.

Param dev:: Component device.
Param posn:: Receives reported position.

int (*get_attribute)(struct comp_dev *dev, uint32_t type, void *value)

Gets attribute in component.

Param dev:: Component device.
Param type:: Attribute type.
Param value:: Attribute value.
Return:: 0 if succeeded, error code otherwise.

int (*set_attribute)(struct comp_dev *dev, uint32_t type, void *value)

Sets attribute in component.

Param dev:: Component device.
Param type:: Attribute type.
Param value:: Attribute value.
Return:: 0 if succeeded, error code otherwise.

int (*dai_ts_config)(struct comp_dev *dev)

Configures timestamping in attached DAI.

Mandatory for components that allocate DAI.

Param dev:: Component device.

int (*dai_ts_start)(struct comp_dev *dev)

Starts timestamping.

Mandatory for components that allocate DAI.

Param dev:: Component device.

int (*dai_ts_stop)(struct comp_dev *dev)

Stops timestamping.

Mandatory for components that allocate DAI.

Param dev:: Component device.

int (*dai_ts_get)(struct comp_dev *dev, struct timestamp_data *tsd)

Gets timestamp.

Mandatory for components that allocate DAI.

Param dev:: Component device.
Param tsd:: Receives timestamp data.

int (*bind)(struct comp_dev *dev, void *data)

Bind, atomic - used to notify component of bind event.

Param dev:: Component device.
Param data:: Bind info

int (*unbind)(struct comp_dev *dev, void *data)

Unbind, atomic - used to notify component of unbind event.

Param dev:: Component device.
Param data:: unBind info

int (*get_large_config)(struct comp_dev *dev, uint32_t param_id, bool first_block, bool last_block, uint32_t *data_offset, char *data)

Gets config in component.

Callee fills up *data with config data and save the config size in *data_offset for host to reconstruct the config

Param dev:: Component device
Param param_id:: param id for each component
Param first_block:: first block of large block.
Param last_block:: last block of large block.
Param data_offset:: block offset filled by callee.
Param data:: block data.
Return:: 0 if succeeded, error code otherwise.

int (*set_large_config)(struct comp_dev *dev, uint32_t param_id, bool first_block, bool last_block, uint32_t data_offset, const char *data)

Set config in component.

Host divides large block into small blocks and sends them to fw. The data_offset indicates the offset in the large block data.

Param dev:: Component device
Param param_id:: param id for each component
Param first_block:: first block of large block.
Param last_block:: last block of large block.
Param data_offset:: block offset in large block.
Param data:: block data.
Return:: 0 if succeeded, error code otherwise.

uint64_t (*get_total_data_processed)(struct comp_dev *dev, uint32_t stream_no, bool input)

Returns total data processed in number bytes.

Param dev:: Component device
Param stream_no:: Index of input/output stream
Param input:: Selects between input (true) or output (false) stream direction
Return:: total data processed if succeeded, 0 otherwise.

struct comp_driver

#include <component.h>

Audio component base driver “class”.

used by all other component types.

Public Members

uint32_t type: SOF_COMP_ for driver.

const struct sof_uuid *uid: Address to UUID value.

struct tr_ctx *tctx: Pointer to trace context.

struct comp_ops ops: component operations

const struct module_interface *adapter_ops

module specific operations.

Intended to replace the ops field. Currently used by module_adapter.

struct comp_driver_info

#include <component.h>

Holds constant pointer to component driver.

Public Members

const struct comp_driver *drv: pointer to component driver

struct list_item list: list of component drivers

struct comp_ipc_config

#include <component.h>

Audio component base configuration from IPC at creation.

Public Members

uint32_t core: core we run on

uint32_t id: component id

uint32_t pipeline_id: component pipeline id

uint32_t proc_domain: processing domain - LL or DP

enum sof_comp_type type: component type

uint32_t periods_sink: 0 means variable

uint32_t periods_source: 0 means variable

uint32_t frame_fmt: SOF_IPC_FRAME_.

uint32_t xrun_action: action we should take on XRUN

struct comp_perf_data

#include <component.h>

Public Members

size_t peak_of_measured_cpc

struct perf_data_item_comp *perf_data_item

struct comp_dev

#include <component.h>

Audio component base device “class”.

used by other component types.

Public Members

uint16_t state: COMP_STATE_.

uint32_t frames: number of frames we copy to sink

struct pipeline *pipeline: pipeline we belong to

struct task *task: component’s processing task used 1) for components running on different core than the rest of the pipeline 2) for all DP tasks

uint32_t size: component’s allocated size

uint32_t period: component’s processing period for LL modules is set to LL pipeline’s period for DP module its meaning is “the time the module MUST provide data that allows the following module to perform without glitches”

uint32_t priority: component’s processing priority

bool is_shared: indicates whether component is shared across cores

struct comp_ipc_config ipc_config: Component IPC configuration.

struct tr_ctx tctx: trace settings

uint32_t direction: enum sof_ipc_stream_direction

bool direction_set: flag indicating that the direction has been set

const struct comp_driver *drv: driver

struct processing_module *mod: self->mod->dev == self, NULL if component is not using module adapter

struct list_item bsource_list: list of source buffers

struct list_item bsink_list: list of sink buffers

struct comp_perf_data perf_data

size_t ibs

size_t obs

size_t cpc

size_t ll_chunk_size

void *priv_data: private data

group Component's Common Helpers

Component registration

int comp_register(struct comp_driver_info *drv)

Registers the component driver on the list of available components.

Parameters:: drv – Component driver to be registered.
Returns:: 0 if succeeded, error code otherwise.

void comp_unregister(struct comp_driver_info *drv)

Unregisters the component driver from the list of available components.

Parameters:: drv – Component driver to be unregistered.

XRUN handling.

static inline void comp_underrun(struct comp_dev *dev, struct comp_buffer *source, uint32_t copy_bytes)

Called by the component device when underrun is detected.

Parameters:

dev – Component device.
source – Source buffer.
copy_bytes – Requested size of data to be available.

static inline void comp_overrun(struct comp_dev *dev, struct comp_buffer *sink, uint32_t copy_bytes)

Called by component device when overrun is detected.

Parameters:

dev – Component device.
sink – Sink buffer.
copy_bytes – Requested size of free space to be available.

Defines

comp_set_drvdata(c, data)

Assigns private data to component device.

Parameters:

c – Component device.
data – Private data.

comp_get_drvdata(c)

Retrieves driver private data from component device.

Parameters:

c – Component device.

Returns:

Private data.

DECLARE_MODULE(init): Usage at the end of an independent module file: DECLARE_MODULE(sys_*_init);.

Functions

static inline uint32_t dev_comp_id(const struct comp_dev *dev)

Retrieves Component id from device.

Parameters:: dev – Device.
Returns:: Component id.

static inline uint32_t dev_comp_pipe_id(const struct comp_dev *dev)

Retrieves Component pipeline id from device.

Parameters:: dev – Device.
Returns:: Component pipeline id.

static inline enum sof_comp_type dev_comp_type(const struct comp_dev *dev)

Retrieves component type from device.

Parameters:: dev – Device.
Returns:: Component type.

static inline struct comp_dev *comp_alloc(const struct comp_driver *drv, size_t bytes)

Allocates memory for the component device and initializes common part.

Parameters:

drv – Parent component driver.
bytes – Size of the component device in bytes.

Returns:

Pointer to the component device.

static inline struct processing_module *comp_mod(const struct comp_dev *dev)

Module adapter associated with a component.

Parameters:: dev – Component device

int comp_set_state(struct comp_dev *dev, int cmd)

Component state set.

This function should be called by a component implementation at the beginning of its state transition to verify whether the trigger is valid in the current state and abort the transition otherwise.

Typically the COMP_STATE_READY as the initial state is set directly by the component’s implementation of _new().

COMP_TRIGGER_PREPARE is called from the component’s prepare().

COMP_TRIGGER_START/STOP is called from trigger().

COMP_TRIGGER_RESET is called from reset().

Parameters:

dev – Component device.
cmd – Command, one of COMP_TRIGGER_….

Returns:

0 if succeeded, error code otherwise.

static inline void component_set_nearest_period_frames(struct comp_dev *current, uint32_t rate)

void comp_get_copy_limits(struct comp_buffer *source, struct comp_buffer *sink, struct comp_copy_limits *cl)

Computes source to sink copy operation boundaries including maximum number of frames that can be transferred (data available in source vs.

free space available in sink).

Parameters:

source – [in] Source buffer.
sink – [in] Sink buffer.
cl – [out] Current copy limits.

void comp_get_copy_limits_frame_aligned(const struct comp_buffer *source, const struct comp_buffer *sink, struct comp_copy_limits *cl)

Computes source to sink copy operation boundaries including maximum number of frames aligned with requirement that can be transferred (data available in source vs.

free space available in sink).

Parameters:

source – [in] Buffer of source.
sink – [in] Buffer of sink.
cl – [out] Current copy limits.

static inline int comp_get_state(const struct comp_dev *dev)

Get component state.

Parameters:: dev – Component from which user wants to read status.
Return values:: COMP_STATE_NOT_EXIST – if there’s no connected component
Returns:: state of the component

static inline int comp_buffer_get_source_state(const struct comp_buffer *buffer)

helper, provide state of a component connected to a buffer as a data provider

Parameters:: buffer – a buffer to be checked
Return values:: COMP_STATE_NOT_EXIST – if there’s no connected component
Returns:: state of the component

static inline int comp_buffer_get_sink_state(const struct comp_buffer *buffer)

helper, provide state of a component connected to a buffer as a data consumer

Parameters:: buffer – a buffer to be checked
Return values:: COMP_STATE_NOT_EXIST – if there’s no connected component
Returns:: state of the component

int comp_verify_params(struct comp_dev *dev, uint32_t flag, struct sof_ipc_stream_params *params)

Warning: duplicate declaration in topology.h.

Called by component in params() function in order to set and update some of downstream (playback) or upstream (capture) buffer parameters with pcm parameters. There is a possibility to specify which of parameters won’t be overwritten (e.g. SRC component should not overwrite rate parameter, because it is able to change it).

Parameters:

dev – Component device
flag – Specifies which parameter should not be updated
params – pcm params

struct comp_copy_limits

#include <component.h>

Struct for use with comp_get_copy_limits() function.

Public Members

int frames

int source_bytes

int sink_bytes

int source_frame_bytes

int sink_frame_bytes