source_api.h File Reference

Source audio endpoint API for module input buffers. More...

Include dependency graph for source_api.h:

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

Go to the source code of this file.

Data Structures
struct	source_ops
	this is a definition of internals of source API More...
struct	sof_source
	internals of source API. More...

Functions
static size_t	source_get_data_available (struct sof_source *source)
	Public functions.
static size_t	source_get_aligned_frames_available (struct sof_source *source)
	Retrieves number of available data frames aligned to the alignment constants set by source_set_alignment_constants().
static enum sof_ipc_frame	source_get_frm_fmt (struct sof_source *source)
static unsigned int	source_get_channels (struct sof_source *source)
size_t	source_get_frame_bytes (struct sof_source *source)
	get size of a single audio frame (in bytes)
size_t	source_get_data_frames_available (struct sof_source *source)
	Retrieves size of available data (in frames) return number of frames that are available for immediate use.
int	source_get_data (struct sof_source *source, size_t req_size, void const **data_ptr, void const **buffer_start, size_t *buffer_size)
	Retrieves a fragment of circular data to be used by the caller (to read) After calling get_data, the data are guaranteed to be available for exclusive use (read only) if the provided pointers are cached, it is guaranteed that the caller may safely use it without any additional cache operations.
int	source_get_data_s16 (struct sof_source *source, size_t req_size, int16_t const **data_ptr, int16_t const **buffer_start, size_t *buffer_samples)
	Retrieves a fragment of circular data (to read)
int	source_get_data_s32 (struct sof_source *source, size_t req_size, int32_t const **data_ptr, int32_t const **buffer_start, size_t *buffer_samples)
	Retrieves a fragment of circular data (to read)
int	source_release_data (struct sof_source *source, size_t free_size)
	Releases fragment previously obtained by source_get_data() Once called, the data are no longer available for the caller.
int	source_set_size (struct sof_source *source, size_t size)
	Resize the buffer backing the source.
static enum sof_ipc_frame	source_get_valid_fmt (struct sof_source *source)
	set of functions for retrieve audio parameters
static unsigned int	source_get_rate (struct sof_source *source)
static uint32_t	source_get_buffer_fmt (struct sof_source *source)
static size_t	source_get_min_available (struct sof_source *source)
static uint32_t	source_get_id (struct sof_source *source)
static uint32_t	source_get_pipeline_id (struct sof_source *source)
static int	source_bind (struct sof_source *source, struct processing_module *module)
	hook to be called when a module connects to the API
static int	source_unbind (struct sof_source *source)
	hook to be called when a module disconnects from the API
static struct processing_module *	source_get_bound_module (struct sof_source *source)
static enum sof_audio_buffer_state	source_get_state (const struct sof_source *source)
static int	source_get_comp_state (struct sof_source *source)
	get the state of the component producing data to this source
static uint32_t	source_align_frames_round_up (struct sof_source *source, uint32_t frames)
static uint32_t	source_align_frames_round_down (struct sof_source *source, uint32_t frames)
static uint32_t	source_align_frames_round_nearest (struct sof_source *source, uint32_t frames)

Detailed Description

Source audio endpoint API for module input buffers.

Function Documentation

source_align_frames_round_down()

static uint32_t source_align_frames_round_down ( struct sof_source *  source, uint32_t  frames  )

inlinestatic

source_align_frames_round_nearest()

static uint32_t source_align_frames_round_nearest ( struct sof_source *  source, uint32_t  frames  )

inlinestatic

source_align_frames_round_up()

static uint32_t source_align_frames_round_up ( struct sof_source *  source, uint32_t  frames  )

inlinestatic

source_bind()

