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 * @{ 24 */ 25 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 a node identifier for the gpio controller at index 0 62 * in "gpio_pha" 63 * @see DT_GPIO_CTLR_BY_IDX() 64 */ 65 #define DT_GPIO_CTLR(node_id, gpio_pha) \ 66 DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0) 67 68 /** 69 * @brief Get a label property from a gpio phandle-array property 70 * at an index 71 * 72 * It's an error if the GPIO controller node referenced by the phandle 73 * in node_id's "gpio_pha" property at index "idx" has no label 74 * property. 75 * 76 * Example devicetree fragment: 77 * 78 * gpio1: gpio@... { 79 * label = "GPIO_1"; 80 * }; 81 * 82 * gpio2: gpio@... { 83 * label = "GPIO_2"; 84 * }; 85 * 86 * n: node { 87 * gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, 88 * <&gpio2 30 GPIO_ACTIVE_HIGH>; 89 * }; 90 * 91 * Example usage: 92 * 93 * DT_GPIO_LABEL_BY_IDX(DT_NODELABEL(n), gpios, 1) // "GPIO_2" 94 * 95 * @param node_id node identifier 96 * @param gpio_pha lowercase-and-underscores GPIO property with 97 * type "phandle-array" 98 * @param idx logical index into "gpio_pha" 99 * @return the label property of the node referenced at index "idx" 100 * @see DT_PHANDLE_BY_IDX() 101 */ 102 #define DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, idx) \ 103 DT_PROP(DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx), label) 104 105 /** 106 * @brief Equivalent to DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0) 107 * @param node_id node identifier 108 * @param gpio_pha lowercase-and-underscores GPIO property with 109 * type "phandle-array" 110 * @return the label property of the node referenced at index 0 111 * @see DT_GPIO_LABEL_BY_IDX() 112 */ 113 #define DT_GPIO_LABEL(node_id, gpio_pha) \ 114 DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0) 115 116 /** 117 * @brief Get a GPIO specifier's pin cell at an index 118 * 119 * This macro only works for GPIO specifiers with cells named "pin". 120 * Refer to the node's binding to check if necessary. 121 * 122 * Example devicetree fragment: 123 * 124 * gpio1: gpio@... { 125 * compatible = "vnd,gpio"; 126 * #gpio-cells = <2>; 127 * }; 128 * 129 * gpio2: gpio@... { 130 * compatible = "vnd,gpio"; 131 * #gpio-cells = <2>; 132 * }; 133 * 134 * n: node { 135 * gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, 136 * <&gpio2 30 GPIO_ACTIVE_HIGH>; 137 * }; 138 * 139 * Bindings fragment for the vnd,gpio compatible: 140 * 141 * gpio-cells: 142 * - pin 143 * - flags 144 * 145 * Example usage: 146 * 147 * DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 0) // 10 148 * DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 1) // 30 149 * 150 * @param node_id node identifier 151 * @param gpio_pha lowercase-and-underscores GPIO property with 152 * type "phandle-array" 153 * @param idx logical index into "gpio_pha" 154 * @return the pin cell value at index "idx" 155 * @see DT_PHA_BY_IDX() 156 */ 157 #define DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, idx) \ 158 DT_PHA_BY_IDX(node_id, gpio_pha, idx, pin) 159 160 /** 161 * @brief Equivalent to DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0) 162 * @param node_id node identifier 163 * @param gpio_pha lowercase-and-underscores GPIO property with 164 * type "phandle-array" 165 * @return the pin cell value at index 0 166 * @see DT_GPIO_PIN_BY_IDX() 167 */ 168 #define DT_GPIO_PIN(node_id, gpio_pha) \ 169 DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0) 170 171 /** 172 * @brief Get a GPIO specifier's flags cell at an index 173 * 174 * This macro expects GPIO specifiers with cells named "flags". 175 * If there is no "flags" cell in the GPIO specifier, zero is returned. 176 * Refer to the node's binding to check specifier cell names if necessary. 177 * 178 * Example devicetree fragment: 179 * 180 * gpio1: gpio@... { 181 * compatible = "vnd,gpio"; 182 * #gpio-cells = <2>; 183 * }; 184 * 185 * gpio2: gpio@... { 186 * compatible = "vnd,gpio"; 187 * #gpio-cells = <2>; 188 * }; 189 * 190 * n: node { 191 * gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, 192 * <&gpio2 30 GPIO_ACTIVE_HIGH>; 193 * }; 194 * 195 * Bindings fragment for the vnd,gpio compatible: 196 * 197 * gpio-cells: 198 * - pin 199 * - flags 200 * 201 * Example usage: 202 * 203 * DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 0) // GPIO_ACTIVE_LOW 204 * DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 1) // GPIO_ACTIVE_HIGH 205 * 206 * @param node_id node identifier 207 * @param gpio_pha lowercase-and-underscores GPIO property with 208 * type "phandle-array" 209 * @param idx logical index into "gpio_pha" 210 * @return the flags cell value at index "idx", or zero if there is none 211 * @see DT_PHA_BY_IDX() 212 */ 213 #define DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, idx) \ 214 DT_PHA_BY_IDX_OR(node_id, gpio_pha, idx, flags, 0) 215 216 /** 217 * @brief Equivalent to DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0) 218 * @param node_id node identifier 219 * @param gpio_pha lowercase-and-underscores GPIO property with 220 * type "phandle-array" 221 * @return the flags cell value at index 0, or zero if there is none 222 * @see DT_GPIO_FLAGS_BY_IDX() 223 */ 224 #define DT_GPIO_FLAGS(node_id, gpio_pha) \ 225 DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0) 226 227 /** 228 * @brief Get a label property from a DT_DRV_COMPAT instance's GPIO 229 * property at an index 230 * @param inst DT_DRV_COMPAT instance number 231 * @param gpio_pha lowercase-and-underscores GPIO property with 232 * type "phandle-array" 233 * @param idx logical index into "gpio_pha" 234 * @return the label property of the node referenced at index "idx" 235 */ 236 #define DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, idx) \ 237 DT_GPIO_LABEL_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx) 238 239 /** 240 * @brief Equivalent to DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0) 241 * @param inst DT_DRV_COMPAT instance number 242 * @param gpio_pha lowercase-and-underscores GPIO property with 243 * type "phandle-array" 244 * @return the label property of the node referenced at index 0 245 */ 246 #define DT_INST_GPIO_LABEL(inst, gpio_pha) \ 247 DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0) 248 249 /** 250 * @brief Get a DT_DRV_COMPAT instance's GPIO specifier's pin cell value 251 * at an index 252 * @param inst DT_DRV_COMPAT instance number 253 * @param gpio_pha lowercase-and-underscores GPIO property with 254 * type "phandle-array" 255 * @param idx logical index into "gpio_pha" 256 * @return the pin cell value at index "idx" 257 * @see DT_GPIO_PIN_BY_IDX() 258 */ 259 #define DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, idx) \ 260 DT_GPIO_PIN_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx) 261 262 /** 263 * @brief Equivalent to DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0) 264 * @param inst DT_DRV_COMPAT instance number 265 * @param gpio_pha lowercase-and-underscores GPIO property with 266 * type "phandle-array" 267 * @return the pin cell value at index 0 268 * @see DT_INST_GPIO_PIN_BY_IDX() 269 */ 270 #define DT_INST_GPIO_PIN(inst, gpio_pha) \ 271 DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0) 272 273 /** 274 * @brief Get a DT_DRV_COMPAT instance's GPIO specifier's flags cell 275 * at an index 276 * @param inst DT_DRV_COMPAT instance number 277 * @param gpio_pha lowercase-and-underscores GPIO property with 278 * type "phandle-array" 279 * @param idx logical index into "gpio_pha" 280 * @return the flags cell value at index "idx", or zero if there is none 281 * @see DT_GPIO_FLAGS_BY_IDX() 282 */ 283 #define DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, idx) \ 284 DT_GPIO_FLAGS_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx) 285 286 /** 287 * @brief Equivalent to DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0) 288 * @param inst DT_DRV_COMPAT instance number 289 * @param gpio_pha lowercase-and-underscores GPIO property with 290 * type "phandle-array" 291 * @return the flags cell value at index 0, or zero if there is none 292 * @see DT_INST_GPIO_FLAGS_BY_IDX() 293 */ 294 #define DT_INST_GPIO_FLAGS(inst, gpio_pha) \ 295 DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0) 296 297 /** 298 * @} 299 */ 300 301 #ifdef __cplusplus 302 } 303 #endif 304 305 #endif /* ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_ */ 306
