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