Capability Structure

Fixed-size container describing one media capability. More...

Files
file	mpipe_structure.h
	Structure: one media capability, held by value.

Data Structures
struct	mpipe_structure
	Fixed-size container holding the fields of one capability. More...

Macros
#define	MPIPE_STRUCTURE_FLAG_ANY   BIT(0)
	The structure constrains nothing and intersects with anything.
#define	MPIPE_FRAME_INTERVAL_FROM_FPS(fps)
	Convert a frame rate in frames per second to a frame interval in microseconds.
#define	MPIPE_STRUCTURE_DEFINE(name, media, fields)
	Define a read-only Capability Structure in .rodata.

Enumerations
enum	mpipe_media_type { MPIPE_MEDIA_UNKNOWN = 0 , MPIPE_MEDIA_AUDIO_PCM , MPIPE_MEDIA_VIDEO , MPIPE_MEDIA_END }
	Media type a capability describes. More...
enum	mpipe_caps_field {   MPIPE_CAPS_PIXEL_FORMAT = 0 , MPIPE_CAPS_IMAGE_WIDTH , MPIPE_CAPS_IMAGE_HEIGHT , MPIPE_CAPS_SAMPLE_RATE ,   MPIPE_CAPS_BITWIDTH , MPIPE_CAPS_NUM_OF_CHANNEL , MPIPE_CAPS_INTERLEAVED , MPIPE_CAPS_FRAME_INTERVAL ,   MPIPE_CAPS_END }
	Caps field identifiers. More...

Functions
int	mpipe_structure_init (struct mpipe_structure *structure, uint8_t media_type_id)
	Initialize an Capability Structure.
int	mpipe_structure_init_fields (struct mpipe_structure *structure, uint8_t media_type_id,...)
	Initialize an Capability Structure with a media type and a list of fields.
int	mpipe_structure_init_any (struct mpipe_structure *structure)
	Initialize a structure that constrains nothing.
bool	mpipe_structure_is_any (const struct mpipe_structure *structure)
	Check whether a structure constrains nothing.
bool	mpipe_structure_is_empty (const struct mpipe_structure *structure)
	Check whether an Capability Structure matches nothing.
int	mpipe_structure_append_value (struct mpipe_structure *structure, uint8_t field_id, const struct mpipe_value *value)
	Append a field to an Capability Structure from caller-owned storage.
int	mpipe_structure_copy_field (const struct mpipe_structure *src, struct mpipe_structure *dst, uint8_t field_id)
	Copy a field from one Capability Structure to another.
int	mpipe_structure_clear (struct mpipe_structure *structure)
	Empty an Capability Structure, dropping every field it carries.
bool	mpipe_structure_is_fixed (const struct mpipe_structure *structure)
	Check if an Capability Structure is fixed.
const struct mpipe_value *	mpipe_structure_get_value (const struct mpipe_structure *structure, uint8_t field_id)
	Get the value of a field in an Capability Structure.
int	mpipe_structure_remove_field (struct mpipe_structure *structure, uint8_t field_id)
	Remove a field from an Capability Structure.
int	mpipe_structure_intersect (const struct mpipe_structure *struct1, const struct mpipe_structure *struct2, struct mpipe_structure *out)
	Intersect two structures into caller-provided storage.
int	mpipe_structure_fixate (const struct mpipe_structure *src, struct mpipe_structure *out)
	Fixate a structure into caller-provided storage.
void	mpipe_structure_print (const struct mpipe_structure *structure)
	Print an Capability Structure.

Detailed Description

Fixed-size container describing one media capability.

An mpipe_structure holds a set of fields, each an mpipe_caps_field identifier paired with an Value Container. It is a fixed-size type held by value, so it needs no allocation: the fields occupy the first slots of two parallel arrays, one naming the field and one holding its value.

A video capability such as

video, format=VIDEO_PIX_FMT_RGB565, width=[16, 1280, 2], height=[16, 720, 2]

