Elements

The unit a pipeline is built from. More...

Files
file	mpipe_element.h
	Element: the unit a pipeline is built from.

Data Structures
struct	mpipe_element
	Element base class. More...

Macros
#define	MPIPE_STATE_GET_NEXT(cur, target)
	Calculate the next state.
#define	MPIPE_STATE_TRANSITION(cur, next)
	Create state transition value.
#define	MPIPE_STATE_TRANSITION_CURRENT(trans)
	Extract the current state from the state transition.
#define	MPIPE_STATE_TRANSITION_NEXT(trans)
	Extract the next state from the state transition.

Enumerations
enum	mpipe_state { MPIPE_STATE_READY = 0 , MPIPE_STATE_PAUSED = 1 , MPIPE_STATE_PLAYING = 2 }
	States of an element. More...
enum	mpipe_state_change { MPIPE_STATE_CHANGE_READY_TO_PAUSED , MPIPE_STATE_CHANGE_PAUSED_TO_PLAYING , MPIPE_STATE_CHANGE_PLAYING_TO_PAUSED , MPIPE_STATE_CHANGE_PAUSED_TO_READY }
	enum mpipe_state_change More...

Functions
int	mpipe_element_init (struct mpipe_element *self, uint8_t id)
	Initialize an element.
static void	mpipe_element_set_name (struct mpipe_element *self, const char *name)
	Name an element for the pipeline dump.
void	mpipe_element_reset_pad_caps (struct mpipe_element *element)
	Reset every pad of an element to constraining nothing.
void	mpipe_element_add_pad (struct mpipe_element *element, struct mpipe_pad *pad)
	Attach a pad to an element.
int	mpipe_element_link (struct mpipe_element *element_1, struct mpipe_element *element_2,...)
	Link elements together.
int	mpipe_element_set_state (struct mpipe_element *element, enum mpipe_state state)
	Set the state of an element.
struct zbus_channel *	mpipe_element_get_bus_chan (struct mpipe_element *element)
	Get the bus channel of an element.

Detailed Description

The unit a pipeline is built from.

An element is one processing step: it produces buffers, consumes them, or turns some into others. It exposes Pad connectors, and linking two elements links a source pad of one to a sink pad of the other. What an element does is its own business; what the framework asks of it is that it answer queries, handle events, and follow the state machine.

States

An element is in one of three states, and moves between neighbors one step at a time:

READY <-> PAUSED <-> PLAYING

READY means constructed and linked but holding no negotiated format and no buffers. The READY to PAUSED transition is where the work happens: the source drives capability negotiation across the whole graph, then the buffer pool query settles who provides buffers and how many, and the pools start. PAUSED to PLAYING lets data flow. Going back down reverses it, and PAUSED to READY drops the negotiated capabilities so the next run negotiates afresh.

A transition returns 0 when it completes and a negative errno when the element refuses it; -EINPROGRESS is reserved for a transition that completes asynchronously. An element that refuses one stays where it is; nothing unwinds the elements that already moved, which is deliberate - the graph then shows exactly which element refused and in which transition.

Specializing an element

The bases in Sources, Sinks, Transforms, Parsers and Bins implement the protocol; a concrete element embeds one of them as its first member, calls that base's init with its own id, and overrides only the hooks it cares about. Chaining to the base change_state is mandatory - that is what performs the reset and the pool teardown every element is expected to do.

Macro Definition Documentation

MPIPE_STATE_GET_NEXT

#define MPIPE_STATE_GET_NEXT	(		cur,
			target )

#include <mpipe_element.h>

Value:

((enum mpipe_state)((int)cur + SYS_SIGN((int)target - (int)cur)))

Calculate the next state.

Given a current state and a target state, calculate the next intermediate state

Parameters

cur	Current state, see mpipe_state
target	Target state, see mpipe_state

Returns

Next intermediate state

MPIPE_STATE_TRANSITION

#define MPIPE_STATE_TRANSITION	(		cur,
			next )

#include <mpipe_element.h>

Value:

(((cur) << 2) | (next))

Create state transition value.

Parameters

cur	Current state
next	Next state

Returns

State transition value

MPIPE_STATE_TRANSITION_CURRENT

#define MPIPE_STATE_TRANSITION_CURRENT

(

trans

)

#include <mpipe_element.h>

Value:

((enum mpipe_state)((trans) >> 2))

Extract the current state from the state transition.

Given a state transition, extract the current state.

Parameters

trans

A transition state, see mpipe_state_change

Returns

The current state

MPIPE_STATE_TRANSITION_NEXT

#define MPIPE_STATE_TRANSITION_NEXT

(

trans

)

#include <mpipe_element.h>

Value:

((enum mpipe_state)((trans) & 0x3))

Extract the next state from the state transition.

