Skip to content

Commit 6918e3d

Browse files
pabigotnashif
authored andcommitted
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>
1 parent 63638ce commit 6918e3d

File tree

3 files changed

+57
-3
lines changed

3 files changed

+57
-3
lines changed

doc/guides/dts/api-usage.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -303,8 +303,9 @@ See :ref:`dt-get-device` for ways to do that.
303303

304304
Another common use case is accessing specifier values in a phandle array. The
305305
general purpose APIs for this are :c:func:`DT_PHA_BY_IDX` and :c:func:`DT_PHA`.
306-
There are also hardware-specific shorthands like :c:func:`DT_GPIO_LABEL_BY_IDX`,
307-
:c:func:`DT_GPIO_LABEL`, :c:func:`DT_GPIO_PIN_BY_IDX`, :c:func:`DT_GPIO_PIN`,
306+
There are also hardware-specific shorthands like :c:func:`DT_GPIO_CTLR_BY_IDX`,
307+
:c:func:`DT_GPIO_CTLR`, :c:func:`DT_GPIO_LABEL_BY_IDX`, :c:func:`DT_GPIO_LABEL`,
308+
:c:func:`DT_GPIO_PIN_BY_IDX`, :c:func:`DT_GPIO_PIN`,
308309
:c:func:`DT_GPIO_FLAGS_BY_IDX`, and :c:func:`DT_GPIO_FLAGS`.
309310

310311
See :c:func:`DT_PHA_HAS_CELL_AT_IDX` and :c:func:`DT_PROP_HAS_IDX` for ways to

include/devicetree/gpio.h

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,47 @@ extern "C" {
2323
* @{
2424
*/
2525

26+
/**
27+
* @brief Get the node identifier for the controller phandle from a
28+
* gpio phandle-array property at an index
29+
*
30+
* Example devicetree fragment:
31+
*
32+
* gpio1: gpio@... { };
33+
*
34+
* gpio2: gpio@... { };
35+
*
36+
* n: node {
37+
* gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
38+
* <&gpio2 30 GPIO_ACTIVE_HIGH>;
39+
* };
40+
*
41+
* Example usage:
42+
*
43+
* DT_GPIO_CTLR_BY_IDX(DT_NODELABEL(n), gpios, 1) // DT_NODELABEL(gpio2)
44+
*
45+
* @param node_id node identifier
46+
* @param gpio_pha lowercase-and-underscores GPIO property with
47+
* type "phandle-array"
48+
* @param idx logical index into "gpio_pha"
49+
* @return the node identifier for the gpio controller referenced at
50+
* index "idx"
51+
* @see DT_PHANDLE_BY_IDX()
52+
*/
53+
#define DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx) \
54+
DT_PHANDLE_BY_IDX(node_id, gpio_pha, idx)
55+
56+
/**
57+
* @brief Equivalent to DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)
58+
* @param node_id node identifier
59+
* @param gpio_pha lowercase-and-underscores GPIO property with
60+
* type "phandle-array"
61+
* @return the label property of the node referenced at index 0
62+
* @see DT_GPIO_CTLR_BY_IDX()
63+
*/
64+
#define DT_GPIO_CTLR(node_id, gpio_pha) \
65+
DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)
66+
2667
/**
2768
* @brief Get a label property from a gpio phandle-array property
2869
* at an index
@@ -58,7 +99,7 @@ extern "C" {
5899
* @see DT_PHANDLE_BY_IDX()
59100
*/
60101
#define DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, idx) \
61-
DT_PROP_BY_PHANDLE_IDX(node_id, gpio_pha, idx, label)
102+
DT_PROP(DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx), label)
62103

63104
/**
64105
* @brief Equivalent to DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0)

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -856,6 +856,18 @@ static void test_phandles(void)
856856
#define DT_DRV_COMPAT vnd_phandle_holder
857857
static void test_gpio(void)
858858
{
859+
/* DT_GPIO_CTLR_BY_IDX */
860+
zassert_true(!strcmp(TO_STRING(DT_GPIO_CTLR_BY_IDX(TEST_PH, gpios, 0)),
861+
TO_STRING(DT_NODELABEL(test_gpio_1))),
862+
"gpio 0 ctlr idx");
863+
zassert_true(!strcmp(TO_STRING(DT_GPIO_CTLR_BY_IDX(TEST_PH, gpios, 1)),
864+
TO_STRING(DT_NODELABEL(test_gpio_2))),
865+
"gpio 1 ctlr idx");
866+
867+
/* DT_GPIO_CTLR */
868+
zassert_true(!strcmp(TO_STRING(DT_GPIO_CTLR(TEST_PH, gpios)),
869+
TO_STRING(DT_NODELABEL(test_gpio_1))),
870+
"gpio 0 ctlr");
859871

860872
/* DT_GPIO_LABEL_BY_IDX */
861873
zassert_true(!strcmp(DT_GPIO_LABEL_BY_IDX(TEST_PH, gpios, 0),

0 commit comments

Comments
 (0)