is built directly in caller storage:

struct mpipe_structure s;
 
mpipe_structure_init_fields(&s, MPIPE_MEDIA_VIDEO,
    MPIPE_CAPS_PIXEL_FORMAT, MPIPE_TYPE_UINT, VIDEO_PIX_FMT_RGB565,
    MPIPE_CAPS_IMAGE_WIDTH, MPIPE_TYPE_UINT_RANGE, 16, 1280, 2,
    MPIPE_CAPS_IMAGE_HEIGHT, MPIPE_TYPE_UINT_RANGE, 16, 720, 2,
    MPIPE_CAPS_END);

A range is written [min, max, step], so the width above admits every multiple of 2 from 16 to 1280.

Two structures intersect when they have the same media type, carry at least one field identifier in common, and every field they do share has intersecting values. The result is the union of both: a shared field holds the intersected value, and a field only one side carries passes through unchanged. That last rule is what lets a constraint travel down a chain of elements that do not themselves care about it.

Pointers passed to this API must not be NULL unless the parameter is documented otherwise.

Macro Definition Documentation

MPIPE_FRAME_INTERVAL_FROM_FPS

#define MPIPE_FRAME_INTERVAL_FROM_FPS

(

fps

)

#include <mpipe_structure.h>

Value:

DIV_ROUND_CLOSEST(USEC_PER_SEC, (fps))

Convert a frame rate in frames per second to a frame interval in microseconds.

Gives the value MPIPE_CAPS_FRAME_INTERVAL holds. A frame rate that does not divide 1000000 exactly should be rounded the same way everywhere so that its representation is consistent across the system. Using DIV_ROUND_CLOSEST() is also consistent with the video subsystem and drivers.

Parameters

fps	Frame rate in frames per second, must not be zero

Returns

Frame interval in microseconds

MPIPE_STRUCTURE_DEFINE

#define MPIPE_STRUCTURE_DEFINE	(		name,
			media,
			fields )

#include <mpipe_structure.h>

Value:

