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

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.

Standard Component Stream Commands

TODO: use IPC versions after 1.1

COMP_TRIGGER_STOP

Stop component stream.

COMP_TRIGGER_START

Start component stream.

COMP_TRIGGER_PAUSE

Pause the component stream.

COMP_TRIGGER_RELEASE

Release paused component stream.

COMP_TRIGGER_SUSPEND

Suspend component.

COMP_TRIGGER_RESUME

Resume component.

COMP_TRIGGER_RESET

Reset component.

COMP_TRIGGER_PREPARE

Prepare component.

COMP_TRIGGER_XRUN

XRUN component.

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.

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)

Enums

enum comp_endpoint_type

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

Values:

COMP_ENDPOINT_HOST

Connected to host dma.

COMP_ENDPOINT_DAI

Connected to dai dma.

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:

COMP_COPY_NORMAL = 0

Normal.

COMP_COPY_BLOCKING

Blocking.

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, struct sof_ipc_comp *comp)

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().
Return

Pointer to the new component device.

Parameters

  • drv: Parent component driver.

  • comp: Component parameters.

All parameters should be initialized to their default values.

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().
Parameters

  • 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.
Parameters

  • dev: Component device.

  • 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.

Parameters

  • dev: Component device.

  • params: Receives copy of stream parameters retrieved from DAI hw settings.

  • dir: Stream direction (see enum sof_ipc_stream_direction).

int (*dai_config)(struct comp_dev *dev, struct sof_ipc_dai_config *dai_config)

Configures attached DAI.

Mandatory for components that allocate DAI.

Parameters

  • dev: Component device.

  • dai_config: DAI configuration.

int (*cmd)(struct comp_dev *dev, int cmd, void *data, int max_data_size)

Used to pass standard and bespoke commands (with optional data).

Parameters

  • dev: Component device.

  • cmd: Command.

  • data: Command data.

  • max_data_size: Max size of returned data acceptable by the caller in case of ‘get’ commands.

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

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

Parameters

  • dev: Component device.

  • 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.

Parameters

  • 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. TODO: Some components are not compliant here wrt

reset(). Fix this in v1.8.
Parameters

  • dev: Component device.

int (*copy)(struct comp_dev *dev)

Copy and process stream data from source to sink buffers.

Return

Number of copied frames.

Parameters

  • dev: Component device.

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

Retrieves component rendering position.

Parameters

  • dev: Component device.

  • posn: Receives reported position.

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

Sets attribute in component.

Return

0 if succeeded, error code otherwise.

Parameters

  • dev: Component device.

  • type: Attribute type.

  • value: Attribute value.

int (*dai_ts_config)(struct comp_dev *dev)

Configures timestamping in attached DAI.

Mandatory for components that allocate DAI.

Parameters

  • dev: Component device.

int (*dai_ts_start)(struct comp_dev *dev)

Starts timestamping.

Mandatory for components that allocate DAI.

Parameters

  • dev: Component device.

int (*dai_ts_stop)(struct comp_dev *dev)

Stops timestamping.

Mandatory for components that allocate DAI.

Parameters

  • dev: Component device.

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

Gets timestamp.

Mandatory for components that allocate DAI.

Parameters

  • dev: Component device.

  • tsd: Receives timestamp data.

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_dev
#include <component.h>

Audio component base device “class”.

  • used by other component types.

Public Members

uint16_t state

COMP_STATE_.

uint64_t position

component rendering position

uint32_t frames

number of frames we copy to sink

struct pipeline *pipeline

pipeline we belong to

uint32_t min_sink_bytes

min free sink buffer size measured in bytes required to run component’s processing

uint32_t min_source_bytes

amount of data measured in bytes available at source buffer required to run component’s processing

struct task *task

component’s processing task used only for components running on different core than the rest of the pipeline

uint32_t size

component’s allocated size

uint32_t period

component’s processing period

uint32_t priority

component’s processing priority

bool is_shared

indicates whether component is shared across cores

struct tr_ctx tctx

trace settings

uint32_t direction

enum sof_ipc_stream_direction

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

struct sof_ipc_comp comp

IPC config object header - MUST be at end as it’s variable size/type.

group component_common_int

Component registration

int comp_register(struct comp_driver_info *drv)

Registers the component driver on the list of available components.

Return

0 if succeeded, error code otherwise.

