Component API

Location: include/sof/audio/component.h

group component_api

Component API specification.

Audio Component States

COMP_STATE_INIT

States may transform as below:-.

*                                  +---------------------------------------+
*                                  |                                       |
*                            -------------                                 |
*                   pause    |           |    stop                         |
*              +-------------| ACTIVITY  |---------------+                 |
*              |             |           |               |      prepare    |
*              |             -------------               |   +---------+   |
*              |                ^     ^                  |   |         |   |
*              |                |     |                  |   |         |   |
*              v                |     |                  v   |         |   |
*       -------------           |     |             -------------      |   |
*       |           |   release |     |   start     |           |      |   |
*       |   PAUSED  |-----------+     +-------------|  PREPARE  |<-----+   |
*       |           |                               |           |          |
*       -------------                               -------------          |
*              |                                      ^     ^              |
*              |               stop                   |     |              |
*              +--------------------------------------+     |              |
*                                                           | prepare      |
*                            -------------                  |              |
*                            |           |                  |              |
*                ----------->|   READY   |------------------+              |
*                    reset   |           |                                 |
*                            -------------                                 |
*                                  ^                                       |
*                                  |                 xrun                  |
*                                  +---------------------------------------+
*
*
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_get_id(comp_p)
trace_comp_get_subid(comp_p)
comp_cl_err(drv_p, __e, ...)
comp_cl_info(drv_p, __e, ...)
comp_cl_dbg(drv_p, __e, ...)
comp_err(comp_p, __e, ...)
comp_info(comp_p, __e, ...)
comp_dbg(comp_p, __e, ...)

Helpers.

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

static int comp_is_single_pipeline(struct comp_dev * current, struct comp_dev * previous)

Checks if two component devices belong to the same parent pipeline.

Return
1 if children of the same pipeline, 0 otherwise.
Parameters
  • current: Component device.
  • previous: Another component device.

static int comp_is_active(struct comp_dev * current)

Checks if component device is active.

Return
1 if active, 0 otherwise.
Parameters
  • current: Component device.

static int comp_get_requested_state(int cmd)

Returns component state based on requested command.

Return
Component state.
Parameters
  • cmd: Request command.

static int comp_get_endpoint_type(struct comp_dev * dev)
static void component_set_period_frames(struct comp_dev * current, uint32_t rate)
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)

Sets the driver private data.

comp_get_drvdata(c)

Retrieves the driver private data.

comp_buffer_list(comp, dir)

Retrieves the component device buffer list.

Declare module macro

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

DECLARE_MODULE(init)

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.

Component creation and destruction - mandatory

struct comp_dev* comp_new(struct sof_ipc_comp * comp)

Creates a new component device.

Return
Pointer to the new component device.
Parameters
  • comp: Parameters of the new component device.

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

Component API.

int comp_set_state(struct comp_dev * dev, int cmd)

Component state set.

Return
0 if succeeded, error code otherwise.
Parameters
  • dev: Component device.
  • cmd: Command, one of COMP_TRIGGER_….

static int comp_params(struct comp_dev * dev, struct sof_ipc_stream_params * params)

Component parameter init.

Return
0 if succeeded, error code otherwise.
Parameters
  • dev: Component device.
  • params: Audio (PCM) stream parameters to be set

static int comp_dai_get_hw_params(struct comp_dev * dev, struct sof_ipc_stream_params * params)

Fetch hardware stream parameters - only mandatory for DAI components.

Return
0 if succeeded, error code otherwise.
Parameters
  • dev: Component device.
  • params: hw parameters

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

Send component command.

Return
0 if succeeded, error code otherwise.
Parameters
  • dev: Component device.
  • cmd: Command.
  • data: Command data.
  • max_data_size: Max data size.

static int comp_trigger(struct comp_dev * dev, int cmd)

Trigger component - mandatory and atomic.

Return
0 if succeeded, error code otherwise.
Parameters
  • dev: Component device.
  • cmd: Command.

static int comp_prepare(struct comp_dev * dev)

