devicetree: add DT(_INST)_FOREACH_PROP_ELEM_SEP(_VARGS)

Add a new set of helpers for expanding property entries with a
separator. These macros complement DT(_INST)FOREACH_PROP_ELEM(_VARGS) by
adding the capability to expand with a custom separator between property
entries. This allows, in some cases, to re-use existing macros (e.g.
DT_PROP_BY_IDX) without creating an auxiliary macro that just appends a
separator. Example:

```dts
n: node {
	...
	my-gpios = <&gpioa 0 GPIO_ACTIVE_HIGH>,
		   <&gpiob 1 GPIO_ACTIVE_HIGH>;
};
```

Before:

```c
 #define GPIO_DT_SPEC_BY_IDX_AND_COMMA(node_id, prop, idx) \
	GPIO_DT_SPEC_BY_IDX(node_id, prop, idx),

struct gpio_dt_spec specs[] = {
	DT_FOREACH_PROP_ELEM(DT_NODELABEL(n), my_gpios,
			     GPIO_DT_SPEC_BY_IDX_AND_COMMA)
};
```

After:

```c
struct gpio_dt_spec specs[] = {
	DT_FOREACH_PROP_ELEM_SEP(DT_NODELABEL(n), my_gpios,
				 GPIO_DT_SPEC_BY_IDX, (,))
};
```

Signed-off-by: Gerard Marull-Paretas <[email protected]>

Author: gmarull

doc/build/dts/macros.bnf

@@ -60,10 +60,12 @@ node-macro =/ %s"DT_N" path-id %s"_COMPAT_VENDOR_IDX_" DIGIT
 ; Every non-root node gets one of these macros, which expands to the node
 ; identifier for that node's parent in the devicetree.
 node-macro =/ %s"DT_N" path-id %s"_PARENT"
-; These are used internally by DT_FOREACH_PROP_ELEM(_VARGS), which
+; These are used internally by DT_FOREACH_PROP_ELEM(_SEP)(_VARGS), which
 ; iterates over each property element.
 node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM"
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM_SEP"
 node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM_VARGS"
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM_SEP_VARGS"
 ; These are used internally by DT_FOREACH_CHILD, which iterates over
 ; each child node.
 node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD"

include/zephyr/devicetree.h

@@ -2507,6 +2507,53 @@
 #define DT_FOREACH_PROP_ELEM(node_id, prop, fn)		\
 	DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM)(fn)
 
