devicetree: gpio: provide accessors for controller phandle

Provide a helper to extract the devicetree node_id for a GPIO
controller from a gpio phandle array.  This can be used with
DEVICE_DT_GET() to directly reference the corresponding controller
device.

Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>

Author: pabigot

doc/guides/dts/api-usage.rst

@@ -303,8 +303,9 @@ See :ref:`dt-get-device` for ways to do that.
 
 Another common use case is accessing specifier values in a phandle array. The
 general purpose APIs for this are :c:func:`DT_PHA_BY_IDX` and :c:func:`DT_PHA`.
-There are also hardware-specific shorthands like :c:func:`DT_GPIO_LABEL_BY_IDX`,
-:c:func:`DT_GPIO_LABEL`, :c:func:`DT_GPIO_PIN_BY_IDX`, :c:func:`DT_GPIO_PIN`,
+There are also hardware-specific shorthands like :c:func:`DT_GPIO_CTLR_BY_IDX`,
+:c:func:`DT_GPIO_CTLR`, :c:func:`DT_GPIO_LABEL_BY_IDX`, :c:func:`DT_GPIO_LABEL`,
+:c:func:`DT_GPIO_PIN_BY_IDX`, :c:func:`DT_GPIO_PIN`,
 :c:func:`DT_GPIO_FLAGS_BY_IDX`, and :c:func:`DT_GPIO_FLAGS`.
 
 See :c:func:`DT_PHA_HAS_CELL_AT_IDX` and :c:func:`DT_PROP_HAS_IDX` for ways to

include/devicetree/gpio.h

@@ -23,6 +23,47 @@ extern "C" {
  * @{
  */
 
+/**
+ * @brief Get the node identifier for the controller phandle from a
+ *        gpio phandle-array property at an index
+ *
+ * Example devicetree fragment:
+ *
+ *     gpio1: gpio@... { };
+ *
+ *     gpio2: gpio@... { };
+ *
+ *     n: node {
+ *             gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
+ *                     <&gpio2 30 GPIO_ACTIVE_HIGH>;
+ *     };
+ *
+ * Example usage:
+ *
+ *     DT_GPIO_CTLR_BY_IDX(DT_NODELABEL(n), gpios, 1) // DT_NODELABEL(gpio2)
+ *
+ * @param node_id node identifier
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @param idx logical index into "gpio_pha"
+ * @return the node identifier for the gpio controller referenced at
+ *         index "idx"
+ * @see DT_PHANDLE_BY_IDX()
+ */
+#define DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx) \
+	DT_PHANDLE_BY_IDX(node_id, gpio_pha, idx)
+
+/**
+ * @brief Equivalent to DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)
+ * @param node_id node identifier
+ * @param gpio_pha lowercase-and-underscores GPIO property with
+ *        type "phandle-array"
+ * @return the label property of the node referenced at index 0
+ * @see DT_GPIO_CTLR_BY_IDX()
+ */
+#define DT_GPIO_CTLR(node_id, gpio_pha) \
+	DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)
+
 /**
  * @brief Get a label property from a gpio phandle-array property
  *        at an index
@@ -58,7 +99,7 @@ extern "C" {
  * @see DT_PHANDLE_BY_IDX()
  */
 #define DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, idx) \
-	DT_PROP_BY_PHANDLE_IDX(node_id, gpio_pha, idx, label)
+	DT_PROP(DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx), label)
 
 /**
  * @brief Equivalent to DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0)

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

@@ -856,6 +856,18 @@ static void test_phandles(void)
 #define DT_DRV_COMPAT vnd_phandle_holder
 static void test_gpio(void)
 {
+	/* DT_GPIO_CTLR_BY_IDX */
+	zassert_true(!strcmp(TO_STRING(DT_GPIO_CTLR_BY_IDX(TEST_PH, gpios, 0)),
+			     TO_STRING(DT_NODELABEL(test_gpio_1))),
+		     "gpio 0 ctlr idx");
+	zassert_true(!strcmp(TO_STRING(DT_GPIO_CTLR_BY_IDX(TEST_PH, gpios, 1)),
+			     TO_STRING(DT_NODELABEL(test_gpio_2))),
+		     "gpio 1 ctlr idx");
+
+	/* DT_GPIO_CTLR */
+	zassert_true(!strcmp(TO_STRING(DT_GPIO_CTLR(TEST_PH, gpios)),
+			     TO_STRING(DT_NODELABEL(test_gpio_1))),
+		     "gpio 0 ctlr");
 
 	/* DT_GPIO_LABEL_BY_IDX */
 	zassert_true(!strcmp(DT_GPIO_LABEL_BY_IDX(TEST_PH, gpios, 0),