Prepare component.

Return
0 if succeeded, error code otherwise.
Parameters
  • dev: Component device.

static int comp_copy(struct comp_dev * dev)

Copy component buffers - mandatory.

Return
Number of frames copied.
Parameters
  • dev: Component device.

static int comp_reset(struct comp_dev * dev)

Component reset and free runtime resources.

Return
0 if succeeded, error code otherwise.
Parameters
  • dev: Component device.

static int comp_dai_config(struct comp_dev * dev, struct sof_ipc_dai_config * config)

DAI configuration - only mandatory for DAI components.

Return
0 if succeeded, error code otherwise.
Parameters
  • dev: Component device.
  • config: DAI configuration.

static int comp_position(struct comp_dev * dev, struct sof_ipc_stream_posn * posn)

Retrieves component rendering position.

Return
0 if succeeded, error code otherwise.
Parameters
  • dev: Component device.
  • posn: Position reported by the component device.

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

Sets component attribute.

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

Components API for infrastructure.

void sys_comp_init(struct sof * sof)

Allocates and initializes audio component list.

To be called once at boot time.

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.

static bool comp_is_scheduling_source(struct comp_dev * dev)

Called to check whether component schedules its pipeline.

Return
True if this is scheduling component, false otherwise.
Parameters
  • dev: Component device.

int comp_get_copy_limits(struct comp_dev * dev, struct comp_copy_limits * cl)

Called by component in copy.

Parameters
  • dev: Component device.
  • cl: Struct of parameters for use in copy function.

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

static struct comp_driver_list* comp_drivers_get(void)

Enums

enum comp_endpoint_type

Values:

COMP_ENDPOINT_HOST
COMP_ENDPOINT_DAI
COMP_ENDPOINT_NODE
enum comp_copy_type

Values:

COMP_COPY_NORMAL = 0
COMP_COPY_BLOCKING
COMP_COPY_ONE_SHOT
struct comp_ops
#include <component.h>

Audio component operations - all mandatory.

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

Public Members

struct comp_dev*new)(const struct comp_driver *drv, struct sof_ipc_comp *comp)

component creation

voidfree)(struct comp_dev *dev)

component destruction

intparams)(struct comp_dev *dev, struct sof_ipc_stream_params *params)

set component audio stream parameters

intdai_get_hw_params)(struct comp_dev *dev, struct sof_ipc_stream_params *params)

get dai hw parameters

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

set component audio stream parameters

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

used to pass standard and bespoke commands (with optional data)

inttrigger)(struct comp_dev *dev, int cmd)

atomic - used to start/stop/pause stream operations

intprepare)(struct comp_dev *dev)

prepare component after params are set

intreset)(struct comp_dev *dev)

reset component

intcopy)(struct comp_dev *dev)

copy and process stream data from source to sink buffers

intposition)(struct comp_dev *dev, struct sof_ipc_stream_posn *posn)

position

intset_attribute)(struct comp_dev *dev, uint32_t type, void *value)

set attribute in component

intdai_ts_config)(struct comp_dev *dev)
intdai_ts_start)(struct comp_dev *dev)
intdai_ts_stop)(struct comp_dev *dev)
intdai_ts_get)(struct comp_dev *dev, struct timestamp_data *tsd)
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.

struct comp_ops ops

component operations

struct comp_driver_info
#include <component.h>

Public Members

const struct comp_driver* drv

pointer to component driver

struct list_item list

list of component drivers

struct comp_driver_list
#include <component.h>

Public Members

struct list_item list
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

uint32_t output_rate

0 means all output rates are fine

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

uint32_t direction

common runtime configuration for downstream/upstream

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* private

private data

struct sof_ipc_comp comp

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

struct comp_copy_limits
#include <component.h>

Struct for use with comp_get_copy_limits() function.

Public Members

struct comp_buffer* sink
struct comp_buffer* source
int frames
int source_bytes
int sink_bytes
int source_frame_bytes
int sink_frame_bytes