+/**
+ * @brief Invokes @p fn for each element in the value of property @p prop with
+ *        separator.
+ *
+ * Example devicetree fragment:
+ *
+ * @code{.dts}
+ *     n: node {
+ *             my-gpios = <&gpioa 0 GPIO_ACTICE_HIGH>,
+ *                        <&gpiob 1 GPIO_ACTIVE_HIGH>;
+ *     };
+ * @endcode
+ *
+ * Example usage:
+ *
+ * @code{.c}
+ *     struct gpio_dt_spec specs[] = {
+ *             DT_FOREACH_PROP_ELEM_SEP(DT_NODELABEL(n), my_gpios,
+ *                                      GPIO_DT_SPEC_BY_IDX, (,))
+ *     };
+ * @endcode
+ *
+ * This expands as a first step to:
+ *
+ * @code{.c}
+ *     struct gpio_dt_spec specs[] = {
+ *     struct gpio_dt_spec specs[] = {
+ *             GPIO_DT_SPEC_BY_IDX(DT_NODELABEL(n), my_gpios, 0),
+ *             GPIO_DT_SPEC_BY_IDX(DT_NODELABEL(n), my_gpios, 1)
+ *     };
+ * @endcode
+ *
+ * The "prop" argument must refer to a property with type string,
+ * array, uint8-array, string-array, phandles, or phandle-array. It is
+ * an error to use this macro with properties of other types.
+ *
+ * @param node_id node identifier
+ * @param prop lowercase-and-underscores property name
+ * @param fn macro to invoke
+ * @param sep Separator (e.g. comma or semicolon). Must be in parentheses;
+ *            this is required to enable providing a comma as separator.
+ *
+ * @see DT_FOREACH_PROP_ELEM
+ */
+#define DT_FOREACH_PROP_ELEM_SEP(node_id, prop, fn, sep) \
+	DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM_SEP)(fn, sep)
+
 /**
  * @brief Invokes @p fn for each element in the value of property @p prop with
  * multiple arguments.
@@ -2527,6 +2574,23 @@
 #define DT_FOREACH_PROP_ELEM_VARGS(node_id, prop, fn, ...)		\
 	DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM_VARGS)(fn, __VA_ARGS__)
 
+/**
+ * @brief Invokes @p fn for each element in the value of property @p prop with
+ * multiple arguments and a separator.
+ *
+ * @param node_id node identifier
+ * @param prop lowercase-and-underscores property name
+ * @param fn macro to invoke
+ * @param sep Separator (e.g. comma or semicolon). Must be in parentheses;
+ *            this is required to enable providing a comma as separator.
+ * @param ... variable number of arguments to pass to fn
+ *
+ * @see DT_FOREACH_PROP_ELEM_VARGS
+ */
+#define DT_FOREACH_PROP_ELEM_SEP_VARGS(node_id, prop, fn, sep, ...)	\
+	DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM_SEP_VARGS)(	\
+		fn, sep, __VA_ARGS__)
+
 /**
  * @brief Invokes @p fn for each status `okay` node of a compatible.
  *
@@ -3592,6 +3656,21 @@
 #define DT_INST_FOREACH_PROP_ELEM(inst, prop, fn) \
 	DT_FOREACH_PROP_ELEM(DT_DRV_INST(inst), prop, fn)
 
+/**
+ * @brief Invokes @p fn for each element of property @p prop for
+ *        a `DT_DRV_COMPAT` instance with a separator.
+ *
+ * Equivalent to DT_FOREACH_PROP_ELEM_SEP(DT_DRV_INST(inst), prop, fn, sep).
+ *
+ * @param inst instance number
+ * @param prop lowercase-and-underscores property name
+ * @param fn macro to invoke
+ * @param sep Separator (e.g. comma or semicolon). Must be in parentheses;
+ *            this is required to enable providing a comma as separator.
+ */
+#define DT_INST_FOREACH_PROP_ELEM_SEP(inst, prop, fn, sep) \
+	DT_FOREACH_PROP_ELEM_SEP(DT_DRV_INST(inst), prop, fn, sep)
+
 /**
  * @brief Invokes @p fn for each element of property @p prop for
  *        a `DT_DRV_COMPAT` instance with multiple arguments.
@@ -3610,7 +3689,28 @@
 	DT_FOREACH_PROP_ELEM_VARGS(DT_DRV_INST(inst), prop, fn, __VA_ARGS__)
 
 /**
- * @brief Does a `DT_DRV_COMPAT` instance have a property?
+ * @brief Invokes @p fn for each element of property @p prop for
+ *        a `DT_DRV_COMPAT` instance with multiple arguments and a sepatator.
+ *
+ * Equivalent to
+ *      DT_FOREACH_PROP_ELEM_SEP_VARGS(DT_DRV_INST(inst), prop, fn, sep,
+ *                                     __VA_ARGS__)
+ *
+ * @param inst instance number
+ * @param prop lowercase-and-underscores property name
+ * @param fn macro to invoke
+ * @param sep Separator (e.g. comma or semicolon). Must be in parentheses;
+ *            this is required to enable providing a comma as separator.
+ * @param ... variable number of arguments to pass to fn
+ *
+ * @see DT_INST_FOREACH_PROP_ELEM
+ */
+#define DT_INST_FOREACH_PROP_ELEM_SEP_VARGS(inst, prop, fn, sep, ...)		\
+	DT_FOREACH_PROP_ELEM_SEP_VARGS(DT_DRV_INST(inst), prop, fn, sep,	\
+				       __VA_ARGS__)
+
+/**
+ * @brief Does a DT_DRV_COMPAT instance have a property?
  * @param inst instance number
  * @param prop lowercase-and-underscores property name
  * @return 1 if the instance has the property, 0 otherwise.

scripts/dts/gen_defines.py

@@ -660,13 +660,24 @@ def write_vanilla_props(node):
         if prop.type in FOREACH_PROP_ELEM_TYPES:
             # DT_N_<node-id>_P_<prop-id>_FOREACH_PROP_ELEM
             macro2val[f"{macro}_FOREACH_PROP_ELEM(fn)"] = \
-                ' \\\n\t'.join(f'fn(DT_{node.z_path_id}, {prop_id}, {i})'
-                              for i in range(len(prop.val)))
+                ' \\\n\t'.join(
+                    f'fn(DT_{node.z_path_id}, {prop_id}, {i})'
+                    for i in range(len(prop.val)))
+
+            macro2val[f"{macro}_FOREACH_PROP_ELEM_SEP(fn, sep)"] = \
+                ' DT_DEBRACKET_INTERNAL sep \\\n\t'.join(
+                    f'fn(DT_{node.z_path_id}, {prop_id}, {i})'
+                    for i in range(len(prop.val)))
 
             macro2val[f"{macro}_FOREACH_PROP_ELEM_VARGS(fn, ...)"] = \
-                ' \\\n\t'.join(f'fn(DT_{node.z_path_id}, {prop_id}, {i},'
-                                ' __VA_ARGS__)'
-                              for i in range(len(prop.val)))
+                ' \\\n\t'.join(
+                    f'fn(DT_{node.z_path_id}, {prop_id}, {i}, __VA_ARGS__)'
+                    for i in range(len(prop.val)))
+
+            macro2val[f"{macro}_FOREACH_PROP_ELEM_SEP_VARGS(fn, sep, ...)"] = \
+                ' DT_DEBRACKET_INTERNAL sep \\\n\t'.join(
+                    f'fn(DT_{node.z_path_id}, {prop_id}, {i}, __VA_ARGS__)'
+                    for i in range(len(prop.val)))
 
         plen = prop_len(prop)
         if plen is not None: