Skip to content

Commit

Permalink
Devicetree: Devicetree Bindings: Add new APIs
Browse files Browse the repository at this point in the history 
The existing APIs for enums were rewritten to support the changes.
Additional macros were added to now also support getting specific
indices from the array / string-array.
The macros can be evoked the same way like before, since nothing changed
for the interface. Therefore, these changes are backward compatible.

Signed-off-by: Joel Hirsbrunner <jhirsbrunner@baumer.com>
  • Loading branch information
@JHirsbrunner @nashif
JHirsbrunner authored and nashif committed Oct 15, 2024
1 parent 7454cb9 commit ae747c4
Showing 1 changed file with 104 additions and 24 deletions.
128 changes: 104 additions & 24 deletions include/zephyr/devicetree.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
* @brief devicetree.h API
* @defgroup devicetree Devicetree
* @since 2.2
* @version 1.1.0
* @version 1.2.0
* @{
* @}
*/
Expand Down Expand Up @@ -913,75 +913,122 @@
(DT_PROP(node_id, prop)), (default_value))

/**
* @brief Get a property value's index into its enumeration values
* @brief Get a property array value's index into its enumeration values
*
* The return values start at zero.
*
* Example devicetree fragment:
*
* @code{.dts}
* usb1: usb@12340000 {
* maximum-speed = "full-speed";
* };
* usb2: usb@12341000 {
* maximum-speed = "super-speed";
* some_node: some-node {
* compat = "vend,enum-string-array";
* foos =
* <&phandle val1>,
* <&phandle val2>,
* <&phandle val3>;
* foo-names = "default", "option3", "option1";
* };
* @endcode
*
* Example bindings fragment:
*
* @code{.yaml}
* properties:
* maximum-speed:
* type: string
* enum:
* - "low-speed"
* - "full-speed"
* - "high-speed"
* - "super-speed"
* compatible: vend,enum-string-array
* properties:
* foos:
* type: phandle-array
* description: |
* Explanation about what this phandle-array exactly is for.
*
* foo-names:
* type: string-array
* description: |
* Some explanation about the available options
* default: explain default
* option1: explain option1
* option2: explain option2
* option3: explain option3
* enum:
* - default
* - option1
* - option2
* - option3
* @endcode
*
* Example usage:
*
* @code{.c}
* DT_ENUM_IDX(DT_NODELABEL(usb1), maximum_speed) // 1
* DT_ENUM_IDX(DT_NODELABEL(usb2), maximum_speed) // 3
* DT_ENUM_IDX_BY_IDX(DT_NODELABEL(some_node), foo_names, 0) // 0
* DT_ENUM_IDX_BY_IDX(DT_NODELABEL(some_node), foo_names, 2) // 1
* @endcode
*
* @param node_id node identifier
* @param prop lowercase-and-underscores property name
* @param idx the index to get
* @return zero-based index of the property's value in its enum: list
*/
#define DT_ENUM_IDX(node_id, prop) DT_CAT4(node_id, _P_, prop, _ENUM_IDX)
#define DT_ENUM_IDX_BY_IDX(node_id, prop, idx) \
DT_CAT6(node_id, _P_, prop, _IDX_, idx, _ENUM_IDX)

/**
* @brief Like DT_ENUM_IDX(), but with a fallback to a default enum index
* @brief Equivalent to @ref DT_ENUM_IDX_BY_IDX(node_id, prop, 0).
* @param node_id node identifier
* @param prop lowercase-and-underscores property name
* @return zero-based index of the property's value in its enum: list
*/
#define DT_ENUM_IDX(node_id, prop) DT_ENUM_IDX_BY_IDX(node_id, prop, 0)

/**
* @brief Like DT_ENUM_IDX_BY_IDX(), but with a fallback to a default enum index
*
* If the value exists, this expands to its zero based index value thanks to
* DT_ENUM_IDX(node_id, prop).
* DT_ENUM_IDX_BY_IDX(node_id, prop, idx).
*
* Otherwise, this expands to provided default index enum value.
*
* @param node_id node identifier
* @param prop lowercase-and-underscores property name
* @param idx the index to get
* @param default_idx_value a fallback index value to expand to
* @return zero-based index of the property's value in its enum if present,
* default_idx_value otherwise
*/
#define DT_ENUM_IDX_BY_IDX_OR(node_id, prop, idx, default_idx_value) \
COND_CODE_1(DT_PROP_HAS_IDX(node_id, prop, idx), \
(DT_ENUM_IDX_BY_IDX(node_id, prop, idx)), (default_idx_value))