Given a state transition, extract the next state.

Parameters

trans

A transition state, see mpipe_state_change

Returns

The next state

Enumeration Type Documentation

mpipe_state

enum mpipe_state

#include <mpipe_element.h>

States of an element.

All possible states that an element can be in.

Enumerator
MPIPE_STATE_READY	The element is initialized READY to go to PAUSED.
MPIPE_STATE_PAUSED	The element is PAUSED and ready to receive, process or transfer data.
MPIPE_STATE_PLAYING	The element is PLAYING, data is flowing through the element.

mpipe_state_change

enum mpipe_state_change

#include <mpipe_element.h>

enum mpipe_state_change

Different possible state changes that an element can go through.

Enumerator
MPIPE_STATE_CHANGE_READY_TO_PAUSED	State change from READY to PAUSED.
MPIPE_STATE_CHANGE_PAUSED_TO_PLAYING	State change from PAUSED to PLAYING.
MPIPE_STATE_CHANGE_PLAYING_TO_PAUSED	State change from PLAYING to PAUSED.
MPIPE_STATE_CHANGE_PAUSED_TO_READY	State change from PAUSED to READY.

Function Documentation

mpipe_element_add_pad()

void mpipe_element_add_pad	(	struct mpipe_element *	element,
		struct mpipe_pad *	pad )

#include <mpipe_element.h>

Attach a pad to an element.

Adds pad to the element's pad list and makes the element the pad's container, which is how a pad callback reaches the element that owns it. A base class calls this for the pads it declares, so an element only calls it for a pad of its own.

Parameters

element	Pointer to the element to attach the pad to.
pad	Pointer to the pad to attach.

mpipe_element_get_bus_chan()

struct zbus_channel * mpipe_element_get_bus_chan

(

struct mpipe_element *

element

)

#include <mpipe_element.h>

Get the bus channel of an element.

Retrieves the zbus_channel associated with the element, which is the bus channel of the nearest bin that contains the element. This is how an application reaches the channel to attach an observer to, without depending on where the bin keeps it.

Parameters

element

Pointer to the Elements to get the channel from.

Returns

Pointer to the zbus_channel, or NULL if no bus channel is found.

mpipe_element_init()

int mpipe_element_init	(	struct mpipe_element *	self,
		uint8_t	id )

#include <mpipe_element.h>

Initialize an element.

Initializes the base Elements structure.

Parameters

self	Pointer to the Elements to initialize.
id	Unique element identifier.

Returns

0 on success, negative errno otherwise.

mpipe_element_link()

int mpipe_element_link	(	struct mpipe_element *	element_1,
		struct mpipe_element *	element_2,
			... )

#include <mpipe_element.h>

Link elements together.

Links multiple elements together in a chain. Elements should have only one source and/or one sink pad. If not, the first src/sink pads will be used. The function takes a variable number of elements and links them sequentially.

Parameters

element_1	First element in the chain
element_2	Second element in the chain
...	Additional elements to link (terminated by NULL)

Returns

0 on success, negative errno on failure

mpipe_element_reset_pad_caps()

void mpipe_element_reset_pad_caps

(

struct mpipe_element *

element

)

#include <mpipe_element.h>

Reset every pad of an element to constraining nothing.

Drops the negotiated capability from each of the element's pads so a subsequent re-negotiation starts fresh. Base classes call this on the PAUSED to READY transition; a derived element that overrides change_state must chain to its base function to inherit the reset.

Parameters

element

Pointer to the element whose pads to reset.

mpipe_element_set_name()

void mpipe_element_set_name ( struct mpipe_element * self, const char * name )

inlinestatic

#include <mpipe_element.h>

Name an element for the pipeline dump.

Every element init function names its element after its type, so a dump reads vid_transform rather than an address. Call this afterwards to give one instance a distinct name, which is what tells two elements of the same type apart in a dump.

ret = mpipe_vid_transform_init(&jpeg_dec, JPEG_DEC_ID);
mpipe_element_set_name(&jpeg_dec.transform.element, "jpeg_dec");

Compiles to nothing when

CONFIG_MPIPE_DUMP 

is disabled, so name costs no ROM in a build without the dump.

Parameters

self	Element to name.
name	Name to report. Must outlive the element; a string literal does.

mpipe_element_set_state()

int mpipe_element_set_state	(	struct mpipe_element *	element,
		enum mpipe_state	state )

#include <mpipe_element.h>

Set the state of an element.

Sets the state of an element. This function will try to set the requested state by going through all the intermediary states and calling the element's state change function for each.

Parameters

element	The element to change state of
state	The element's new mpipe_state

Returns

0 on success, else the errno of the element that refused a transition

Return values

-ENOSYS	The element has no set_state hook
-EINPROGRESS	Reserved: the transition completes asynchronously