Parameters

  • drv: Component driver to be registered.

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 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 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_SIZE(x)

Computes size of the component device including ipc config.

COMP_GET_IPC(dev, type)

Retrieves component device IPC configuration.

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.

Return

Private data.

Parameters

  • c: Component device.

DECLARE_MODULE(init)

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

Functions

static struct sof_ipc_comp *dev_comp(struct comp_dev *dev)

Retrieves component from device.

Return

Pointer to the component.

Parameters

  • dev: Device.

static uint32_t dev_comp_id(const struct comp_dev *dev)

Retrieves Component id from device.

Return

Component id.

Parameters

  • dev: Device.

static uint32_t dev_comp_pipe_id(const struct comp_dev *dev)

Retrieves Component pipeline id from device.

Return

Component pipeline id.

Parameters

  • dev: Device.

static enum sof_comp_type dev_comp_type(const struct comp_dev *dev)

Retrieves component type from device.

Return

Component type.

Parameters

  • dev: Device.

static struct sof_ipc_comp_config *dev_comp_config(struct comp_dev *dev)

Retrieves component config data from device.

Return

Pointer to the component data.

Parameters

  • dev: Device.

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

Allocates memory for the component device and initializes common part.

Return

Pointer to the component device.

Parameters

  • drv: Parent component driver.

  • bytes: Size of the component device in bytes.

static struct sof_ipc_comp_config *comp_config(struct sof_ipc_comp *comp)

Retrieves component config data from component ipc.

Return

Pointer to the component config data.

Parameters

  • comp: Component ipc data.

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.

Return

0 if succeeded, error code otherwise.

Parameters

  • dev: Component device.

  • cmd: Command, one of COMP_TRIGGER_….

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().

static void component_set_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

  • [in] source: Source buffer.

  • [in] sink: Sink buffer.

  • [out] cl: Current copy limits.

static void comp_get_copy_limits_with_lock(struct comp_buffer *source, struct comp_buffer *sink, struct comp_copy_limits *cl)

Version of comp_get_copy_limits that locks both buffers to guarantee consistent state readings.

Parameters

  • [in] source: Source buffer.

  • [in] sink: Sink buffer

  • [out] cl: Current copy limits.

static void comp_invalidate(struct comp_dev *dev)

Invalidates component to ensure current state and params readout.

Parameters

  • dev: Component to invalidate

static void comp_writeback(struct comp_dev *dev)

Writeback component to ensure current state and params readout.

Parameters

  • dev: Component to writeback

static 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.

void *comp_get_data_blob(struct comp_data_blob_handler *blob_handler, size_t *size, uint32_t *crc)

Returns data blob.

In case when new data blob is available it returns new one. Function returns also data blob size in case when size pointer is given.

Parameters

  • blob_handler: Data blob handler

  • size: Pointer to data blob size variable

  • crc: Pointer to data blolb crc value

bool comp_is_new_data_blob_available(struct comp_data_blob_handler *blob_handler)

Checks whether new data blob is available.

Function allows to check (even during streaming - in copy() function) whether new config is available and if it is, component can perform reconfiguration.

Parameters

  • blob_handler: Data blob handler

int comp_init_data_blob(struct comp_data_blob_handler *blob_handler, uint32_t size, void *init_data)

Initilizes data blob with given value.

If init_data is not specified, function will zero data blob.

Parameters

  • blob_handler: Data blob handler

  • size: Data blob size

  • init_data: Initial data blob values

int comp_data_blob_set_cmd(struct comp_data_blob_handler *blob_handler, struct sof_ipc_ctrl_data *cdata)

Handles IPC set command.

Parameters

  • blob_handler: Data blob handler

  • cdata: IPC ctrl data

int comp_data_blob_get_cmd(struct comp_data_blob_handler *blob_handler, struct sof_ipc_ctrl_data *cdata, int size)

Handles IPC get command.

Parameters

  • blob_handler: Data blob handler

  • cdata: IPC ctrl data

  • size: Required size

struct comp_data_blob_handler *comp_data_blob_handler_new(struct comp_dev *dev)

Returns new data blob handler.

Parameters

  • dev: Component device

void comp_data_blob_handler_free(struct comp_data_blob_handler *blob_handler)

Free data blob handler.

Parameters

  • blob_handler: Data blob handler

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

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