devicetree.h: add DT_NODE_CHILD_IDX

It can be useful to know what a node's index is in its parent's list
of children. This information is now available to C via
gen_defines.py, but no user-facing macros are available to access it.

Add a macro which exposes this information to users via devicetree.h.

Some APIs want to build on devicetree.h by creating some derived
structure for each of a node's children. It can therefore be
convenient to use each child's index in the list of children as an
identifier for the child.

Some concrete and common examples are "gpio-keys" and "gpio-leds",
which allow you to define arbitrary numbers of keys and LEDs as child
nodes of nodes with those compatibles. Derived APIs can use a key or
LED node's index in its list of parents as a way to identify which of
several structures is relevant to a particular controlled key or LED.

These are just examples, though -- the feature added here makes no
assumptions about where it's being used.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

include/devicetree.h

@@ -474,6 +474,30 @@
  */
 #define DT_NODE_FULL_NAME(node_id) DT_CAT(node_id, _FULL_NAME)
 
+/**
+ * @brief Get a devicetree node's index into its parent's list of children
+ *
+ * Indexes are zero-based.
+ *
+ * It is an error to use this macro with the root node.
+ *
+ * Example devicetree fragment:
+ *
+ *     parent {
+ *             c1: child-1 {};
+ *             c2: child-2 {};
+ *     };
+ *
+ * Example usage:
+ *
+ *     DT_NODE_CHILD_IDX(DT_NODELABEL(c1)) // 0
+ *     DT_NODE_CHILD_IDX(DT_NODELABEL(c2)) // 1
+ *
+ * @param node_id node identifier
+ * @return the node's index in its parent node's list of children
+ */
+#define DT_NODE_CHILD_IDX(node_id) DT_CAT(node_id, _CHILD_IDX)
+
 /**
  * @brief Do node_id1 and node_id2 refer to the same node?
  *

tests/lib/devicetree/api/src/main.c

@@ -1996,6 +1996,13 @@ static void test_node_name(void)
 			     "reg-holder"), "");
 }
 
+static void test_node_child_idx(void)
+{
+	zassert_equal(DT_NODE_CHILD_IDX(DT_NODELABEL(test_child_a)), 0, "");
+	zassert_equal(DT_NODE_CHILD_IDX(DT_NODELABEL(test_child_b)), 1, "");
+	zassert_equal(DT_NODE_CHILD_IDX(DT_NODELABEL(test_child_c)), 2, "");
+}
+
 static void test_same_node(void)
 {
 	zassert_true(DT_SAME_NODE(TEST_DEADBEEF, TEST_DEADBEEF), "");
@@ -2369,6 +2376,7 @@ void test_main(void)
 			 ztest_unit_test(test_dep_ord),
 			 ztest_unit_test(test_path),
 			 ztest_unit_test(test_node_name),
+			 ztest_unit_test(test_node_child_idx),
 			 ztest_unit_test(test_same_node),
 			 ztest_unit_test(test_pinctrl),
 			 ztest_unit_test(test_mbox),