Linear Range

The linear range API maps values in a linear range to a range index. More...

Data Structures
struct	linear_range
	Linear range. More...

Macros
#define	LINEAR_RANGE_INIT(_min, _step, _min_idx, _max_idx)
	Initializer for Linear Range.

Functions
static uint32_t	linear_range_values_count (const struct linear_range *r)
	Obtain the number of values representable in a linear range.
static uint32_t	linear_range_group_values_count (const struct linear_range *r, size_t r_cnt)
	Obtain the number of values representable by a group of linear ranges.
static int32_t	linear_range_get_max_value (const struct linear_range *r)
	Obtain the maximum value representable by a linear range.
static int	linear_range_get_value (const struct linear_range *r, uint16_t idx, int32_t *val)
	Obtain value given a linear range index.
static int	linear_range_group_get_value (const struct linear_range *r, size_t r_cnt, uint16_t idx, int32_t *val)
	Obtain value in a group given a linear range index.
static int	linear_range_get_index (const struct linear_range *r, int32_t val, uint16_t *idx)
	Obtain index given a value.
static int	linear_range_group_get_index (const struct linear_range *r, size_t r_cnt, int32_t val, uint16_t *idx)
	Obtain index in a group given a value.
static int	linear_range_get_win_index (const struct linear_range *r, int32_t val_min, int32_t val_max, uint16_t *idx)
	Obtain index given a window of values.
static int	linear_range_group_get_win_index (const struct linear_range *r, size_t r_cnt, int32_t val_min, int32_t val_max, uint16_t *idx)
	Obtain index in a group given a value that must be within a window of values.

Detailed Description

The linear range API maps values in a linear range to a range index.

A linear range can be fully defined by four parameters:

• Minimum value
• Step value
• Minimum index value
• Maximum index value

For example, in a voltage regulator, supported voltages typically map to a register index value like this:

• 1000uV: 0x00
• 1250uV: 0x01
• 1500uV: 0x02
• ...
• 3000uV: 0x08

In this case, we have:

• Minimum value: 1000uV
• Step value: 250uV
• Minimum index value: 0x00
• Maximum index value: 0x08

A linear range may also be constant, that is, step set to zero.

It is often the case where the same device has discontinuous linear ranges. The API offers utility functions to deal with groups of linear ranges as well.

Implementation uses fixed-width integers. Range is limited to [INT32_MIN, INT32_MAX], while number of indices is limited to UINT16_MAX.

Original idea borrowed from Linux.

Macro Definition Documentation

LINEAR_RANGE_INIT

#define LINEAR_RANGE_INIT	(		_min,
			_step,
			_min_idx,
			_max_idx )

#include <zephyr/sys/linear_range.h>

Value:

        {                                                                      \
                .min = (_min),                                                 \
                .step = (_step),                                               \
                .min_idx = (_min_idx),                                         \
                .max_idx = (_max_idx),                                         \
        }

Initializer for Linear Range.

Parameters

_min	Minimum value in range.
_step	Step value.
_min_idx	Minimum index.
_max_idx	Maximum index.

Function Documentation

linear_range_get_index()

static int linear_range_get_index ( const struct linear_range * r, int32_t val, uint16_t * idx )

inlinestatic

#include <zephyr/sys/linear_range.h>

Obtain index given a value.

If the value falls outside the range, the nearest index will be stored and -ERANGE returned. That is, if the value falls below or above the range, the index will take the minimum or maximum value, respectively. For constant ranges, the minimum index will be returned.

Parameters

[in]	r	Linear range instance.
	val	Value.
[out]	idx	Where index will be stored.

Return values

0	If value falls within the range.
-ERANGE	If the value falls out of the range.

linear_range_get_max_value()

static int32_t linear_range_get_max_value ( const struct linear_range * r )

inlinestatic

#include <zephyr/sys/linear_range.h>

Obtain the maximum value representable by a linear range.

Parameters

[in]

r

Linear range instance.

Returns

Maximum value representable by r.

linear_range_get_value()

static int linear_range_get_value ( const struct linear_range * r, uint16_t idx, int32_t * val )

inlinestatic

#include <zephyr/sys/linear_range.h>

Obtain value given a linear range index.

Parameters

[in]	r	Linear range instance.
	idx	Range index.
[out]	val	Where value will be stored.

Return values

0	If successful
-EINVAL	If index is out of range.

linear_range_get_win_index()

static int linear_range_get_win_index ( const struct linear_range * r, int32_t val_min, int32_t val_max, uint16_t * idx )

inlinestatic

#include <zephyr/sys/linear_range.h>

Obtain index given a window of values.

If the window of values does not intersect with the range, -EINVAL will be returned. If intersection is partial (any of the window edges does not intersect), the nearest index will be stored and -ERANGE returned.

Parameters

[in]	r	Linear range instance.
	val_min	Minimum window value.
	val_max	Maximum window value.
[out]	idx	Where index will be stored.

Return values

0	If a valid index is found within linear range.
-ERANGE	If the given window of values falls partially out of the linear range.
-EINVAL	If the given window of values does not intersect with the linear range or if they are too narrow.

linear_range_group_get_index()

static int linear_range_group_get_index ( const struct linear_range * r, size_t r_cnt, int32_t val, uint16_t * idx )

inlinestatic

#include <zephyr/sys/linear_range.h>

Obtain index in a group given a value.

This function works the same way as linear_range_get_index(), but considering all ranges in the group.

Parameters

[in]	r	Linear range instances.
	r_cnt	Number of linear range instances.
	val	Value.
[out]	idx	Where index will be stored.

Return values

0	If value falls within the range group.
-ERANGE	If the value falls out of the range group.
-EINVAL	If input is not valid (i.e. zero groups).

linear_range_group_get_value()

static int linear_range_group_get_value ( const struct linear_range * r, size_t r_cnt, uint16_t idx, int32_t * val )

inlinestatic

#include <zephyr/sys/linear_range.h>

Obtain value in a group given a linear range index.

Parameters

[in]	r	Array of linear range instances.
	r_cnt	Number of linear range instances.
	idx	Range index.
[out]	val	Where value will be stored.

Return values

0	If successful
-EINVAL	If index is out of range.

linear_range_group_get_win_index()

static int linear_range_group_get_win_index ( const struct linear_range * r, size_t r_cnt, int32_t val_min, int32_t val_max, uint16_t * idx )

inlinestatic

#include <zephyr/sys/linear_range.h>

Obtain index in a group given a value that must be within a window of values.

This function works the same way as linear_range_get_win_index(), but considering all ranges in the group.

Parameters

[in]	r	Linear range instances.
	r_cnt	Number of linear range instances.
	val_min	Minimum window value.
	val_max	Maximum window value.
[out]	idx	Where index will be stored.

Return values

0	If a valid index is found within linear range group.
-ERANGE	If the given window of values falls partially out of the linear range group.
-EINVAL	If the given window of values does not intersect with the linear range group, if they are too narrow, or if input is invalid (i.e. zero groups).

linear_range_group_values_count()

static uint32_t linear_range_group_values_count ( const struct linear_range * r, size_t r_cnt )

inlinestatic

#include <zephyr/sys/linear_range.h>

Obtain the number of values representable by a group of linear ranges.

Parameters

[in]	r	Array of linear range instances.
	r_cnt	Number of linear range instances.

Returns

Number of ranges representable by the r group.

linear_range_values_count()

static uint32_t linear_range_values_count ( const struct linear_range * r )

inlinestatic

#include <zephyr/sys/linear_range.h>

Obtain the number of values representable in a linear range.

Parameters

[in]

r

Linear range instance.

Returns

Number of ranges representable by r.