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_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

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.

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 *ipc_specific_config)

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 comp:

Component parameters.

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

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_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 list_item bsource_list

list of source buffers

struct list_item bsink_list

list of sink buffers

void *priv_data

private data

group component_common_int

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.

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(struct comp_dev *req_dev, struct comp_dev *dev)

Get component state.

Parameters:
  • req_dev – Requesting component

  • dev – Component from which user wants to read status.

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