include: zephyr: devicetree: Add DT_CHILD_BY_IDX

Adds `DT_CHILD_BY_IDX` to get the child elements of a node by index.

Signed-off-by: TOKITA Hiroshi <[email protected]>

Author: soburi

doc/build/dts/macros.bnf

@@ -96,6 +96,9 @@ node-macro =/ %s"DT_N" path-id %s"_FOREACH_NODELABEL" [ %s"_VARGS" ]
 node-macro =/ %s"DT_N" path-id %s"_NODELABEL_NUM"
 ; The node's zero-based index in the list of it's parent's child nodes.
 node-macro =/ %s"DT_N" path-id %s"_CHILD_IDX"
+; Identifies child nodes by ordinal number.
+node-macro =/ %s"DT_N" path-id %s"_CHILD_IDX_" *DIGIT
+node-macro =/ %s"DT_N" path-id %s"_CHILD_IDX_" *DIGIT "_EXISTS"
 ; The node's status macro; dt-name in this case is something like "okay"
 ; or "disabled".
 node-macro =/ %s"DT_N" path-id %s"_STATUS_" dt-name

include/zephyr/devicetree.h

@@ -435,6 +435,44 @@
  */
 #define DT_CHILD(node_id, child) UTIL_CAT(node_id, DT_S_PREFIX(child))
 
+/**
+ * @brief Get a child node by index
+ *
+ * This macro retrieves a child node of a specified node by its
+ * index. The index corresponds to the order in which the child nodes
+ * are defined in the Devicetree source.
+ *
+ * Example devicetree fragment:
+ *
+ * @code{.dts}
+ * / {
+ *     parent_node {
+ *         first_child {
+ *             reg = <0>;
+ *         };
+ *         second_child {
+ *             reg = <1>;
+ *         };
+ *     };
+ * };
+ * @endcode
+ *
+ * Example usage:
+ *
+ * @code{.c}
+ * DT_CHILD_BY_IDX(DT_NODELABEL(parent_node), 0) // "first_child"
+ * DT_CHILD_BY_IDX(DT_NODELABEL(parent_node), 1) // "second_child"
+ * @endcode
+ *
+ * @param node_id The identifier of the parent node. This can be obtained
+ *                using macros like DT_NODELABEL(), DT_PATH(), or similar.
+ * @param idx     The index of the child node to retrieve. Must be within
+ *                the range of 0 to DT_CHILD_NUM(node_id) - 1.
+ *
+ * @return The identifier of the child node at the specified index.
+ */
+#define DT_CHILD_BY_IDX(node_id, idx) UTIL_CAT(UTIL_CAT(node_id, _CHILD_IDX_), idx)
+
 /**
  * @brief Get a node identifier for a status `okay` node with a compatible
  *

scripts/dts/gen_defines.py

@@ -478,10 +478,13 @@ def write_children(node: edtlib.Node) -> None:
     out_dt_define(f"{node.z_path_id}_CHILD_NUM", len(node.children))
 
     ok_nodes_num = 0
-    for child in node.children.values():
+    for i, child in enumerate(node.children.values()):
         if child.status == "okay":
             ok_nodes_num = ok_nodes_num + 1
 
+        out_dt_define(f"{node.z_path_id}_CHILD_IDX_{i}", f"DT_{child.z_path_id}")
+        out_dt_define(f"{node.z_path_id}_CHILD_IDX_{i}_EXISTS", 1)
+
     out_dt_define(f"{node.z_path_id}_CHILD_NUM_STATUS_OKAY", ok_nodes_num)
 
     out_dt_define(f"{node.z_path_id}_FOREACH_CHILD(fn)",