Value Container

One typed scalar or range, the smallest piece of a capability. More...

Files
file	mpipe_value.h
	Value: one typed scalar or range inside a capability.

Data Structures
union	mpipe_value_bound
	One end of a range value, or its step. More...
struct	mpipe_value
	Value structure. More...

Enumerations
enum	mpipe_value_type {   MPIPE_TYPE_NONE = 0 , MPIPE_TYPE_BOOLEAN , MPIPE_TYPE_INT , MPIPE_TYPE_UINT ,   MPIPE_TYPE_INT_RANGE , MPIPE_TYPE_UINT_RANGE , MPIPE_TYPE_COUNT }
	Value types. More...

Functions
int	mpipe_value_set (struct mpipe_value *value, int type,...)
	Set a value's type and contents.
int	mpipe_value_set_va_list (struct mpipe_value *value, enum mpipe_value_type type, va_list *args)
	Set a value from a va_list.
bool	mpipe_value_get_boolean (const struct mpipe_value *value)
	Get boolean value of MPIPE_TYPE_BOOLEAN type.
int32_t	mpipe_value_get_int (const struct mpipe_value *value)
	Get int value of MPIPE_TYPE_INT type.
uint32_t	mpipe_value_get_uint (const struct mpipe_value *value)
	Get uint value of MPIPE_TYPE_UINT type.
int32_t	mpipe_value_get_int_range_min (const struct mpipe_value *range)
	Get minimum value of a MPIPE_TYPE_INT_RANGE type.
int32_t	mpipe_value_get_int_range_max (const struct mpipe_value *range)
	Get maximum value of a MPIPE_TYPE_INT_RANGE type.
int32_t	mpipe_value_get_int_range_step (const struct mpipe_value *range)
	Get step value of a MPIPE_TYPE_INT_RANGE type.
uint32_t	mpipe_value_get_uint_range_min (const struct mpipe_value *range)
	Get minimum value of a MPIPE_TYPE_UINT_RANGE type.
uint32_t	mpipe_value_get_uint_range_max (const struct mpipe_value *range)
	Get maximum value of a MPIPE_TYPE_UINT_RANGE type.
uint32_t	mpipe_value_get_uint_range_step (const struct mpipe_value *range)
	Get step value of a MPIPE_TYPE_UINT_RANGE type.
int	mpipe_value_intersect (const struct mpipe_value *val1, const struct mpipe_value *val2, struct mpipe_value *out)
	Intersect two values, put the result into caller-provided storage.
bool	mpipe_value_is_primitive (const struct mpipe_value *value)
	Check if a value is of a primitive type.
void	mpipe_value_print (const struct mpipe_value *value, bool new_line)
	Print a value.

Initializers for a statically defined value
Each expands to a braced initializer for one Value Container, so a capability known at build time can be placed in .rodata rather than built at runtime. They are what MPIPE_STRUCTURE_DEFINE takes for each of its fields. The range forms take the bounds and the step between two consecutive values.
#define	MPIPE_VALUE_BOOLEAN(v)
	Initialize an MPIPE_TYPE_BOOLEAN value.
#define	MPIPE_VALUE_INT(v)
	Initialize an MPIPE_TYPE_INT value.
#define	MPIPE_VALUE_UINT(v)
	Initialize an MPIPE_TYPE_UINT value.
#define	MPIPE_VALUE_INT_RANGE(lo, hi, st)
	Initialize an MPIPE_TYPE_INT_RANGE value.
#define	MPIPE_VALUE_UINT_RANGE(lo, hi, st)
	Initialize an MPIPE_TYPE_UINT_RANGE value.

Detailed Description

One typed scalar or range, the smallest piece of a capability.

An Value Container is what a field of an Capability Structure holds: a boolean, a signed or unsigned integer, or a {min, max, step} range of one of those. A range is how a device says it accepts a span rather than one setting - every width from 16 to 1280 in steps of 2 - and fixation later picks a single value out of it.

It is a tagged union with no pointer in any arm, so it is the same size on every target, copying one is a plain assignment, and there is nothing to release. That is what lets a capability be passed by value and placed in .rodata.