/**
* @brief Equivalent to DT_ENUM_IDX_BY_IDX_OR(node_id, prop, 0, default_idx_value).
* @param node_id node identifier
* @param prop lowercase-and-underscores property name
* @param default_idx_value a fallback index value to expand to
* @return zero-based index of the property's value in its enum if present,
* default_idx_value otherwise
*/
#define DT_ENUM_IDX_OR(node_id, prop, default_idx_value) \
COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
(DT_ENUM_IDX(node_id, prop)), (default_idx_value))
DT_ENUM_IDX_BY_IDX_OR(node_id, prop, 0, default_idx_value)

/**
* @brief Does a node enumeration property have a given value?
* @brief Does a node enumeration property array have a given value?
*
* @param node_id node identifier
* @param prop lowercase-and-underscores property name
* @param idx the index to get
* @param value lowercase-and-underscores enumeration value
* @return 1 if the node property has the value @a value, 0 otherwise.
*/
#define DT_ENUM_HAS_VALUE_BY_IDX(node_id, prop, idx, value) \
IS_ENABLED(DT_CAT8(node_id, _P_, prop, _IDX_, idx, _ENUM_VAL_, value, _EXISTS))

/**
* @brief Equivalent to DT_ENUM_HAS_VALUE_BY_IDX(node_id, prop, 0, value).
* @param node_id node identifier
* @param prop lowercase-and-underscores property name
* @param value lowercase-and-underscores enumeration value
* @return 1 if the node property has the value @a value, 0 otherwise.
*/
#define DT_ENUM_HAS_VALUE(node_id, prop, value) \
IS_ENABLED(DT_CAT6(node_id, _P_, prop, _ENUM_VAL_, value, _EXISTS))
DT_ENUM_HAS_VALUE_BY_IDX(node_id, prop, 0, value)

/**
* @brief Get a string property's value as a token.
Expand Down Expand Up @@ -3964,6 +4011,16 @@
#define DT_INST_FOREACH_CHILD_STATUS_OKAY_SEP_VARGS(inst, fn, sep, ...) \
DT_FOREACH_CHILD_STATUS_OKAY_SEP_VARGS(DT_DRV_INST(inst), fn, sep, __VA_ARGS__)

/**
* @brief Get a `DT_DRV_COMPAT` property array value's index into its enumeration values
* @param inst instance number
* @param prop lowercase-and-underscores property name
* @param idx the index to get
* @return zero-based index of the property's value in its enum: list
*/
#define DT_INST_ENUM_IDX_BY_IDX(inst, prop, idx) \
DT_ENUM_IDX_BY_IDX(DT_DRV_INST(inst), prop, idx)

/**
* @brief Get a `DT_DRV_COMPAT` value's index into its enumeration values
* @param inst instance number
Expand All @@ -3973,6 +4030,18 @@
#define DT_INST_ENUM_IDX(inst, prop) \
DT_ENUM_IDX(DT_DRV_INST(inst), prop)

/**
* @brief Like DT_INST_ENUM_IDX_BY_IDX(), but with a fallback to a default enum index
* @param inst instance number
* @param prop lowercase-and-underscores property name
* @param idx the index to get
* @param default_idx_value a fallback index value to expand to
* @return zero-based index of the property's value in its enum if present,
* default_idx_value otherwise
*/
#define DT_INST_ENUM_IDX_BY_IDX_OR(inst, prop, idx, default_idx_value) \
DT_ENUM_IDX_BY_IDX_OR(DT_DRV_INST(inst), prop, idx, default_idx_value)

/**
* @brief Like DT_INST_ENUM_IDX(), but with a fallback to a default enum index
* @param inst instance number
Expand All @@ -3984,6 +4053,17 @@
#define DT_INST_ENUM_IDX_OR(inst, prop, default_idx_value) \
DT_ENUM_IDX_OR(DT_DRV_INST(inst), prop, default_idx_value)

/**
* @brief Does a `DT_DRV_COMPAT` enumeration property have a given value by index?
* @param inst instance number
* @param prop lowercase-and-underscores property name
* @param idx the index to get
* @param value lowercase-and-underscores enumeration value
* @return zero-based index of the property's value in its enum
*/
#define DT_INST_ENUM_HAS_VALUE_BY_IDX(inst, prop, idx, value) \
DT_ENUM_HAS_VALUE_BY_IDX(DT_DRV_INST(inst), prop, idx, value)

/**
* @brief Does a `DT_DRV_COMPAT` enumeration property have a given value?
*
Expand Down

0 comments on commit ae747c4

Please sign in to comment.