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 * @deprecated If used to obtain a device instance with device_get_binding, 70 * consider using @c DEVICE_DT_GET(DT_GPIO_CTLR_BY_IDX(node, gpio_pha, idx)). 71 * 72 * @brief Get a label property from a gpio phandle-array property 73 * at an index 74 * 75 * It's an error if the GPIO controller node referenced by the phandle 76 * in node_id's "gpio_pha" property at index "idx" has no label 77 * property. 78 * 79 * Example devicetree fragment: 80 * 81 * gpio1: gpio@... { 82 * label = "GPIO_1"; 83 * }; 84 * 85 * gpio2: gpio@... { 86 * label = "GPIO_2"; 87 * }; 88 * 89 * n: node { 90 * gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, 91 * <&gpio2 30 GPIO_ACTIVE_HIGH>; 92 * }; 93 * 94 * Example usage: 95 * 96 * DT_GPIO_LABEL_BY_IDX(DT_NODELABEL(n), gpios, 1) // "GPIO_2" 97 * 98 * @param node_id node identifier 99 * @param gpio_pha lowercase-and-underscores GPIO property with 100 * type "phandle-array" 101 * @param idx logical index into "gpio_pha" 102 * @return the label property of the node referenced at index "idx" 103 * @see DT_PHANDLE_BY_IDX() 104 */ 105 #define DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, idx) \ 106 DT_PROP(DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx), label) __DEPRECATED_MACRO 107 108 /** 109 * @deprecated If used to obtain a device instance with device_get_binding, 110 * consider using @c DEVICE_DT_GET(DT_GPIO_CTLR(node, gpio_pha)). 111 * 112 * @brief Equivalent to DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0) 113 * @param node_id node identifier 114 * @param gpio_pha lowercase-and-underscores GPIO property with 115 * type "phandle-array" 116 * @return the label property of the node referenced at index 0 117 * @see DT_GPIO_LABEL_BY_IDX() 118 */ 119 #define DT_GPIO_LABEL(node_id, gpio_pha) \ 120 DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0) __DEPRECATED_MACRO 121 122 /** 123 * @brief Get a GPIO specifier's pin cell at an index 124 * 125 * This macro only works for GPIO specifiers with cells named "pin". 126 * Refer to the node's binding to check if necessary. 127 * 128 * Example devicetree fragment: 129 * 130 * gpio1: gpio@... { 131 * compatible = "vnd,gpio"; 132 * #gpio-cells = <2>; 133 * }; 134 * 135 * gpio2: gpio@... { 136 * compatible = "vnd,gpio"; 137 * #gpio-cells = <2>; 138 * }; 139 * 140 * n: node { 141 * gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, 142 * <&gpio2 30 GPIO_ACTIVE_HIGH>; 143 * }; 144 * 145 * Bindings fragment for the vnd,gpio compatible: 146 * 147 * gpio-cells: 148 * - pin 149 * - flags 150 * 151 * Example usage: 152 * 153 * DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 0) // 10 154 * DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 1) // 30 155 * 156 * @param node_id node identifier 157 * @param gpio_pha lowercase-and-underscores GPIO property with 158 * type "phandle-array" 159 * @param idx logical index into "gpio_pha" 160 * @return the pin cell value at index "idx" 161 * @see DT_PHA_BY_IDX() 162 */ 163 #define DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, idx) \ 164 DT_PHA_BY_IDX(node_id, gpio_pha, idx, pin) 165 166 /** 167 * @brief Equivalent to DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0) 168 * @param node_id node identifier 169 * @param gpio_pha lowercase-and-underscores GPIO property with 170 * type "phandle-array" 171 * @return the pin cell value at index 0 172 * @see DT_GPIO_PIN_BY_IDX() 173 */ 174 #define DT_GPIO_PIN(node_id, gpio_pha) \ 175 DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0) 176 177 /** 178 * @brief Get a GPIO specifier's flags cell at an index 179 * 180 * This macro expects GPIO specifiers with cells named "flags". 181 * If there is no "flags" cell in the GPIO specifier, zero is returned. 182 * Refer to the node's binding to check specifier cell names if necessary. 183 * 184 * Example devicetree fragment: 185 * 186 * gpio1: gpio@... { 187 * compatible = "vnd,gpio"; 188 * #gpio-cells = <2>; 189 * }; 190 * 191 * gpio2: gpio@... { 192 * compatible = "vnd,gpio"; 193 * #gpio-cells = <2>; 194 * }; 195 * 196 * n: node { 197 * gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, 198 * <&gpio2 30 GPIO_ACTIVE_HIGH>; 199 * }; 200 * 201 * Bindings fragment for the vnd,gpio compatible: 202 * 203 * gpio-cells: 204 * - pin 205 * - flags 206 * 207 * Example usage: 208 * 209 * DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 0) // GPIO_ACTIVE_LOW 210 * DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 1) // GPIO_ACTIVE_HIGH 211 * 212 * @param node_id node identifier 213 * @param gpio_pha lowercase-and-underscores GPIO property with 214 * type "phandle-array" 215 * @param idx logical index into "gpio_pha" 216 * @return the flags cell value at index "idx", or zero if there is none 217 * @see DT_PHA_BY_IDX() 218 */ 219 #define DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, idx) \ 220 DT_PHA_BY_IDX_OR(node_id, gpio_pha, idx, flags, 0) 221 222 /** 223 * @brief Equivalent to DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0) 224 * @param node_id node identifier 225 * @param gpio_pha lowercase-and-underscores GPIO property with 226 * type "phandle-array" 227 * @return the flags cell value at index 0, or zero if there is none 228 * @see DT_GPIO_FLAGS_BY_IDX() 229 */ 230 #define DT_GPIO_FLAGS(node_id, gpio_pha) \ 231 DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0) 232 233 /** 234 * @brief Get the number of GPIO hogs in a node 235 * 236 * This expands to the number of hogged GPIOs, or zero if there are none. 237 * 238 * Example devicetree fragment: 239 * 240 * gpio1: gpio@... { 241 * compatible = "vnd,gpio"; 242 * #gpio-cells = <2>; 243 * 244 * n1: node-1 { 245 * gpio-hog; 246 * gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>; 247 * output-high; 248 * }; 249 * 250 * n2: node-2 { 251 * gpio-hog; 252 * gpios = <3 GPIO_ACTIVE_HIGH>; 253 * output-low; 254 * }; 255 * }; 256 * 257 * Bindings fragment for the vnd,gpio compatible: 258 * 259 * gpio-cells: 260 * - pin 261 * - flags 262 * 263 * Example usage: 264 * 265 * DT_NUM_GPIO_HOGS(DT_NODELABEL(n1)) // 2 266 * DT_NUM_GPIO_HOGS(DT_NODELABEL(n2)) // 1 267 * 268 * @param node_id node identifier; may or may not be a GPIO hog node. 269 * @return number of hogged GPIOs in the node 270 */ 271 #define DT_NUM_GPIO_HOGS(node_id) \ 272 COND_CODE_1(IS_ENABLED(DT_CAT(node_id, _GPIO_HOGS_EXISTS)), \ 273 (DT_CAT(node_id, _GPIO_HOGS_NUM)), (0)) 274 275 /** 276 * @brief Get a GPIO hog specifier's pin cell at an index 277 * 278 * This macro only works for GPIO specifiers with cells named "pin". 279 * Refer to the node's binding to check if necessary. 280 * 281 * Example devicetree fragment: 282 * 283 * gpio1: gpio@... { 284 * compatible = "vnd,gpio"; 285 * #gpio-cells = <2>; 286 * 287 * n1: node-1 { 288 * gpio-hog; 289 * gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>; 290 * output-high; 291 * }; 292 * 293 * n2: node-2 { 294 * gpio-hog; 295 * gpios = <3 GPIO_ACTIVE_HIGH>; 296 * output-low; 297 * }; 298 * }; 299 * 300 * Bindings fragment for the vnd,gpio compatible: 301 * 302 * gpio-cells: 303 * - pin 304 * - flags 305 * 306 * Example usage: 307 * 308 * DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n1), 0) // 0 309 * DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n1), 1) // 1 310 * DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n2), 0) // 3 311 * 312 * @param node_id node identifier 313 * @param idx logical index into "gpios" 314 * @return the pin cell value at index "idx" 315 */ 316 #define DT_GPIO_HOG_PIN_BY_IDX(node_id, idx) \ 317 DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_pin) 318 319 /** 320 * @brief Get a GPIO hog specifier's flags cell at an index 321 * 322 * This macro expects GPIO specifiers with cells named "flags". 323 * If there is no "flags" cell in the GPIO specifier, zero is returned. 324 * Refer to the node's binding to check specifier cell names if necessary. 325 * 326 * Example devicetree fragment: 327 * 328 * gpio1: gpio@... { 329 * compatible = "vnd,gpio"; 330 * #gpio-cells = <2>; 331 * 332 * n1: node-1 { 333 * gpio-hog; 334 * gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>; 335 * output-high; 336 * }; 337 * 338 * n2: node-2 { 339 * gpio-hog; 340 * gpios = <3 GPIO_ACTIVE_HIGH>; 341 * output-low; 342 * }; 343 * }; 344 * 345 * Bindings fragment for the vnd,gpio compatible: 346 * 347 * gpio-cells: 348 * - pin 349 * - flags 350 * 351 * Example usage: 352 * 353 * DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n1), 0) // GPIO_ACTIVE_HIGH 354 * DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n1), 1) // GPIO_ACTIVE_LOW 355 * DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n2), 0) // GPIO_ACTIVE_HIGH 356 * 357 * @param node_id node identifier 358 * @param idx logical index into "gpios" 359 * @return the flags cell value at index "idx", or zero if there is none 360 */ 361 #define DT_GPIO_HOG_FLAGS_BY_IDX(node_id, idx) \ 362 COND_CODE_1(IS_ENABLED(DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_flags_EXISTS)), \ 363 (DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_flags)), (0)) 364 365 /** 366 * @deprecated If used to obtain a device instance with device_get_binding, 367 * consider using @c DEVICE_DT_GET(DT_INST_GPIO_CTLR_BY_IDX(node, gpio_pha, idx)). 368 * 369 * @brief Get a label property from a DT_DRV_COMPAT instance's GPIO 370 * property at an index 371 * @param inst DT_DRV_COMPAT instance number 372 * @param gpio_pha lowercase-and-underscores GPIO property with 373 * type "phandle-array" 374 * @param idx logical index into "gpio_pha" 375 * @return the label property of the node referenced at index "idx" 376 */ 377 #define DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, idx) \ 378 DT_GPIO_LABEL_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx) __DEPRECATED_MACRO 379 380 /** 381 * @deprecated If used to obtain a device instance with device_get_binding, 382 * consider using @c DEVICE_DT_GET(DT_INST_GPIO_CTLR(node, gpio_pha)). 383 * 384 * @brief Equivalent to DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0) 385 * @param inst DT_DRV_COMPAT instance number 386 * @param gpio_pha lowercase-and-underscores GPIO property with 387 * type "phandle-array" 388 * @return the label property of the node referenced at index 0 389 */ 390 #define DT_INST_GPIO_LABEL(inst, gpio_pha) \ 391 DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0) __DEPRECATED_MACRO 392 393 /** 394 * @brief Get a DT_DRV_COMPAT instance's GPIO specifier's pin cell value 395 * at an index 396 * @param inst DT_DRV_COMPAT instance number 397 * @param gpio_pha lowercase-and-underscores GPIO property with 398 * type "phandle-array" 399 * @param idx logical index into "gpio_pha" 400 * @return the pin cell value at index "idx" 401 * @see DT_GPIO_PIN_BY_IDX() 402 */ 403 #define DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, idx) \ 404 DT_GPIO_PIN_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx) 405 406 /** 407 * @brief Equivalent to DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0) 408 * @param inst DT_DRV_COMPAT instance number 409 * @param gpio_pha lowercase-and-underscores GPIO property with 410 * type "phandle-array" 411 * @return the pin cell value at index 0 412 * @see DT_INST_GPIO_PIN_BY_IDX() 413 */ 414 #define DT_INST_GPIO_PIN(inst, gpio_pha) \ 415 DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0) 416 417 /** 418 * @brief Get a DT_DRV_COMPAT instance's GPIO specifier's flags cell 419 * at an index 420 * @param inst DT_DRV_COMPAT instance number 421 * @param gpio_pha lowercase-and-underscores GPIO property with 422 * type "phandle-array" 423 * @param idx logical index into "gpio_pha" 424 * @return the flags cell value at index "idx", or zero if there is none 425 * @see DT_GPIO_FLAGS_BY_IDX() 426 */ 427 #define DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, idx) \ 428 DT_GPIO_FLAGS_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx) 429 430 /** 431 * @brief Equivalent to DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0) 432 * @param inst DT_DRV_COMPAT instance number 433 * @param gpio_pha lowercase-and-underscores GPIO property with 434 * type "phandle-array" 435 * @return the flags cell value at index 0, or zero if there is none 436 * @see DT_INST_GPIO_FLAGS_BY_IDX() 437 */ 438 #define DT_INST_GPIO_FLAGS(inst, gpio_pha) \ 439 DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0) 440 441 /** 442 * @} 443 */ 444 445 #ifdef __cplusplus 446 } 447 #endif 448 449 #endif /* ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_ */ 450