The type set is deliberately just these two shapes, because they are closed under intersection: intersecting two values never yields something larger than its inputs, so the result always fits in storage the caller already has. A set-of-alternatives type would break that and force an allocation back in, which is why alternatives live on an enumeration index instead - see Pad.

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

Macro Definition Documentation

MPIPE_VALUE_BOOLEAN

#define MPIPE_VALUE_BOOLEAN

(

v

)

#include <mpipe_value.h>

Value:

{.type = MPIPE_TYPE_BOOLEAN, .v_boolean = (v)}

Initialize an MPIPE_TYPE_BOOLEAN value.

Parameters

v	Boolean the value holds

MPIPE_VALUE_INT

#define MPIPE_VALUE_INT

(

v

)

#include <mpipe_value.h>

Value:

{.type = MPIPE_TYPE_INT, .v_int = (v)}

Initialize an MPIPE_TYPE_INT value.

Parameters

v	Signed integer the value holds

MPIPE_VALUE_INT_RANGE

#define MPIPE_VALUE_INT_RANGE	(		lo,
			hi,
			st )

#include <mpipe_value.h>

Value:

{.type = MPIPE_TYPE_INT_RANGE, .range = MPIPE_VALUE_RANGE_INIT(v_int, lo, hi, st)}

Initialize an MPIPE_TYPE_INT_RANGE value.

Parameters

lo	Lowest value of the range, inclusive
hi	Highest value of the range, inclusive
st	Step between two consecutive values

MPIPE_VALUE_UINT

#define MPIPE_VALUE_UINT

(

v

)

#include <mpipe_value.h>

Value:

{.type = MPIPE_TYPE_UINT, .v_uint = (v)}

Initialize an MPIPE_TYPE_UINT value.

Parameters

v	Unsigned integer the value holds

MPIPE_VALUE_UINT_RANGE

#define MPIPE_VALUE_UINT_RANGE	(		lo,
			hi,
			st )

#include <mpipe_value.h>

Value:

{.type = MPIPE_TYPE_UINT_RANGE, .range = MPIPE_VALUE_RANGE_INIT(v_uint, lo, hi, st)}

Initialize an MPIPE_TYPE_UINT_RANGE value.

Parameters

lo	Lowest value of the range, inclusive
hi	Highest value of the range, inclusive
st	Step between two consecutive values

Enumeration Type Documentation

mpipe_value_type

enum mpipe_value_type

#include <mpipe_value.h>

Value types.

Enumerator
MPIPE_TYPE_NONE	No type.
MPIPE_TYPE_BOOLEAN	Boolean value.
MPIPE_TYPE_INT	Signed integer value.
MPIPE_TYPE_UINT	Unsigned integer value.
MPIPE_TYPE_INT_RANGE	Integer range value.
MPIPE_TYPE_UINT_RANGE	Unsigned integer range value.
MPIPE_TYPE_COUNT	Number of types.

Function Documentation

mpipe_value_get_boolean()

bool mpipe_value_get_boolean

(

const struct mpipe_value *

value

)

#include <mpipe_value.h>

Get boolean value of MPIPE_TYPE_BOOLEAN type.

The getters read the requested member without checking the type, so the caller is responsible for passing a value of the matching type.

Parameters

value

Pointer to the value.

Returns

The boolean the value holds.

mpipe_value_get_int()

int32_t mpipe_value_get_int

(

const struct mpipe_value *

value

)

#include <mpipe_value.h>

Get int value of MPIPE_TYPE_INT type.

Parameters

value

Pointer to the value.

Returns

The integer the value holds.

mpipe_value_get_int_range_max()

int32_t mpipe_value_get_int_range_max

(

const struct mpipe_value *

range

)

#include <mpipe_value.h>

Get maximum value of a MPIPE_TYPE_INT_RANGE type.

Parameters

range

Pointer to the range value.

Returns

The upper bound of the range.

mpipe_value_get_int_range_min()

int32_t mpipe_value_get_int_range_min

