mirror of https://github.com/thesofproject/sof.git
comp: dox: complete and clean up api documentation
Merged the documentation of the component api and infrastructure helpers. Removed unnesessary dox groups that did not improve readability. Completed missing dox parts. Signed-off-by: Marcin Maka <marcin.maka@linux.intel.com>
This commit is contained in:
Marcin Maka
Tomasz Lauda
parent
ac01040efe
commit
6ed1d32f70
|
|
@ -47,7 +47,6 @@ struct sof_ipc_stream_posn;
|
|||
struct dai_hw_params;
|
||||
|
||||
/** \addtogroup component_api Component API
|
||||
* Component API specification.
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -223,70 +222,159 @@ enum comp_copy_type {
|
|||
struct comp_driver;
|
||||
|
||||
/**
|
||||
* Audio component operations - all mandatory.
|
||||
* Audio component operations.
|
||||
*
|
||||
* All component operations must return 0 for success, negative values for
|
||||
* errors and 1 to stop the pipeline walk operation.
|
||||
* errors and 1 to stop the pipeline walk operation unless specified otherwise
|
||||
* in the operation documentation.
|
||||
*/
|
||||
struct comp_ops {
|
||||
/** component creation */
|
||||
/**
|
||||
* Creates a new component device.
|
||||
* @param drv Parent component driver.
|
||||
* @param comp Component parameters.
|
||||
* @return Pointer to the new component device.
|
||||
*
|
||||
* All required data objects should be allocated from the run-time
|
||||
* heap (RZONE_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.
|
||||
*/
|
||||
struct comp_dev *(*new)(const struct comp_driver *drv,
|
||||
struct sof_ipc_comp *comp);
|
||||
|
||||
/** component destruction */
|
||||
/**
|
||||
* Called to delete the specified component device.
|
||||
* @param dev Component device to be deleted.
|
||||
*
|
||||
* All data structures previously allocated on the run-time heap
|
||||
* must be freed by the implementation of <code>free()</code>.
|
||||
*/
|
||||
void (*free)(struct comp_dev *dev);
|
||||
|
||||
/** set component audio stream parameters */
|
||||
/**
|
||||
* Sets component audio stream parameters.
|
||||
* @param dev Component device.
|
||||
* @param params Audio (PCM) stream parameters to be set.
|
||||
*/
|
||||
int (*params)(struct comp_dev *dev,
|
||||
struct sof_ipc_stream_params *params);
|
||||
|
||||
/** get dai hw parameters */
|
||||
/**
|
||||
* Fetches hardware stream parameters.
|
||||
* @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).
|
||||
*
|
||||
* Mandatory for components that allocate DAI.
|
||||
*/
|
||||
int (*dai_get_hw_params)(struct comp_dev *dev,
|
||||
struct sof_ipc_stream_params *params, int dir);
|
||||
|
||||
/** set component audio stream parameters */
|
||||
/**
|
||||
* Configures attached DAI.
|
||||
* @param dev Component device.
|
||||
* @param dai_config DAI configuration.
|
||||
*
|
||||
* Mandatory for components that allocate DAI.
|
||||
*/
|
||||
int (*dai_config)(struct comp_dev *dev,
|
||||
struct sof_ipc_dai_config *dai_config);
|
||||
|
||||
/** used to pass standard and bespoke commands (with optional data) */
|
||||
/**
|
||||
* Used to pass standard and bespoke commands (with optional data).
|
||||
* @param dev Component device.
|
||||
* @param cmd Command.
|
||||
* @param data Command data.
|
||||
* @param max_data_size Max size of returned data acceptable by the
|
||||
* caller in case of 'get' commands.
|
||||
*/
|
||||
int (*cmd)(struct comp_dev *dev, int cmd, void *data,
|
||||
int max_data_size);
|
||||
|
||||
/** atomic - used to start/stop/pause stream operations */
|
||||
/**
|
||||
* Trigger, atomic - used to start/stop/pause stream operations.
|
||||
* @param dev Component device.
|
||||
* @param cmd Command, one of COMP_TRIGGER_...
|
||||
*/
|
||||
int (*trigger)(struct comp_dev *dev, int cmd);
|
||||
|
||||
/** prepare component after params are set */
|
||||
/**
|
||||
* Prepares component after params are set.
|
||||
* @param dev Component device.
|
||||
*/
|
||||
int (*prepare)(struct comp_dev *dev);
|
||||
|
||||
/** reset component */
|
||||
/**
|
||||
* Resets component.
|
||||
* @param dev Component device.
|
||||
*/
|
||||
int (*reset)(struct comp_dev *dev);
|
||||
|
||||
/** copy and process stream data from source to sink buffers */
|
||||
/**
|
||||
* Copy and process stream data from source to sink buffers.
|
||||
* @param dev Component device.
|
||||
* @return Number of copied frames.
|
||||
*/
|
||||
int (*copy)(struct comp_dev *dev);
|
||||
|
||||
/** position */
|
||||
/**
|
||||
* Retrieves component rendering position.
|
||||
* @param dev Component device.
|
||||
* @param posn Receives reported position.
|
||||
*/
|
||||
int (*position)(struct comp_dev *dev,
|
||||
struct sof_ipc_stream_posn *posn);
|
||||
|
||||
/** set attribute in component */
|
||||
/**
|
||||
* Sets 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);
|
||||
|
||||
/* Configure timestamping */
|
||||
/**
|
||||
* Configures timestamping in attached DAI.
|
||||
* @param dev Component device.
|
||||
*
|
||||
* Mandatory for components that allocate DAI.
|
||||
*/
|
||||
int (*dai_ts_config)(struct comp_dev *dev);
|
||||
|
||||
/* Start timestamping */
|
||||
/**
|
||||
* Starts timestamping.
|
||||
* @param dev Component device.
|
||||
*
|
||||
* Mandatory for components that allocate DAI.
|
||||
*/
|
||||
int (*dai_ts_start)(struct comp_dev *dev);
|
||||
|
||||
/* Stop timestamping */
|
||||
/**
|
||||
* Stops timestamping.
|
||||
* @param dev Component device.
|
||||
*
|
||||
* Mandatory for components that allocate DAI.
|
||||
*/
|
||||
int (*dai_ts_stop)(struct comp_dev *dev);
|
||||
|
||||
/* Get timestamp */
|
||||
/**
|
||||
* Gets timestamp.
|
||||
* @param dev Component device.
|
||||
* @param tsd Receives timestamp data.
|
||||
*
|
||||
* Mandatory for components that allocate DAI.
|
||||
*/
|
||||
int (*dai_ts_get)(struct comp_dev *dev,
|
||||
struct timestamp_data *tsd);
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
* Audio component base driver "class"
|
||||
* - used by all other component types.
|
||||
|
|
@ -354,7 +442,13 @@ struct comp_dev {
|
|||
struct sof_ipc_comp comp;
|
||||
};
|
||||
|
||||
/** \name Helpers.
|
||||
/** @}*/
|
||||
|
||||
/* Common helper function used internally by the component implementations
|
||||
* begin here.
|
||||
*/
|
||||
|
||||
/** \addtogroup component_common_int Component's Common Helpers
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
|
@ -435,21 +529,22 @@ static inline struct sof_ipc_comp_config *comp_config(struct sof_ipc_comp *comp)
|
|||
return (struct sof_ipc_comp_config *)(comp + 1);
|
||||
}
|
||||
|
||||
/** \brief Sets the driver private data. */
|
||||
/**
|
||||
* \brief Assigns private data to component device.
|
||||
* @param c Component device.
|
||||
* @param data Private data.
|
||||
*/
|
||||
#define comp_set_drvdata(c, data) \
|
||||
(c->private = data)
|
||||
|
||||
/** \brief Retrieves the driver private data. */
|
||||
/**
|
||||
* \brief Retrieves driver private data from component device.
|
||||
* @param c Component device.
|
||||
* @return Private data.
|
||||
*/
|
||||
#define comp_get_drvdata(c) \
|
||||
c->private
|
||||
|
||||
/** @}*/
|
||||
|
||||
/** \name Declare module macro
|
||||
* \brief Usage at the end of an independent module file:
|
||||
* DECLARE_MODULE(sys_*_init);
|
||||
* @{
|
||||
*/
|
||||
#ifdef UNIT_TEST
|
||||
#define DECLARE_MODULE(init)
|
||||
#elif CONFIG_LIBRARY
|
||||
|
|
@ -457,12 +552,13 @@ static inline struct sof_ipc_comp_config *comp_config(struct sof_ipc_comp *comp)
|
|||
#define DECLARE_MODULE(init) __attribute__((constructor)) \
|
||||
static void _module_init(void) { init(); }
|
||||
#else
|
||||
/** \brief Usage at the end of an independent module file:
|
||||
* DECLARE_MODULE(sys_*_init);
|
||||
*/
|
||||
#define DECLARE_MODULE(init) __attribute__((__used__)) \
|
||||
__section(".module_init") static void(*f)(void) = init
|
||||
#endif
|
||||
|
||||
/** @}*/
|
||||
|
||||
/** \name Component registration
|
||||
* @{
|
||||
*/
|
||||
|
|
@ -482,10 +578,6 @@ void comp_unregister(struct comp_driver_info *drv);
|
|||
|
||||
/** @}*/
|
||||
|
||||
/** \name Component API.
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Component state set.
|
||||
* @param dev Component device.
|
||||
|
|
@ -507,12 +599,6 @@ void comp_unregister(struct comp_driver_info *drv);
|
|||
*/
|
||||
int comp_set_state(struct comp_dev *dev, int cmd);
|
||||
|
||||
/** @}*/
|
||||
|
||||
/** \name Helpers.
|
||||
* @{
|
||||
*/
|
||||
|
||||
/* \brief Set component period frames */
|
||||
static inline void component_set_period_frames(struct comp_dev *current,
|
||||
uint32_t rate)
|
||||
|
|
@ -524,8 +610,6 @@ static inline void component_set_period_frames(struct comp_dev *current,
|
|||
current->frames = ceil_divide(rate * current->period, 1000000);
|
||||
}
|
||||
|
||||
/** @}*/
|
||||
|
||||
/** \name XRUN handling.
|
||||
* @{
|
||||
*/
|
||||
|
|
@ -567,6 +651,8 @@ static inline void comp_overrun(struct comp_dev *dev, struct comp_buffer *sink,
|
|||
pipeline_xrun(dev->pipeline, dev, bytes);
|
||||
}
|
||||
|
||||
/** @}*/
|
||||
|
||||
/**
|
||||
* Called by component in copy.
|
||||
* @param source Source buffer.
|
||||
|
|
@ -591,6 +677,4 @@ int comp_verify_params(struct comp_dev *dev, uint32_t flag,
|
|||
|
||||
/** @}*/
|
||||
|
||||
/** @}*/
|
||||
|
||||
#endif /* __SOF_AUDIO_COMPONENT_H__ */
|
||||
|
|
|
|||
|
|
@ -37,23 +37,10 @@ struct comp_driver_list {
|
|||
((dir) == PPL_DIR_DOWNSTREAM ? &comp->bsink_list : \
|
||||
&comp->bsource_list)
|
||||
|
||||
/** \name Component creation and destruction - mandatory
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Creates a new component device.
|
||||
* @param comp Parameters of the new component device.
|
||||
* @return Pointer to the new component device.
|
||||
*/
|
||||
/** See comp_ops::new */
|
||||
struct comp_dev *comp_new(struct sof_ipc_comp *comp);
|
||||
|
||||
/**
|
||||
* Called to delete the specified component device.
|
||||
* All data structures previously allocated on the run-time heap
|
||||
* must be freed by the implementation of <code>free()</code>.
|
||||
* @param dev Component device to be deleted.
|
||||
*/
|
||||
/** See comp_ops::free */
|
||||
static inline void comp_free(struct comp_dev *dev)
|
||||
{
|
||||
assert(dev->drv->ops.free);
|
||||
|
|
@ -67,8 +54,6 @@ static inline void comp_free(struct comp_dev *dev)
|
|||
dev->drv->ops.free(dev);
|
||||
}
|
||||
|
||||
/** @}*/
|
||||
|
||||
/**
|
||||
* Commits component's memory if it's shared.
|
||||
* @param dev Component device.
|
||||
|
|
@ -94,12 +79,7 @@ static inline int comp_params_remote(struct comp_dev *dev,
|
|||
return idc_send_msg(&msg, IDC_BLOCKING);
|
||||
}
|
||||
|
||||
/**
|
||||
* Component parameter init.
|
||||
* @param dev Component device.
|
||||
* @param params Audio (PCM) stream parameters to be set
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** See comp_ops::params */
|
||||
static inline int comp_params(struct comp_dev *dev,
|
||||
struct sof_ipc_stream_params *params)
|
||||
{
|
||||
|
|
@ -115,13 +95,7 @@ static inline int comp_params(struct comp_dev *dev,
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetch hardware stream parameters - only mandatory for DAI components.
|
||||
* @param dev Component device.
|
||||
* @param params hw parameters
|
||||
* @param dir Pipeline direction (see enum sof_ipc_stream_direction).
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** See comp_ops::dai_get_hw_params */
|
||||
static inline int comp_dai_get_hw_params(struct comp_dev *dev,
|
||||
struct sof_ipc_stream_params *params,
|
||||
int dir)
|
||||
|
|
@ -136,14 +110,7 @@ static inline int comp_dai_get_hw_params(struct comp_dev *dev,
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* Send component command.
|
||||
* @param dev Component device.
|
||||
* @param cmd Command.
|
||||
* @param data Command data.
|
||||
* @param max_data_size Max data size.
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** See comp_ops::cmd */
|
||||
static inline int comp_cmd(struct comp_dev *dev, int cmd, void *data,
|
||||
int max_data_size)
|
||||
{
|
||||
|
|
@ -154,7 +121,7 @@ static inline int comp_cmd(struct comp_dev *dev, int cmd, void *data,
|
|||
(cdata->data->magic != SOF_ABI_MAGIC ||
|
||||
SOF_ABI_VERSION_INCOMPATIBLE(SOF_ABI_VERSION, cdata->data->abi))) {
|
||||
comp_err(dev, "comp_cmd() error: invalid version, data->magic = %u, data->abi = %u",
|
||||
cdata->data->magic, cdata->data->abi);
|
||||
cdata->data->magic, cdata->data->abi);
|
||||
goto out;
|
||||
}
|
||||
|
||||
|
|
@ -168,10 +135,7 @@ out:
|
|||
}
|
||||
|
||||
/**
|
||||
* Triggers command for component on other core.
|
||||
* @param dev Component device.
|
||||
* @param cmd Command to be triggered.
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
* Runs comp_ops::trigger on the core the target component is assigned to.
|
||||
*/
|
||||
static inline int comp_trigger_remote(struct comp_dev *dev, int cmd)
|
||||
{
|
||||
|
|
@ -182,12 +146,7 @@ static inline int comp_trigger_remote(struct comp_dev *dev, int cmd)
|
|||
return idc_send_msg(&msg, IDC_BLOCKING);
|
||||
}
|
||||
|
||||
/**
|
||||
* Trigger component - mandatory and atomic.
|
||||
* @param dev Component device.
|
||||
* @param cmd Command.
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** See comp_ops::trigger */
|
||||
static inline int comp_trigger(struct comp_dev *dev, int cmd)
|
||||
{
|
||||
int ret = 0;
|
||||
|
|
@ -202,11 +161,7 @@ static inline int comp_trigger(struct comp_dev *dev, int cmd)
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* Prepares component on other core.
|
||||
* @param dev Component device.
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** Runs comp_ops::prepare on the target component's core */
|
||||
static inline int comp_prepare_remote(struct comp_dev *dev)
|
||||
{
|
||||
struct idc_msg msg = { IDC_MSG_PREPARE,
|
||||
|
|
@ -215,11 +170,7 @@ static inline int comp_prepare_remote(struct comp_dev *dev)
|
|||
return idc_send_msg(&msg, IDC_BLOCKING);
|
||||
}
|
||||
|
||||
/**
|
||||
* Prepare component.
|
||||
* @param dev Component device.
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** See comp_ops::prepare */
|
||||
static inline int comp_prepare(struct comp_dev *dev)
|
||||
{
|
||||
int ret = 0;
|
||||
|
|
@ -233,11 +184,7 @@ static inline int comp_prepare(struct comp_dev *dev)
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* Copy component buffers - mandatory.
|
||||
* @param dev Component device.
|
||||
* @return Number of frames copied.
|
||||
*/
|
||||
/** See comp_ops::copy */
|
||||
static inline int comp_copy(struct comp_dev *dev)
|
||||
{
|
||||
int ret = 0;
|
||||
|
|
@ -253,13 +200,7 @@ static inline int comp_copy(struct comp_dev *dev)
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets component attribute.
|
||||
* @param dev Component device.
|
||||
* @param type Attribute type.
|
||||
* @param value Attribute value.
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** See comp_ops::set_attribute */
|
||||
static inline int comp_set_attribute(struct comp_dev *dev, uint32_t type,
|
||||
void *value)
|
||||
{
|
||||
|
|
@ -273,11 +214,7 @@ static inline int comp_set_attribute(struct comp_dev *dev, uint32_t type,
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resets component on other core.
|
||||
* @param dev Component device.
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** Runs comp_ops::reset on the target component's core */
|
||||
static inline int comp_reset_remote(struct comp_dev *dev)
|
||||
{
|
||||
struct idc_msg msg = { IDC_MSG_RESET,
|
||||
|
|
@ -304,14 +241,9 @@ static inline int comp_reset(struct comp_dev *dev)
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* DAI configuration - only mandatory for DAI components.
|
||||
* @param dev Component device.
|
||||
* @param config DAI configuration.
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** See comp_ops::dai_config */
|
||||
static inline int comp_dai_config(struct comp_dev *dev,
|
||||
struct sof_ipc_dai_config *config)
|
||||
struct sof_ipc_dai_config *config)
|
||||
{
|
||||
int ret = 0;
|
||||
|
||||
|
|
@ -323,14 +255,9 @@ static inline int comp_dai_config(struct comp_dev *dev,
|
|||
return ret;
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves component rendering position.
|
||||
* @param dev Component device.
|
||||
* @param posn Position reported by the component device.
|
||||
* @return 0 if succeeded, error code otherwise.
|
||||
*/
|
||||
/** See comp_ops::position */
|
||||
static inline int comp_position(struct comp_dev *dev,
|
||||
struct sof_ipc_stream_posn *posn)
|
||||
struct sof_ipc_stream_posn *posn)
|
||||
{
|
||||
int ret = 0;
|
||||
|
||||
|
|
@ -342,18 +269,12 @@ static inline int comp_position(struct comp_dev *dev,
|
|||
return ret;
|
||||
}
|
||||
|
||||
/** \name Components API for infrastructure.
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Allocates and initializes audio component list.
|
||||
* To be called once at boot time.
|
||||
*/
|
||||
void sys_comp_init(struct sof *sof);
|
||||
|
||||
/** @}*/
|
||||
|
||||
/**
|
||||
* Checks if two component devices belong to the same parent pipeline.
|
||||
* @param current Component device.
|
||||
|
|
|
|||
Loading…
Reference in New Issue