LCOV - code coverage report
Current view: top level - zephyr/devicetree - gpio.h Coverage Total Hit
Test: new.info Lines: 100.0 % 14 14
Test Date: 2025-09-05 20:47:19

            Line data    Source code
       1            1 : /**
       2              :  * @file
       3              :  * @brief GPIO Devicetree macro public API header file.
       4              :  */
       5              : 
       6              : /*
       7              :  * Copyright (c) 2020, Linaro Ltd.
       8              :  * Copyright (c) 2020 Nordic Semiconductor
       9              :  *
      10              :  * SPDX-License-Identifier: Apache-2.0
      11              :  */
      12              : 
      13              : #ifndef ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_
      14              : #define ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_
      15              : 
      16              : #ifdef __cplusplus
      17              : extern "C" {
      18              : #endif
      19              : 
      20              : /**
      21              :  * @defgroup devicetree-gpio Devicetree GPIO API
      22              :  * @ingroup devicetree
      23              :  * @ingroup gpio_interface
      24              :  * @{
      25              :  *
      26              :  * @defgroup devicetree-gpio-pin-headers GPIO pin headers
      27              :  * @brief Constants for pins exposed on common GPIO pin headers
      28              :  * @{
      29              :  * @}
      30              :  */
      31              : 
      32              : /**
      33              :  * @brief Get the node identifier for the controller phandle from a
      34              :  *        gpio phandle-array property at an index
      35              :  *
      36              :  * Example devicetree fragment:
      37              :  *
      38              :  *     gpio1: gpio@... { };
      39              :  *
      40              :  *     gpio2: gpio@... { };
      41              :  *
      42              :  *     n: node {
      43              :  *             gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
      44              :  *                     <&gpio2 30 GPIO_ACTIVE_HIGH>;
      45              :  *     };
      46              :  *
      47              :  * Example usage:
      48              :  *
      49              :  *     DT_GPIO_CTLR_BY_IDX(DT_NODELABEL(n), gpios, 1) // DT_NODELABEL(gpio2)
      50              :  *
      51              :  * @param node_id node identifier
      52              :  * @param gpio_pha lowercase-and-underscores GPIO property with
      53              :  *        type "phandle-array"
      54              :  * @param idx logical index into "gpio_pha"
      55              :  * @return the node identifier for the gpio controller referenced at
      56              :  *         index "idx"
      57              :  * @see DT_PHANDLE_BY_IDX()
      58              :  */
      59            1 : #define DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx) \
      60              :         DT_PHANDLE_BY_IDX(node_id, gpio_pha, idx)
      61              : 
      62              : /**
      63              :  * @brief Equivalent to DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)
      64              :  * @param node_id node identifier
      65              :  * @param gpio_pha lowercase-and-underscores GPIO property with
      66              :  *        type "phandle-array"
      67              :  * @return a node identifier for the gpio controller at index 0
      68              :  *         in "gpio_pha"
      69              :  * @see DT_GPIO_CTLR_BY_IDX()
      70              :  */
      71            1 : #define DT_GPIO_CTLR(node_id, gpio_pha) \
      72              :         DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)
      73              : 
      74              : /**
      75              :  * @brief Get a GPIO specifier's pin cell at an index
      76              :  *
      77              :  * This macro only works for GPIO specifiers with cells named "pin".
      78              :  * Refer to the node's binding to check if necessary.
      79              :  *
      80              :  * Example devicetree fragment:
      81              :  *
      82              :  *     gpio1: gpio@... {
      83              :  *             compatible = "vnd,gpio";
      84              :  *             #gpio-cells = <2>;
      85              :  *     };
      86              :  *
      87              :  *     gpio2: gpio@... {
      88              :  *             compatible = "vnd,gpio";
      89              :  *             #gpio-cells = <2>;
      90              :  *     };
      91              :  *
      92              :  *     n: node {
      93              :  *             gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
      94              :  *                     <&gpio2 30 GPIO_ACTIVE_HIGH>;
      95              :  *     };
      96              :  *
      97              :  * Bindings fragment for the vnd,gpio compatible:
      98              :  *
      99              :  *     gpio-cells:
     100              :  *       - pin
     101              :  *       - flags
     102              :  *
     103              :  * Example usage:
     104              :  *
     105              :  *     DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 0) // 10
     106              :  *     DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 1) // 30
     107              :  *
     108              :  * @param node_id node identifier
     109              :  * @param gpio_pha lowercase-and-underscores GPIO property with
     110              :  *        type "phandle-array"
     111              :  * @param idx logical index into "gpio_pha"
     112              :  * @return the pin cell value at index "idx"
     113              :  * @see DT_PHA_BY_IDX()
     114              :  */
     115            1 : #define DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, idx) \
     116              :         DT_PHA_BY_IDX(node_id, gpio_pha, idx, pin)
     117              : 
     118              : /**
     119              :  * @brief Equivalent to DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0)
     120              :  * @param node_id node identifier
     121              :  * @param gpio_pha lowercase-and-underscores GPIO property with
     122              :  *        type "phandle-array"
     123              :  * @return the pin cell value at index 0
     124              :  * @see DT_GPIO_PIN_BY_IDX()
     125              :  */
     126            1 : #define DT_GPIO_PIN(node_id, gpio_pha) \
     127              :         DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0)
     128              : 
     129              : /**
     130              :  * @brief Get a GPIO specifier's flags cell at an index
     131              :  *
     132              :  * This macro expects GPIO specifiers with cells named "flags".
     133              :  * If there is no "flags" cell in the GPIO specifier, zero is returned.
     134              :  * Refer to the node's binding to check specifier cell names if necessary.
     135              :  *
     136              :  * Example devicetree fragment:
     137              :  *
     138              :  *     gpio1: gpio@... {
     139              :  *             compatible = "vnd,gpio";
     140              :  *             #gpio-cells = <2>;
     141              :  *     };
     142              :  *
     143              :  *     gpio2: gpio@... {
     144              :  *             compatible = "vnd,gpio";
     145              :  *             #gpio-cells = <2>;
     146              :  *     };
     147              :  *
     148              :  *     n: node {
     149              :  *             gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
     150              :  *                     <&gpio2 30 GPIO_ACTIVE_HIGH>;
     151              :  *     };
     152              :  *
     153              :  * Bindings fragment for the vnd,gpio compatible:
     154              :  *
     155              :  *     gpio-cells:
     156              :  *       - pin
     157              :  *       - flags
     158              :  *
     159              :  * Example usage:
     160              :  *
     161              :  *     DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 0) // GPIO_ACTIVE_LOW
     162              :  *     DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 1) // GPIO_ACTIVE_HIGH
     163              :  *
     164              :  * @param node_id node identifier
     165              :  * @param gpio_pha lowercase-and-underscores GPIO property with
     166              :  *        type "phandle-array"
     167              :  * @param idx logical index into "gpio_pha"
     168              :  * @return the flags cell value at index "idx", or zero if there is none
     169              :  * @see DT_PHA_BY_IDX()
     170              :  */
     171            1 : #define DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, idx) \
     172              :         DT_PHA_BY_IDX_OR(node_id, gpio_pha, idx, flags, 0)
     173              : 
     174              : /**
     175              :  * @brief Equivalent to DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0)
     176              :  * @param node_id node identifier
     177              :  * @param gpio_pha lowercase-and-underscores GPIO property with
     178              :  *        type "phandle-array"
     179              :  * @return the flags cell value at index 0, or zero if there is none
     180              :  * @see DT_GPIO_FLAGS_BY_IDX()
     181              :  */
     182            1 : #define DT_GPIO_FLAGS(node_id, gpio_pha) \
     183              :         DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0)
     184              : 
     185              : /**
     186              :  * @brief Get the number of GPIO hogs in a node
     187              :  *
     188              :  * This expands to the number of hogged GPIOs, or zero if there are none.
     189              :  *
     190              :  * Example devicetree fragment:
     191              :  *
     192              :  *     gpio1: gpio@... {
     193              :  *       compatible = "vnd,gpio";
     194              :  *       #gpio-cells = <2>;
     195              :  *
     196              :  *       n1: node-1 {
     197              :  *               gpio-hog;
     198              :  *               gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>;
     199              :  *               output-high;
     200              :  *       };
     201              :  *
     202              :  *       n2: node-2 {
     203              :  *               gpio-hog;
     204              :  *               gpios = <3 GPIO_ACTIVE_HIGH>;
     205              :  *               output-low;
     206              :  *       };
     207              :  *     };
     208              :  *
     209              :  * Bindings fragment for the vnd,gpio compatible:
     210              :  *
     211              :  *     gpio-cells:
     212              :  *       - pin
     213              :  *       - flags
     214              :  *
     215              :  * Example usage:
     216              :  *
     217              :  *     DT_NUM_GPIO_HOGS(DT_NODELABEL(n1)) // 2
     218              :  *     DT_NUM_GPIO_HOGS(DT_NODELABEL(n2)) // 1
     219              :  *
     220              :  * @param node_id node identifier; may or may not be a GPIO hog node.
     221              :  * @return number of hogged GPIOs in the node
     222              :  */
     223            1 : #define DT_NUM_GPIO_HOGS(node_id) \
     224              :         COND_CODE_1(IS_ENABLED(DT_CAT(node_id, _GPIO_HOGS_EXISTS)), \
     225              :                     (DT_CAT(node_id, _GPIO_HOGS_NUM)), (0))
     226              : 
     227              : /**
     228              :  * @brief Get a GPIO hog specifier's pin cell at an index
     229              :  *
     230              :  * This macro only works for GPIO specifiers with cells named "pin".
     231              :  * Refer to the node's binding to check if necessary.
     232              :  *
     233              :  * Example devicetree fragment:
     234              :  *
     235              :  *     gpio1: gpio@... {
     236              :  *       compatible = "vnd,gpio";
     237              :  *       #gpio-cells = <2>;
     238              :  *
     239              :  *       n1: node-1 {
     240              :  *               gpio-hog;
     241              :  *               gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>;
     242              :  *               output-high;
     243              :  *       };
     244              :  *
     245              :  *       n2: node-2 {
     246              :  *               gpio-hog;
     247              :  *               gpios = <3 GPIO_ACTIVE_HIGH>;
     248              :  *               output-low;
     249              :  *       };
     250              :  *     };
     251              :  *
     252              :  * Bindings fragment for the vnd,gpio compatible:
     253              :  *
     254              :  *     gpio-cells:
     255              :  *       - pin
     256              :  *       - flags
     257              :  *
     258              :  * Example usage:
     259              :  *
     260              :  *     DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n1), 0) // 0
     261              :  *     DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n1), 1) // 1
     262              :  *     DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n2), 0) // 3
     263              :  *
     264              :  * @param node_id node identifier
     265              :  * @param idx logical index into "gpios"
     266              :  * @return the pin cell value at index "idx"
     267              :  */
     268            1 : #define DT_GPIO_HOG_PIN_BY_IDX(node_id, idx) \
     269              :         DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_pin)
     270              : 
     271              : /**
     272              :  * @brief Get a GPIO hog specifier's flags cell at an index
     273              :  *
     274              :  * This macro expects GPIO specifiers with cells named "flags".
     275              :  * If there is no "flags" cell in the GPIO specifier, zero is returned.
     276              :  * Refer to the node's binding to check specifier cell names if necessary.
     277              :  *
     278              :  * Example devicetree fragment:
     279              :  *
     280              :  *     gpio1: gpio@... {
     281              :  *       compatible = "vnd,gpio";
     282              :  *       #gpio-cells = <2>;
     283              :  *
     284              :  *       n1: node-1 {
     285              :  *               gpio-hog;
     286              :  *               gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>;
     287              :  *               output-high;
     288              :  *       };
     289              :  *
     290              :  *       n2: node-2 {
     291              :  *               gpio-hog;
     292              :  *               gpios = <3 GPIO_ACTIVE_HIGH>;
     293              :  *               output-low;
     294              :  *       };
     295              :  *     };
     296              :  *
     297              :  * Bindings fragment for the vnd,gpio compatible:
     298              :  *
     299              :  *     gpio-cells:
     300              :  *       - pin
     301              :  *       - flags
     302              :  *
     303              :  * Example usage:
     304              :  *
     305              :  *     DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n1), 0) // GPIO_ACTIVE_HIGH
     306              :  *     DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n1), 1) // GPIO_ACTIVE_LOW
     307              :  *     DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n2), 0) // GPIO_ACTIVE_HIGH
     308              :  *
     309              :  * @param node_id node identifier
     310              :  * @param idx logical index into "gpios"
     311              :  * @return the flags cell value at index "idx", or zero if there is none
     312              :  */
     313            1 : #define DT_GPIO_HOG_FLAGS_BY_IDX(node_id, idx) \
     314              :         COND_CODE_1(IS_ENABLED(DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_flags_EXISTS)), \
     315              :                     (DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_flags)), (0))
     316              : 
     317              : /**
     318              :  * @brief Get a DT_DRV_COMPAT instance's GPIO specifier's pin cell value
     319              :  *        at an index
     320              :  * @param inst DT_DRV_COMPAT instance number
     321              :  * @param gpio_pha lowercase-and-underscores GPIO property with
     322              :  *        type "phandle-array"
     323              :  * @param idx logical index into "gpio_pha"
     324              :  * @return the pin cell value at index "idx"
     325              :  * @see DT_GPIO_PIN_BY_IDX()
     326              :  */
     327            1 : #define DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, idx) \
     328              :         DT_GPIO_PIN_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx)
     329              : 
     330              : /**
     331              :  * @brief Equivalent to DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0)
     332              :  * @param inst DT_DRV_COMPAT instance number
     333              :  * @param gpio_pha lowercase-and-underscores GPIO property with
     334              :  *        type "phandle-array"
     335              :  * @return the pin cell value at index 0
     336              :  * @see DT_INST_GPIO_PIN_BY_IDX()
     337              :  */
     338            1 : #define DT_INST_GPIO_PIN(inst, gpio_pha) \
     339              :         DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0)
     340              : 
     341              : /**
     342              :  * @brief Get a DT_DRV_COMPAT instance's GPIO specifier's flags cell
     343              :  *        at an index
     344              :  * @param inst DT_DRV_COMPAT instance number
     345              :  * @param gpio_pha lowercase-and-underscores GPIO property with
     346              :  *        type "phandle-array"
     347              :  * @param idx logical index into "gpio_pha"
     348              :  * @return the flags cell value at index "idx", or zero if there is none
     349              :  * @see DT_GPIO_FLAGS_BY_IDX()
     350              :  */
     351            1 : #define DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, idx) \
     352              :         DT_GPIO_FLAGS_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx)
     353              : 
     354              : /**
     355              :  * @brief Equivalent to DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0)
     356              :  * @param inst DT_DRV_COMPAT instance number
     357              :  * @param gpio_pha lowercase-and-underscores GPIO property with
     358              :  *        type "phandle-array"
     359              :  * @return the flags cell value at index 0, or zero if there is none
     360              :  * @see DT_INST_GPIO_FLAGS_BY_IDX()
     361              :  */
     362            1 : #define DT_INST_GPIO_FLAGS(inst, gpio_pha) \
     363              :         DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0)
     364              : 
     365              : /**
     366              :  * @}
     367              :  */
     368              : 
     369              : #ifdef __cplusplus
     370              : }
     371              : #endif
     372              : 
     373              : #endif  /* ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_ */
        

Generated by: LCOV version 2.0-1