(

const struct mpipe_value *

range

)

#include <mpipe_value.h>

Get minimum value of a MPIPE_TYPE_INT_RANGE type.

Parameters

range

Pointer to the range value.

Returns

The lower bound of the range.

mpipe_value_get_int_range_step()

int32_t mpipe_value_get_int_range_step

(

const struct mpipe_value *

range

)

#include <mpipe_value.h>

Get step value of a MPIPE_TYPE_INT_RANGE type.

Parameters

range

Pointer to the range value.

Returns

The step between two consecutive values of the range.

mpipe_value_get_uint()

uint32_t mpipe_value_get_uint

(

const struct mpipe_value *

value

)

#include <mpipe_value.h>

Get uint value of MPIPE_TYPE_UINT type.

Parameters

value

Pointer to the value.

Returns

The unsigned integer the value holds.

mpipe_value_get_uint_range_max()

uint32_t mpipe_value_get_uint_range_max

(

const struct mpipe_value *

range

)

#include <mpipe_value.h>

Get maximum value of a MPIPE_TYPE_UINT_RANGE type.

Parameters

range

Pointer to the range value.

Returns

The upper bound of the range.

mpipe_value_get_uint_range_min()

uint32_t mpipe_value_get_uint_range_min

(

const struct mpipe_value *

range

)

#include <mpipe_value.h>

Get minimum value of a MPIPE_TYPE_UINT_RANGE type.

Parameters

range

Pointer to the range value.

Returns

The lower bound of the range.

mpipe_value_get_uint_range_step()

uint32_t mpipe_value_get_uint_range_step

(

const struct mpipe_value *

range

)

#include <mpipe_value.h>

Get step value of a MPIPE_TYPE_UINT_RANGE type.

Parameters

range

Pointer to the range value.

Returns

The step between two consecutive values of the range.

mpipe_value_intersect()

int mpipe_value_intersect	(	const struct mpipe_value *	val1,
		const struct mpipe_value *	val2,
		struct mpipe_value *	out )

#include <mpipe_value.h>

Intersect two values, put the result into caller-provided storage.

Parameters

	val1	Pointer to the first value.
	val2	Pointer to the second value.
[out]	out	Pointer to storage for the result, untouched unless 0 is returned.

Return values

0	Success.
-ENOENT	The intersection is empty

mpipe_value_is_primitive()

bool mpipe_value_is_primitive

(

const struct mpipe_value *

value

)

#include <mpipe_value.h>

Check if a value is of a primitive type.

Parameters

value

Pointer to the value to check.

Returns

true if the value is primitive, false otherwise or if value is NULL

mpipe_value_print()

void mpipe_value_print	(	const struct mpipe_value *	value,
		bool	new_line )

#include <mpipe_value.h>

Print a value.

Parameters

value	Pointer to the value to print.
new_line	Add newline after printing.

mpipe_value_set()

int mpipe_value_set	(	struct mpipe_value *	value,
		int	type,
			... )

#include <mpipe_value.h>

Set a value's type and contents.

BOOLEAN, INT and UINT take one argument; the range types take min, max and step.

Parameters

[out]	value	Pointer to the value to set.
	type	Type of the value, see mpipe_value_type. It is an int and not the enum itself because va_start() starts reading right after this parameter, so the parameter cannot be of a type narrower than int, which an enum is allowed to be.
	...	Arguments initializing the value, per the rules above.

Return values

0	on success
-EINVAL	type is invalid

mpipe_value_set_va_list()

int mpipe_value_set_va_list	(	struct mpipe_value *	value,
		enum mpipe_value_type	type,
		va_list *	args )

#include <mpipe_value.h>

Set a value from a va_list.

Same as mpipe_value_set but accepts a va_list pointer instead of variadic arguments, so a caller parsing its own list can build a value in place.

Parameters

[out]	value	Pointer to the value to set.
	type	Type of the value, see mpipe_value_type.
	args	Pointer to a va_list positioned at this value's arguments.

Return values

0	on success
-EINVAL	type is invalid