sink_api.h File Reference

Sink audio endpoint API for module output buffers. More...

Include dependency graph for sink_api.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	sink_ops
	this is a definition of internals of sink API More...
struct	sof_sink
	internals of sink API. More...

Functions
static size_t	sink_get_free_size (struct sof_sink *sink)
	Public functions.
static size_t	sink_get_free_frames_aligned (struct sof_sink *sink)
	Retrieves number of free frames in sink aligned to the alignment constants set by sink_set_alignment_constants().
static enum sof_ipc_frame	sink_get_frm_fmt (struct sof_sink *sink)
static uint32_t	sink_get_channels (struct sof_sink *sink)
size_t	sink_get_frame_bytes (struct sof_sink *sink)
	get size of a single audio frame (in bytes)
size_t	sink_get_free_frames (struct sof_sink *sink)
	Retrieves size of free space available in sink (in frames) return number of free frames in buffer available to immediate filling.
int	sink_get_buffer (struct sof_sink *sink, size_t req_size, void **data_ptr, void **buffer_start, size_t *buffer_size)
	Get a circular buffer to operate on (to write).
int	sink_get_buffer_s16 (struct sof_sink *sink, size_t req_size, int16_t **data_ptr, int16_t **buffer_start, size_t *buffer_samples)
	Get a circular buffer to operate on (to write).
int	sink_get_buffer_s32 (struct sof_sink *sink, size_t req_size, int32_t **data_ptr, int32_t **buffer_start, size_t *buffer_samples)
	Get a circular buffer to operate on (to write).
int	sink_commit_buffer (struct sof_sink *sink, size_t commit_size)
	Commits that the buffer previously obtained by get_buffer is filled with data and ready to be used.
int	sink_set_frm_fmt (struct sof_sink *sink, enum sof_ipc_frame frame_fmt)
	set of functions for retrieve audio parameters
static enum sof_ipc_frame	sink_get_valid_fmt (struct sof_sink *sink)
static uint32_t	sink_get_rate (struct sof_sink *sink)
static uint32_t	sink_get_buffer_fmt (struct sof_sink *sink)
int	sink_set_params (struct sof_sink *sink, struct sof_ipc_stream_params *params, bool force_update)
	initial set of audio parameters, provided in sof_ipc_stream_params
int	sink_set_alignment_constants (struct sof_sink *sink, const uint32_t byte_align, const uint32_t frame_align_req)
	Set frame_align_shift and frame_align of stream according to byte_align and frame_align_req alignment requirement.
int	sink_set_size (struct sof_sink *sink, size_t size)
	Resize the buffer backing the sink.
int	sink_set_valid_fmt (struct sof_sink *sink, enum sof_ipc_frame valid_sample_fmt)
int	sink_set_rate (struct sof_sink *sink, unsigned int rate)
int	sink_set_channels (struct sof_sink *sink, unsigned int channels)
int	sink_set_buffer_fmt (struct sof_sink *sink, uint32_t buffer_fmt)
int	sink_set_overrun (struct sof_sink *sink, bool overrun_permitted)
static size_t	sink_get_min_free_space (struct sof_sink *sink)
static uint32_t	sink_get_id (struct sof_sink *sink)
static uint32_t	sink_get_pipeline_id (struct sof_sink *sink)
static int	sink_get_state (struct sof_sink *sink)
	get the state of the component consuming data from this sink
static int	sink_bind (struct sof_sink *sink, struct processing_module *module)
	hook to be called when a module connects to the API
static int	sink_unbind (struct sof_sink *sink)
	hook to be called when a module disconnects from the API
static struct processing_module *	sink_get_bound_module (struct sof_sink *sink)
static uint32_t	sink_get_last_feeding_time (struct sof_sink *sink)

Detailed Description

Sink audio endpoint API for module output buffers.

Function Documentation

sink_bind()

static int sink_bind ( struct sof_sink *  sink, struct processing_module *  module  )

inlinestatic

hook to be called when a module connects to the API