BUILD_ASSERT((fields(MPIPE_STRUCTURE_FIELD_COUNT) 0) <= CONFIG_MPIPE_STRUCTURE_MAX_FIELDS, \
             #name " has more fields than CONFIG_MPIPE_STRUCTURE_MAX_FIELDS");             \
static const struct mpipe_structure name = {                                               \
        .media_type_id = (media),                                                          \
        .flags = 0,                                                                        \
        .num_fields = fields(MPIPE_STRUCTURE_FIELD_COUNT) 0,                               \
        .ids = {fields(MPIPE_STRUCTURE_FIELD_ID)},                                         \
        .values = {fields(MPIPE_STRUCTURE_FIELD_VALUE)},                                   \
}

Define a read-only Capability Structure in .rodata.

An element whose capabilities are known at build time can carry them here instead of building them at runtime, and copy one out by plain struct assignment when it is enumerated.

fields is a macro taking one argument, which it applies to each field as arg(field_id, value_initializer). Listing the fields once is what keeps the identifiers, the values and the count from disagreeing, which would silently drop a field. Defining more fields than CONFIG_MPIPE_STRUCTURE_MAX_FIELDS fails the build.

#define JPEG_SRC_FIELDS(X) X(MPIPE_CAPS_PIXEL_FORMAT, MPIPE_VALUE_UINT(VIDEO_PIX_FMT_JPEG))
MPIPE_STRUCTURE_DEFINE(jpeg_src, MPIPE_MEDIA_VIDEO, JPEG_SRC_FIELDS);

Parameters

name	Name of the structure to define.
media	Media type of the structure, see mpipe_media_type.
fields	Macro listing the fields, see above.

MPIPE_STRUCTURE_FLAG_ANY

#define MPIPE_STRUCTURE_FLAG_ANY   BIT(0)

#include <mpipe_structure.h>

The structure constrains nothing and intersects with anything.

Distinct from a structure with no fields set, which constrains nothing because it is empty and therefore intersects with nothing.

Enumeration Type Documentation

mpipe_caps_field

enum mpipe_caps_field

#include <mpipe_structure.h>

Caps field identifiers.

A field of an Capability Structure is one of these identifiers paired with an Value Container. Each entry below names the value type that carries it. A capability offering a span rather than one setting uses the matching range type instead, MPIPE_TYPE_UINT_RANGE where the entry says MPIPE_TYPE_UINT, which is how a device advertises every width from 16 to 1280 rather than a single one. Negotiation then narrows the span, and fixation picks one value out of it. MPIPE_CAPS_PIXEL_FORMAT and MPIPE_CAPS_INTERLEAVED, for example, are the exceptions: neither has a meaningful range form, so both are always carried fixed.

A caps field is not a property. A property configures one element, and nothing else has to agree on it: a camera's gain or contrast, or the device an element binds to. It is set on that element and used by that element.

A caps field describes the data crossing a link, so both ends have to agree on it before anything can flow, and that agreement is what negotiation settles. The test when adding one is whether two different elements would have to arrive at the same value for the stream to be correct. If only the element that owns it cares, it is a property.

MPIPE_CAPS_IMAGE_WIDTH passes that test: a camera, a converter and a display all understand it and all have to agree on one number. Camera gain does not, as the display neither knows nor cares what it is.

These identifiers are shared by every domain, and one structure holds only CONFIG_MPIPE_STRUCTURE_MAX_FIELDS of them at a time, so a new field earns its place by meaning something to more than the element that introduced it. Prefer one a whole domain agrees on, or one that spans domains the way MPIPE_CAPS_FRAME_INTERVAL does for audio and video.

Add it before MPIPE_CAPS_END and document its unit and value type the way the entries below do, and give it a name in dump_field_names in mpipe_dump.c so a dump can print it.

Enumerator
MPIPE_CAPS_PIXEL_FORMAT	Pixel format, as a VIDEO_PIX_FMT_* fourcc, MPIPE_TYPE_UINT.
MPIPE_CAPS_IMAGE_WIDTH	Image width in pixels, MPIPE_TYPE_UINT.
MPIPE_CAPS_IMAGE_HEIGHT	Image height in pixels, MPIPE_TYPE_UINT.
MPIPE_CAPS_SAMPLE_RATE	Sampling frequency in Hz (audio), MPIPE_TYPE_UINT.
MPIPE_CAPS_BITWIDTH	Sample size in bits (audio), MPIPE_TYPE_UINT.
MPIPE_CAPS_NUM_OF_CHANNEL	Number of channels (audio), MPIPE_TYPE_UINT.
MPIPE_CAPS_INTERLEAVED	Layout of the channels within a buffer (audio), MPIPE_TYPE_BOOLEAN: true for interleaved (LRLRLRLR), false for non-interleaved (LLLLRRRR).
MPIPE_CAPS_FRAME_INTERVAL	Time covered by one frame, in microseconds, MPIPE_TYPE_UINT. Used by both the audio and the video domains: for video it is the frame interval, the reciprocal of the frame rate.
MPIPE_CAPS_END	One past the last field identifier. Bounds the range of valid identifiers, and terminates the field list of mpipe_structure_init_fields.

mpipe_media_type

enum mpipe_media_type

#include <mpipe_structure.h>

Media type a capability describes.

Enumerator
MPIPE_MEDIA_UNKNOWN	Unknown media type, what a structure constraining nothing carries.
MPIPE_MEDIA_AUDIO_PCM	Audio in PCM format.
MPIPE_MEDIA_VIDEO	Video, including raw, bayer and compressed formats.
MPIPE_MEDIA_END	One past the last media type; not itself a usable media type.

Function Documentation

mpipe_structure_append_value()

int mpipe_structure_append_value	(	struct mpipe_structure *	structure,
		uint8_t	field_id,
		const struct mpipe_value *	value )

#include <mpipe_structure.h>

Append a field to an Capability Structure from caller-owned storage.

Copies value into the next free slot; the caller keeps its own copy.

Parameters

structure	Pointer to the structure to append the field to.
field_id	Field identifier, see mpipe_caps_field. Must not already be set.
value	Pointer to the field value to copy in.

Return values

0	Success.
-EINVAL	field_id is not a field identifier
-EEXIST	The structure already carries field_id
-ENOSPC	The structure already holds CONFIG_MPIPE_STRUCTURE_MAX_FIELDS fields

mpipe_structure_clear()

int mpipe_structure_clear

(

struct mpipe_structure *

structure

)

#include <mpipe_structure.h>

Empty an Capability Structure, dropping every field it carries.

The structure keeps its media type and its flags, so it can be filled in again without being initialized first.

This leaves it constraining nothing because it holds no field, which intersects with nothing. It does not make it an ANY structure, which constrains nothing but intersects with everything: use mpipe_structure_init_any for that.

Parameters

structure

Pointer to the structure to clear.

Return values

0

Success.

mpipe_structure_copy_field()

int mpipe_structure_copy_field	(	const struct mpipe_structure *	src,
		struct mpipe_structure *	dst,
		uint8_t	field_id )

#include <mpipe_structure.h>

Copy a field from one Capability Structure to another.

Leaves dst untouched and reports -ENOENT when src does not carry the field, so a caller building a capability out of another one can offer every field it wants to pass through and ignore that code, rather than testing for each of them first.

Parameters

	src	Pointer to the structure to read the field from.
[in,out]	dst	Pointer to the structure to append the field to.
	field_id	Field identifier, see mpipe_caps_field.

Return values

0	Success.
-ENOENT	src does not carry the field
-EINVAL	field_id is not a field identifier
-EEXIST	dst already carries the field
-ENOSPC	dst is full

mpipe_structure_fixate()

int mpipe_structure_fixate	(	const struct mpipe_structure *	src,
		struct mpipe_structure *	out )

#include <mpipe_structure.h>

Fixate a structure into caller-provided storage.

Each field is reduced to a single value: a range to its minimum, a value already fixed to itself.

Parameters

	src	Pointer to the structure to fixate.
[out]	out	Pointer to storage for the result, left untouched on failure.

Return values

0	Success.
-ENOENT	src constrains nothing and so has nothing to fixate, whether it is flagged ANY or simply holds no field
-EINVAL	out is src

mpipe_structure_get_value()

const struct mpipe_value * mpipe_structure_get_value	(	const struct mpipe_structure *	structure,
		uint8_t	field_id )

#include <mpipe_structure.h>

Get the value of a field in an Capability Structure.

Retrieves the value associated with the specified field ID.

Parameters

structure	Pointer to the structure containing the field, may be NULL.
field_id	Field identifier, see mpipe_caps_field.

Returns

Pointer to the value of the field, NULL if the structure does not carry it or structure is NULL.

mpipe_structure_init()

int mpipe_structure_init	(	struct mpipe_structure *	structure,
		uint8_t	media_type_id )

#include <mpipe_structure.h>

Initialize an Capability Structure.

Leaves the structure with no field set.

Parameters

structure	Pointer to the structure to initialize.
media_type_id	Media type of the structure, see mpipe_media_type.

Return values

0	Success.
-EINVAL	media_type_id is not a media type

mpipe_structure_init_any()

int mpipe_structure_init_any

(

struct mpipe_structure *

structure

)

#include <mpipe_structure.h>

Initialize a structure that constrains nothing.

Intersecting it with another structure yields a copy of that structure, and fixating it reports -ENOENT because there is nothing to choose.

Parameters

structure

Pointer to the structure to initialize.

Return values

0

Success.

mpipe_structure_init_fields()

int mpipe_structure_init_fields	(	struct mpipe_structure *	structure,
		uint8_t	media_type_id,
			... )

#include <mpipe_structure.h>

Initialize an Capability Structure with a media type and a list of fields.

Builds a capability directly into caller storage: repeated field_id, type, value-args... triples terminated by MPIPE_CAPS_END, with the same per-type argument rules as mpipe_value_set. Allocates nothing, so a capability can be described on the stack or in a caller's own slot.

Parameters

structure	Pointer to the structure to initialize.
media_type_id	Media type of the structure, see mpipe_media_type.
...	Field triples, terminated by MPIPE_CAPS_END.

Return values

0	Success.
-EINVAL	media_type_id is not a media type, or a field identifier or value type is invalid
-EEXIST	The list names the same field twice
-ENOSPC	The list holds more fields than CONFIG_MPIPE_STRUCTURE_MAX_FIELDS

mpipe_structure_intersect()

int mpipe_structure_intersect	(	const struct mpipe_structure *	struct1,
		const struct mpipe_structure *	struct2,
		struct mpipe_structure *	out )

#include <mpipe_structure.h>

Intersect two structures into caller-provided storage.

The structures must share the same media type, carry at least one field identifier in common, and every field they do share must have intersecting values. The result is the union of both inputs: a field both sides carry holds the intersected value, and a field only one side carries is copied through unchanged, which can leave the result holding more fields than either input. Intersecting an ANY structure yields a copy of the other one.

out is written field by field, so it must not be one of the inputs.

Parameters

	struct1	Pointer to the first structure.
	struct2	Pointer to the second structure.
[out]	out	Pointer to storage for the result, left untouched on -EINVAL and cleared on any other failure.

Return values

0	Success.
-ENOENT	The structures share no field, or a shared field has no common value
-EINVAL	out aliases an input, or the media types differ
-ENOSPC	The union does not fit CONFIG_MPIPE_STRUCTURE_MAX_FIELDS

mpipe_structure_is_any()

bool mpipe_structure_is_any

(

const struct mpipe_structure *

structure

)

#include <mpipe_structure.h>

Check whether a structure constrains nothing.

Parameters

structure

Pointer to the structure to check, may be NULL.

Returns

true if the structure constrains nothing, false otherwise or if structure is NULL

mpipe_structure_is_empty()

bool mpipe_structure_is_empty

(

const struct mpipe_structure *

structure

)

#include <mpipe_structure.h>

Check whether an Capability Structure matches nothing.

The counterpart of mpipe_structure_is_any - a structure that constrains nothing because it holds no field intersects with nothing, where an ANY one intersects with everything.

Parameters

structure

Pointer to the structure to check, may be NULL.

Returns

true if the structure is empty, false otherwise or if structure is NULL

mpipe_structure_is_fixed()

bool mpipe_structure_is_fixed

(

const struct mpipe_structure *

structure

)

#include <mpipe_structure.h>

Check if an Capability Structure is fixed.

A structure is fixed when it carries at least one field and every field it carries holds a single value rather than a range. A structure that constrains nothing is never fixed, whether it is flagged ANY or simply holds no field: there is nothing to have settled.

Parameters

structure

Pointer to the structure to check.

Returns

true if the structure is fixed, false otherwise or if structure is NULL

mpipe_structure_print()

void mpipe_structure_print

(

const struct mpipe_structure *

structure

)

#include <mpipe_structure.h>

Print an Capability Structure.

Outputs the contents of the structure for debugging or inspection.

Parameters

structure

Pointer to the structure to print.

mpipe_structure_remove_field()

int mpipe_structure_remove_field	(	struct mpipe_structure *	structure,
		uint8_t	field_id )

#include <mpipe_structure.h>

Remove a field from an Capability Structure.

Deletes the field with the specified ID from the structure.

Parameters

structure	Pointer to the structure containing the field to remove.
field_id	Field identifier, see mpipe_caps_field.

Return values

0	Success.
-ENOENT	The structure does not carry the field