static int source_bind ( struct sof_source *  source, 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

source_get_aligned_frames_available()

static size_t source_get_aligned_frames_available ( struct sof_source *  source )

inlinestatic

Retrieves number of available data frames aligned to the alignment constants set by source_set_alignment_constants().

Returns

Number of aligned available frames.

source_get_bound_module()

static struct processing_module * source_get_bound_module ( struct sof_source *  source )

inlinestatic

source_get_buffer_fmt()

static uint32_t source_get_buffer_fmt ( struct sof_source *  source )

inlinestatic

source_get_channels()

static unsigned int source_get_channels ( struct sof_source *  source )

inlinestatic

source_get_comp_state()

static int source_get_comp_state ( struct sof_source *  source )

inlinestatic

get the state of the component producing data to this source

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

Parameters

source

a source to be checked

Returns

state of the producing component, or COMP_STATE_NOT_EXIST (0) if there is no connected producer or the source implementation does not track it

source_get_data()

int source_get_data	(	struct sof_source *	source,
		size_t	req_size,
		void const **	data_ptr,
		void const **	buffer_start,
		size_t *	buffer_size
	)

Retrieves a fragment of circular data to be used by the caller (to read) After calling get_data, the data are guaranteed to be available for exclusive use (read only) 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

Depending on implementation - there may be a way to have several receivers of the same data, as long as the receiver respects that data are read-only and won'do anything fancy with cache handling itself

some implementation data may be stored in linear buffer in that case: data_ptr = buffer_start buffer_end = data_ptr + req_size buffer_size = req_size

and the data receiver may use it as usual, rollover will simple never occur NOTE! the caller MUST NOT assume that pointers to start/end of the circular buffer are constant. They may change between calls

Parameters

	source	a handler to source
[in]	req_size	requested size of data.
[out]	data_ptr	a pointer to data 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 available data

source_get_data_available()

static size_t source_get_data_available ( struct sof_source *  source )

inlinestatic

Public functions.

Retrieves size of available data (in bytes) return number of bytes that are available for immediate use

source_get_data_frames_available()

size_t source_get_data_frames_available

(

struct sof_source *

source

)

Retrieves size of available data (in frames) return number of frames that are available for immediate use.

source_get_data_s16()

int source_get_data_s16	(	struct sof_source *	source,
		size_t	req_size,
		int16_t const **	data_ptr,
		int16_t const **	buffer_start,
		size_t *	buffer_samples
	)

Retrieves a fragment of circular data (to read)

Same as source_get_data() 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

	source	a handler to source
[in]	req_size	requested size of data.
[out]	data_ptr	a pointer to data will be provided there
[out]	buffer_start	pointer to circular buffer start
[out]	buffer_samples	number of 16 bit samples total in circular buffer

Return values

-ENODATA

if req_size is bigger than available data

source_get_data_s32()

int source_get_data_s32	(	struct sof_source *	source,
		size_t	req_size,
		int32_t const **	data_ptr,
		int32_t const **	buffer_start,
		size_t *	buffer_samples
	)

Retrieves a fragment of circular data (to read)

Same as source_get_data() 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

	source	a handler to source
[in]	req_size	requested size of data.
[out]	data_ptr	a pointer to data will be provided there
[out]	buffer_start	pointer to circular buffer start
[out]	buffer_samples	number of 32 bit samples total in circular buffer

Return values

-ENODATA

if req_size is bigger than available data

source_get_frame_bytes()

size_t source_get_frame_bytes

(

struct sof_source *

source

)

get size of a single audio frame (in bytes)

source_get_frm_fmt()

static enum sof_ipc_frame source_get_frm_fmt ( struct sof_source *  source )

inlinestatic

source_get_id()

static uint32_t source_get_id ( struct sof_source *  source )

inlinestatic

source_get_min_available()

static size_t source_get_min_available ( struct sof_source *  source )

inlinestatic

source_get_pipeline_id()

static uint32_t source_get_pipeline_id ( struct sof_source *  source )

inlinestatic

source_get_rate()

static unsigned int source_get_rate ( struct sof_source *  source )

inlinestatic

source_get_state()

static enum sof_audio_buffer_state source_get_state ( const struct sof_source *  source )

inlinestatic

source_get_valid_fmt()

static enum sof_ipc_frame source_get_valid_fmt ( struct sof_source *  source )

inlinestatic

set of functions for retrieve audio parameters

source_release_data()

int source_release_data	(	struct sof_source *	source,
		size_t	free_size
	)

Releases fragment previously obtained by source_get_data() Once called, the data are no longer available for the caller.

Parameters

source

a handler to source

free_size

amount of data that the caller declares as "never needed again" if free_size == 0 the source implementation MUST keep all data in memory and make them available again at next get_data() call if free_size is bigger than the amount of data obtained before by get_data(), only the amount obtained before will be freed. That means - if somebody obtained some data, processed it and won't need it again, it may simple call put_data with free_size==MAXINT

Returns

proper error code (0 on success)

source_set_size()

int source_set_size	(	struct sof_source *	source,
		size_t	size
	)

Resize the buffer backing the source.

Parameters

source	a handler to source
size	requested buffer size in bytes

Returns

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

source_unbind()

static int source_unbind ( struct sof_source *  source )

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