NOTE! it MUST be called at core that a module is bound to

sink_commit_buffer()

int sink_commit_buffer	(	struct sof_sink *	sink,
		size_t	commit_size
	)

Commits that the buffer previously obtained by get_buffer is filled with data and ready to be used.

Parameters

sink	a handler to sink
commit_size	amount of data that the caller declares as valid if commit_size is bigger than the amount of data obtained before by get_buffer(), only the amount obtained before will be committed. That means - if somebody obtained a buffer, filled it with data and wants to commit it in whole, it may simple call commit_buffer with commit_size==MAXINT

Returns

proper error code (0 on success)

sink_get_bound_module()

static struct processing_module * sink_get_bound_module ( struct sof_sink *  sink )

inlinestatic

sink_get_buffer()

int sink_get_buffer	(	struct sof_sink *	sink,
		size_t	req_size,
		void **	data_ptr,
		void **	buffer_start,
		size_t *	buffer_size
	)

Get a circular buffer to operate on (to write).

Retrieves a fragment of circular data to be used by the caller After calling get_buffer, the space for data is guaranteed to be available for exclusive use on the caller core through provided pointer if the provided pointers are cached, it is guaranteed that the caller may safely use it without any additional cache operations The caller MUST take care of data circularity based on provided pointers

Parameters

	sink	a handler to sink
[in]	req_size	requested size of space
[out]	data_ptr	a pointer to the space will be provided there
[out]	buffer_start	pointer to circular buffer start
[out]	buffer_size	size of circular buffer

Return values

-ENODATA

if req_size is bigger than free space

sink_get_buffer_fmt()

static uint32_t sink_get_buffer_fmt ( struct sof_sink *  sink )

inlinestatic

sink_get_buffer_s16()

int sink_get_buffer_s16	(	struct sof_sink *	sink,
		size_t	req_size,
		int16_t **	data_ptr,
		int16_t **	buffer_start,
		size_t *	buffer_samples
	)

Get a circular buffer to operate on (to write).

Same as sink_get_buffer() except that the size of circular buffer is returned as 16 bit samples count. The returned samples count simplifies pointer arithmetic in a samples process function. The data pointers are int16_t type.

Parameters

	sink	a handler to sink
[in]	req_size	requested size of space
[out]	data_ptr	a pointer to the space will be provided there
[out]	buffer_start	pointer to circular buffer start
[out]	buffer_samples	number of s16 samples total in circular buffer

Return values

-ENODATA

if req_size is bigger than free space

sink_get_buffer_s32()

int sink_get_buffer_s32	(	struct sof_sink *	sink,
		size_t	req_size,
		int32_t **	data_ptr,
		int32_t **	buffer_start,
		size_t *	buffer_samples
	)

Get a circular buffer to operate on (to write).

Same as sink_get_buffer() except that the size of circular buffer is returned as 32 bit samples count. The returned samples count simplifies pointer arithmetic in a samples process function. The data pointers are int32_t type.

Parameters

	sink	a handler to sink
[in]	req_size	requested size of space
[out]	data_ptr	a pointer to the space will be provided there
[out]	buffer_start	pointer to circular buffer start
[out]	buffer_samples	number of s32 samples total in circular buffer

Return values

-ENODATA

if req_size is bigger than free space

sink_get_channels()

static uint32_t sink_get_channels ( struct sof_sink *  sink )

inlinestatic

sink_get_frame_bytes()

size_t sink_get_frame_bytes

(

struct sof_sink *

sink

)

get size of a single audio frame (in bytes)

sink_get_free_frames()

size_t sink_get_free_frames

(

struct sof_sink *

sink

)

Retrieves size of free space available in sink (in frames) return number of free frames in buffer available to immediate filling.

sink_get_free_frames_aligned()

static size_t sink_get_free_frames_aligned ( struct sof_sink *  sink )

inlinestatic

Retrieves number of free frames in sink aligned to the alignment constants set by sink_set_alignment_constants().

Returns

Number of aligned free frames.

sink_get_free_size()

static size_t sink_get_free_size ( struct sof_sink *  sink )

inlinestatic

Public functions.

Retrieves size of free space available in sink (in bytes) return number of free bytes in buffer available to immediate filling

sink_get_frm_fmt()

static enum sof_ipc_frame sink_get_frm_fmt ( struct sof_sink *  sink )

inlinestatic

sink_get_id()

static uint32_t sink_get_id ( struct sof_sink *  sink )

inlinestatic

sink_get_last_feeding_time()

static uint32_t sink_get_last_feeding_time ( struct sof_sink *  sink )

inlinestatic

sink_get_min_free_space()

static size_t sink_get_min_free_space ( struct sof_sink *  sink )

inlinestatic

sink_get_pipeline_id()

static uint32_t sink_get_pipeline_id ( struct sof_sink *  sink )

inlinestatic

sink_get_rate()

static uint32_t sink_get_rate ( struct sof_sink *  sink )

inlinestatic

sink_get_state()

static int sink_get_state ( struct sof_sink *  sink )

inlinestatic

get the state of the component consuming data from this sink

This allows a data producer to query the state of its downstream consumer without reaching into the underlying buffer implementation.

Parameters

sink	a sink to be checked

Returns

state of the consuming component, or COMP_STATE_NOT_EXIST (0) if there is no connected consumer or the sink implementation does not track it

sink_get_valid_fmt()

static enum sof_ipc_frame sink_get_valid_fmt ( struct sof_sink *  sink )

inlinestatic

sink_set_alignment_constants()

int sink_set_alignment_constants	(	struct sof_sink *	sink,
		const uint32_t	byte_align,
		const uint32_t	frame_align_req
	)

Set frame_align_shift and frame_align of stream according to byte_align and frame_align_req alignment requirement.

Once the channel number,frame size are determined, the frame_align and frame_align_shift are determined too. these two feature will be used in audio_stream_get_avail_frames_aligned to calculate the available frames. it should be called in component prepare or param functions only once before stream copy. if someone forgets to call this first, there would be unexampled error such as nothing is copied at all.

Parameters

sink	a handler to sink
byte_align	Processing byte alignment requirement.
frame_align_req	Processing frames alignment requirement.

Returns

0 if success

sink_set_buffer_fmt()

int sink_set_buffer_fmt	(	struct sof_sink *	sink,
		uint32_t	buffer_fmt
	)

sink_set_channels()

int sink_set_channels	(	struct sof_sink *	sink,
		unsigned int	channels
	)

sink_set_frm_fmt()

int sink_set_frm_fmt	(	struct sof_sink *	sink,
		enum sof_ipc_frame	frame_fmt
	)

set of functions for retrieve audio parameters

sink_set_overrun()

int sink_set_overrun	(	struct sof_sink *	sink,
		bool	overrun_permitted
	)

sink_set_params()

int sink_set_params	(	struct sof_sink *	sink,
		struct sof_ipc_stream_params *	params,
		bool	force_update
	)

initial set of audio parameters, provided in sof_ipc_stream_params

Parameters

sink	a handler to sink
params	the set of parameters
force_update	tells the implementation that the params should override actual settings

Returns

0 if success

sink_set_rate()

int sink_set_rate	(	struct sof_sink *	sink,
		unsigned int	rate
	)

sink_set_size()

int sink_set_size	(	struct sof_sink *	sink,
		size_t	size
	)

Resize the buffer backing the sink.

Parameters

sink	a handler to sink
size	requested buffer size in bytes

Returns

0 on success, -ENOSYS if the sink implementation does not support resizing

sink_set_valid_fmt()

int sink_set_valid_fmt	(	struct sof_sink *	sink,
		enum sof_ipc_frame	valid_sample_fmt
	)

sink_unbind()

static int sink_unbind ( struct sof_sink *  sink )

inlinestatic

hook to be called when a module disconnects from the API

NOTE! it MUST be called at core that a module is bound to