1 // SPDX-License-Identifier: GPL-2.0 2 /* 3 * OF helpers for the GPIO API 4 * 5 * Copyright (c) 2007-2008 MontaVista Software, Inc. 6 * 7 * Author: Anton Vorontsov <avorontsov@ru.mvista.com> 8 */ 9 10 #include <linux/device.h> 11 #include <linux/err.h> 12 #include <linux/errno.h> 13 #include <linux/module.h> 14 #include <linux/io.h> 15 #include <linux/gpio/consumer.h> 16 #include <linux/of.h> 17 #include <linux/of_address.h> 18 #include <linux/of_gpio.h> 19 #include <linux/pinctrl/pinctrl.h> 20 #include <linux/slab.h> 21 #include <linux/gpio/machine.h> 22 23 #include "gpiolib.h" 24 25 static int of_gpiochip_match_node_and_xlate(struct gpio_chip *chip, void *data) 26 { 27 struct of_phandle_args *gpiospec = data; 28 29 return chip->gpiodev->dev.of_node == gpiospec->np && 30 chip->of_xlate(chip, gpiospec, NULL) >= 0; 31 } 32 33 static struct gpio_chip *of_find_gpiochip_by_xlate( 34 struct of_phandle_args *gpiospec) 35 { 36 return gpiochip_find(gpiospec, of_gpiochip_match_node_and_xlate); 37 } 38 39 static struct gpio_desc *of_xlate_and_get_gpiod_flags(struct gpio_chip *chip, 40 struct of_phandle_args *gpiospec, 41 enum of_gpio_flags *flags) 42 { 43 int ret; 44 45 if (chip->of_gpio_n_cells != gpiospec->args_count) 46 return ERR_PTR(-EINVAL); 47 48 ret = chip->of_xlate(chip, gpiospec, flags); 49 if (ret < 0) 50 return ERR_PTR(ret); 51 52 return gpiochip_get_desc(chip, ret); 53 } 54 55 static void of_gpio_flags_quirks(struct device_node *np, 56 enum of_gpio_flags *flags, 57 int index) 58 { 59 /* 60 * Some GPIO fixed regulator quirks. 61 * Note that active low is the default. 62 */ 63 if (IS_ENABLED(CONFIG_REGULATOR) && 64 (of_device_is_compatible(np, "regulator-fixed") || 65 of_device_is_compatible(np, "reg-fixed-voltage") || 66 of_device_is_compatible(np, "regulator-gpio"))) { 67 /* 68 * The regulator GPIO handles are specified such that the 69 * presence or absence of "enable-active-high" solely controls 70 * the polarity of the GPIO line. Any phandle flags must 71 * be actively ignored. 72 */ 73 if (*flags & OF_GPIO_ACTIVE_LOW) { 74 pr_warn("%s GPIO handle specifies active low - ignored\n", 75 of_node_full_name(np)); 76 *flags &= ~OF_GPIO_ACTIVE_LOW; 77 } 78 if (!of_property_read_bool(np, "enable-active-high")) 79 *flags |= OF_GPIO_ACTIVE_LOW; 80 } 81 /* 82 * Legacy open drain handling for fixed voltage regulators. 83 */ 84 if (IS_ENABLED(CONFIG_REGULATOR) && 85 of_device_is_compatible(np, "reg-fixed-voltage") && 86 of_property_read_bool(np, "gpio-open-drain")) { 87 *flags |= (OF_GPIO_SINGLE_ENDED | OF_GPIO_OPEN_DRAIN); 88 pr_info("%s uses legacy open drain flag - update the DTS if you can\n", 89 of_node_full_name(np)); 90 } 91 92 /* 93 * Legacy handling of SPI active high chip select. If we have a 94 * property named "cs-gpios" we need to inspect the child node 95 * to determine if the flags should have inverted semantics. 96 */ 97 if (IS_ENABLED(CONFIG_SPI_MASTER) && 98 of_property_read_bool(np, "cs-gpios")) { 99 struct device_node *child; 100 u32 cs; 101 int ret; 102 103 for_each_child_of_node(np, child) { 104 ret = of_property_read_u32(child, "reg", &cs); 105 if (!ret) 106 continue; 107 if (cs == index) { 108 /* 109 * SPI children have active low chip selects 110 * by default. This can be specified negatively 111 * by just omitting "spi-cs-high" in the 112 * device node, or actively by tagging on 113 * GPIO_ACTIVE_LOW as flag in the device 114 * tree. If the line is simultaneously 115 * tagged as active low in the device tree 116 * and has the "spi-cs-high" set, we get a 117 * conflict and the "spi-cs-high" flag will 118 * take precedence. 119 */ 120 if (of_property_read_bool(np, "spi-cs-high")) { 121 if (*flags & OF_GPIO_ACTIVE_LOW) { 122 pr_warn("%s GPIO handle specifies active low - ignored\n", 123 of_node_full_name(np)); 124 *flags &= ~OF_GPIO_ACTIVE_LOW; 125 } 126 } else { 127 if (!(*flags & OF_GPIO_ACTIVE_LOW)) 128 pr_info("%s enforce active low on chipselect handle\n", 129 of_node_full_name(np)); 130 *flags |= OF_GPIO_ACTIVE_LOW; 131 } 132 break; 133 } 134 } 135 } 136 } 137 138 /** 139 * of_get_named_gpiod_flags() - Get a GPIO descriptor and flags for GPIO API 140 * @np: device node to get GPIO from 141 * @propname: property name containing gpio specifier(s) 142 * @index: index of the GPIO 143 * @flags: a flags pointer to fill in 144 * 145 * Returns GPIO descriptor to use with Linux GPIO API, or one of the errno 146 * value on the error condition. If @flags is not NULL the function also fills 147 * in flags for the GPIO. 148 */ 149 struct gpio_desc *of_get_named_gpiod_flags(struct device_node *np, 150 const char *propname, int index, enum of_gpio_flags *flags) 151 { 152 struct of_phandle_args gpiospec; 153 struct gpio_chip *chip; 154 struct gpio_desc *desc; 155 int ret; 156 157 ret = of_parse_phandle_with_args_map(np, propname, "gpio", index, 158 &gpiospec); 159 if (ret) { 160 pr_debug("%s: can't parse '%s' property of node '%pOF[%d]'\n", 161 __func__, propname, np, index); 162 return ERR_PTR(ret); 163 } 164 165 chip = of_find_gpiochip_by_xlate(&gpiospec); 166 if (!chip) { 167 desc = ERR_PTR(-EPROBE_DEFER); 168 goto out; 169 } 170 171 desc = of_xlate_and_get_gpiod_flags(chip, &gpiospec, flags); 172 if (IS_ERR(desc)) 173 goto out; 174 175 if (flags) 176 of_gpio_flags_quirks(np, flags, index); 177 178 pr_debug("%s: parsed '%s' property of node '%pOF[%d]' - status (%d)\n", 179 __func__, propname, np, index, 180 PTR_ERR_OR_ZERO(desc)); 181 182 out: 183 of_node_put(gpiospec.np); 184 185 return desc; 186 } 187 188 int of_get_named_gpio_flags(struct device_node *np, const char *list_name, 189 int index, enum of_gpio_flags *flags) 190 { 191 struct gpio_desc *desc; 192 193 desc = of_get_named_gpiod_flags(np, list_name, index, flags); 194 195 if (IS_ERR(desc)) 196 return PTR_ERR(desc); 197 else 198 return desc_to_gpio(desc); 199 } 200 EXPORT_SYMBOL(of_get_named_gpio_flags); 201 202 /* 203 * The SPI GPIO bindings happened before we managed to establish that GPIO 204 * properties should be named "foo-gpios" so we have this special kludge for 205 * them. 206 */ 207 static struct gpio_desc *of_find_spi_gpio(struct device *dev, const char *con_id, 208 enum of_gpio_flags *of_flags) 209 { 210 char prop_name[32]; /* 32 is max size of property name */ 211 struct device_node *np = dev->of_node; 212 struct gpio_desc *desc; 213 214 /* 215 * Hopefully the compiler stubs the rest of the function if this 216 * is false. 217 */ 218 if (!IS_ENABLED(CONFIG_SPI_MASTER)) 219 return ERR_PTR(-ENOENT); 220 221 /* Allow this specifically for "spi-gpio" devices */ 222 if (!of_device_is_compatible(np, "spi-gpio") || !con_id) 223 return ERR_PTR(-ENOENT); 224 225 /* Will be "gpio-sck", "gpio-mosi" or "gpio-miso" */ 226 snprintf(prop_name, sizeof(prop_name), "%s-%s", "gpio", con_id); 227 228 desc = of_get_named_gpiod_flags(np, prop_name, 0, of_flags); 229 return desc; 230 } 231 232 /* 233 * Some regulator bindings happened before we managed to establish that GPIO 234 * properties should be named "foo-gpios" so we have this special kludge for 235 * them. 236 */ 237 static struct gpio_desc *of_find_regulator_gpio(struct device *dev, const char *con_id, 238 enum of_gpio_flags *of_flags) 239 { 240 /* These are the connection IDs we accept as legacy GPIO phandles */ 241 const char *whitelist[] = { 242 "wlf,ldoena", /* Arizona */ 243 "wlf,ldo1ena", /* WM8994 */ 244 "wlf,ldo2ena", /* WM8994 */ 245 }; 246 struct device_node *np = dev->of_node; 247 struct gpio_desc *desc; 248 int i; 249 250 if (!IS_ENABLED(CONFIG_REGULATOR)) 251 return ERR_PTR(-ENOENT); 252 253 if (!con_id) 254 return ERR_PTR(-ENOENT); 255 256 i = match_string(whitelist, ARRAY_SIZE(whitelist), con_id); 257 if (i < 0) 258 return ERR_PTR(-ENOENT); 259 260 desc = of_get_named_gpiod_flags(np, con_id, 0, of_flags); 261 return desc; 262 } 263 264 struct gpio_desc *of_find_gpio(struct device *dev, const char *con_id, 265 unsigned int idx, 266 enum gpio_lookup_flags *flags) 267 { 268 char prop_name[32]; /* 32 is max size of property name */ 269 enum of_gpio_flags of_flags; 270 struct gpio_desc *desc; 271 unsigned int i; 272 273 /* Try GPIO property "foo-gpios" and "foo-gpio" */ 274 for (i = 0; i < ARRAY_SIZE(gpio_suffixes); i++) { 275 if (con_id) 276 snprintf(prop_name, sizeof(prop_name), "%s-%s", con_id, 277 gpio_suffixes[i]); 278 else 279 snprintf(prop_name, sizeof(prop_name), "%s", 280 gpio_suffixes[i]); 281 282 desc = of_get_named_gpiod_flags(dev->of_node, prop_name, idx, 283 &of_flags); 284 /* 285 * -EPROBE_DEFER in our case means that we found a 286 * valid GPIO property, but no controller has been 287 * registered so far. 288 * 289 * This means we don't need to look any further for 290 * alternate name conventions, and we should really 291 * preserve the return code for our user to be able to 292 * retry probing later. 293 */ 294 if (IS_ERR(desc) && PTR_ERR(desc) == -EPROBE_DEFER) 295 return desc; 296 297 if (!IS_ERR(desc) || (PTR_ERR(desc) != -ENOENT)) 298 break; 299 } 300 301 /* Special handling for SPI GPIOs if used */ 302 if (IS_ERR(desc)) 303 desc = of_find_spi_gpio(dev, con_id, &of_flags); 304 305 /* Special handling for regulator GPIOs if used */ 306 if (IS_ERR(desc) && PTR_ERR(desc) != -EPROBE_DEFER) 307 desc = of_find_regulator_gpio(dev, con_id, &of_flags); 308 309 if (IS_ERR(desc)) 310 return desc; 311 312 if (of_flags & OF_GPIO_ACTIVE_LOW) 313 *flags |= GPIO_ACTIVE_LOW; 314 315 if (of_flags & OF_GPIO_SINGLE_ENDED) { 316 if (of_flags & OF_GPIO_OPEN_DRAIN) 317 *flags |= GPIO_OPEN_DRAIN; 318 else 319 *flags |= GPIO_OPEN_SOURCE; 320 } 321 322 if (of_flags & OF_GPIO_TRANSITORY) 323 *flags |= GPIO_TRANSITORY; 324 325 return desc; 326 } 327 328 /** 329 * of_parse_own_gpio() - Get a GPIO hog descriptor, names and flags for GPIO API 330 * @np: device node to get GPIO from 331 * @chip: GPIO chip whose hog is parsed 332 * @idx: Index of the GPIO to parse 333 * @name: GPIO line name 334 * @lflags: gpio_lookup_flags - returned from of_find_gpio() or 335 * of_parse_own_gpio() 336 * @dflags: gpiod_flags - optional GPIO initialization flags 337 * 338 * Returns GPIO descriptor to use with Linux GPIO API, or one of the errno 339 * value on the error condition. 340 */ 341 static struct gpio_desc *of_parse_own_gpio(struct device_node *np, 342 struct gpio_chip *chip, 343 unsigned int idx, const char **name, 344 enum gpio_lookup_flags *lflags, 345 enum gpiod_flags *dflags) 346 { 347 struct device_node *chip_np; 348 enum of_gpio_flags xlate_flags; 349 struct of_phandle_args gpiospec; 350 struct gpio_desc *desc; 351 unsigned int i; 352 u32 tmp; 353 int ret; 354 355 chip_np = chip->of_node; 356 if (!chip_np) 357 return ERR_PTR(-EINVAL); 358 359 xlate_flags = 0; 360 *lflags = 0; 361 *dflags = 0; 362 363 ret = of_property_read_u32(chip_np, "#gpio-cells", &tmp); 364 if (ret) 365 return ERR_PTR(ret); 366 367 gpiospec.np = chip_np; 368 gpiospec.args_count = tmp; 369 370 for (i = 0; i < tmp; i++) { 371 ret = of_property_read_u32_index(np, "gpios", idx * tmp + i, 372 &gpiospec.args[i]); 373 if (ret) 374 return ERR_PTR(ret); 375 } 376 377 desc = of_xlate_and_get_gpiod_flags(chip, &gpiospec, &xlate_flags); 378 if (IS_ERR(desc)) 379 return desc; 380 381 if (xlate_flags & OF_GPIO_ACTIVE_LOW) 382 *lflags |= GPIO_ACTIVE_LOW; 383 if (xlate_flags & OF_GPIO_TRANSITORY) 384 *lflags |= GPIO_TRANSITORY; 385 386 if (of_property_read_bool(np, "input")) 387 *dflags |= GPIOD_IN; 388 else if (of_property_read_bool(np, "output-low")) 389 *dflags |= GPIOD_OUT_LOW; 390 else if (of_property_read_bool(np, "output-high")) 391 *dflags |= GPIOD_OUT_HIGH; 392 else { 393 pr_warn("GPIO line %d (%pOFn): no hogging state specified, bailing out\n", 394 desc_to_gpio(desc), np); 395 return ERR_PTR(-EINVAL); 396 } 397 398 if (name && of_property_read_string(np, "line-name", name)) 399 *name = np->name; 400 401 return desc; 402 } 403 404 /** 405 * of_gpiochip_scan_gpios - Scan gpio-controller for gpio definitions 406 * @chip: gpio chip to act on 407 * 408 * This is only used by of_gpiochip_add to request/set GPIO initial 409 * configuration. 410 * It returns error if it fails otherwise 0 on success. 411 */ 412 static int of_gpiochip_scan_gpios(struct gpio_chip *chip) 413 { 414 struct gpio_desc *desc = NULL; 415 struct device_node *np; 416 const char *name; 417 enum gpio_lookup_flags lflags; 418 enum gpiod_flags dflags; 419 unsigned int i; 420 int ret; 421 422 for_each_available_child_of_node(chip->of_node, np) { 423 if (!of_property_read_bool(np, "gpio-hog")) 424 continue; 425 426 for (i = 0;; i++) { 427 desc = of_parse_own_gpio(np, chip, i, &name, &lflags, 428 &dflags); 429 if (IS_ERR(desc)) 430 break; 431 432 ret = gpiod_hog(desc, name, lflags, dflags); 433 if (ret < 0) { 434 of_node_put(np); 435 return ret; 436 } 437 } 438 } 439 440 return 0; 441 } 442 443 /** 444 * of_gpio_simple_xlate - translate gpiospec to the GPIO number and flags 445 * @gc: pointer to the gpio_chip structure 446 * @gpiospec: GPIO specifier as found in the device tree 447 * @flags: a flags pointer to fill in 448 * 449 * This is simple translation function, suitable for the most 1:1 mapped 450 * GPIO chips. This function performs only one sanity check: whether GPIO 451 * is less than ngpios (that is specified in the gpio_chip). 452 */ 453 int of_gpio_simple_xlate(struct gpio_chip *gc, 454 const struct of_phandle_args *gpiospec, u32 *flags) 455 { 456 /* 457 * We're discouraging gpio_cells < 2, since that way you'll have to 458 * write your own xlate function (that will have to retrieve the GPIO 459 * number and the flags from a single gpio cell -- this is possible, 460 * but not recommended). 461 */ 462 if (gc->of_gpio_n_cells < 2) { 463 WARN_ON(1); 464 return -EINVAL; 465 } 466 467 if (WARN_ON(gpiospec->args_count < gc->of_gpio_n_cells)) 468 return -EINVAL; 469 470 if (gpiospec->args[0] >= gc->ngpio) 471 return -EINVAL; 472 473 if (flags) 474 *flags = gpiospec->args[1]; 475 476 return gpiospec->args[0]; 477 } 478 EXPORT_SYMBOL(of_gpio_simple_xlate); 479 480 /** 481 * of_mm_gpiochip_add_data - Add memory mapped GPIO chip (bank) 482 * @np: device node of the GPIO chip 483 * @mm_gc: pointer to the of_mm_gpio_chip allocated structure 484 * @data: driver data to store in the struct gpio_chip 485 * 486 * To use this function you should allocate and fill mm_gc with: 487 * 488 * 1) In the gpio_chip structure: 489 * - all the callbacks 490 * - of_gpio_n_cells 491 * - of_xlate callback (optional) 492 * 493 * 3) In the of_mm_gpio_chip structure: 494 * - save_regs callback (optional) 495 * 496 * If succeeded, this function will map bank's memory and will 497 * do all necessary work for you. Then you'll able to use .regs 498 * to manage GPIOs from the callbacks. 499 */ 500 int of_mm_gpiochip_add_data(struct device_node *np, 501 struct of_mm_gpio_chip *mm_gc, 502 void *data) 503 { 504 int ret = -ENOMEM; 505 struct gpio_chip *gc = &mm_gc->gc; 506 507 gc->label = kasprintf(GFP_KERNEL, "%pOF", np); 508 if (!gc->label) 509 goto err0; 510 511 mm_gc->regs = of_iomap(np, 0); 512 if (!mm_gc->regs) 513 goto err1; 514 515 gc->base = -1; 516 517 if (mm_gc->save_regs) 518 mm_gc->save_regs(mm_gc); 519 520 mm_gc->gc.of_node = np; 521 522 ret = gpiochip_add_data(gc, data); 523 if (ret) 524 goto err2; 525 526 return 0; 527 err2: 528 iounmap(mm_gc->regs); 529 err1: 530 kfree(gc->label); 531 err0: 532 pr_err("%pOF: GPIO chip registration failed with status %d\n", np, ret); 533 return ret; 534 } 535 EXPORT_SYMBOL(of_mm_gpiochip_add_data); 536 537 /** 538 * of_mm_gpiochip_remove - Remove memory mapped GPIO chip (bank) 539 * @mm_gc: pointer to the of_mm_gpio_chip allocated structure 540 */ 541 void of_mm_gpiochip_remove(struct of_mm_gpio_chip *mm_gc) 542 { 543 struct gpio_chip *gc = &mm_gc->gc; 544 545 if (!mm_gc) 546 return; 547 548 gpiochip_remove(gc); 549 iounmap(mm_gc->regs); 550 kfree(gc->label); 551 } 552 EXPORT_SYMBOL(of_mm_gpiochip_remove); 553 554 static void of_gpiochip_init_valid_mask(struct gpio_chip *chip) 555 { 556 int len, i; 557 u32 start, count; 558 struct device_node *np = chip->of_node; 559 560 len = of_property_count_u32_elems(np, "gpio-reserved-ranges"); 561 if (len < 0 || len % 2 != 0) 562 return; 563 564 for (i = 0; i < len; i += 2) { 565 of_property_read_u32_index(np, "gpio-reserved-ranges", 566 i, &start); 567 of_property_read_u32_index(np, "gpio-reserved-ranges", 568 i + 1, &count); 569 if (start >= chip->ngpio || start + count >= chip->ngpio) 570 continue; 571 572 bitmap_clear(chip->valid_mask, start, count); 573 } 574 }; 575 576 #ifdef CONFIG_PINCTRL 577 static int of_gpiochip_add_pin_range(struct gpio_chip *chip) 578 { 579 struct device_node *np = chip->of_node; 580 struct of_phandle_args pinspec; 581 struct pinctrl_dev *pctldev; 582 int index = 0, ret; 583 const char *name; 584 static const char group_names_propname[] = "gpio-ranges-group-names"; 585 struct property *group_names; 586 587 if (!np) 588 return 0; 589 590 group_names = of_find_property(np, group_names_propname, NULL); 591 592 for (;; index++) { 593 ret = of_parse_phandle_with_fixed_args(np, "gpio-ranges", 3, 594 index, &pinspec); 595 if (ret) 596 break; 597 598 pctldev = of_pinctrl_get(pinspec.np); 599 of_node_put(pinspec.np); 600 if (!pctldev) 601 return -EPROBE_DEFER; 602 603 if (pinspec.args[2]) { 604 if (group_names) { 605 of_property_read_string_index(np, 606 group_names_propname, 607 index, &name); 608 if (strlen(name)) { 609 pr_err("%pOF: Group name of numeric GPIO ranges must be the empty string.\n", 610 np); 611 break; 612 } 613 } 614 /* npins != 0: linear range */ 615 ret = gpiochip_add_pin_range(chip, 616 pinctrl_dev_get_devname(pctldev), 617 pinspec.args[0], 618 pinspec.args[1], 619 pinspec.args[2]); 620 if (ret) 621 return ret; 622 } else { 623 /* npins == 0: special range */ 624 if (pinspec.args[1]) { 625 pr_err("%pOF: Illegal gpio-range format.\n", 626 np); 627 break; 628 } 629 630 if (!group_names) { 631 pr_err("%pOF: GPIO group range requested but no %s property.\n", 632 np, group_names_propname); 633 break; 634 } 635 636 ret = of_property_read_string_index(np, 637 group_names_propname, 638 index, &name); 639 if (ret) 640 break; 641 642 if (!strlen(name)) { 643 pr_err("%pOF: Group name of GPIO group range cannot be the empty string.\n", 644 np); 645 break; 646 } 647 648 ret = gpiochip_add_pingroup_range(chip, pctldev, 649 pinspec.args[0], name); 650 if (ret) 651 return ret; 652 } 653 } 654 655 return 0; 656 } 657 658 #else 659 static int of_gpiochip_add_pin_range(struct gpio_chip *chip) { return 0; } 660 #endif 661 662 int of_gpiochip_add(struct gpio_chip *chip) 663 { 664 int status; 665 666 if (!chip->of_node) 667 return 0; 668 669 if (!chip->of_xlate) { 670 chip->of_gpio_n_cells = 2; 671 chip->of_xlate = of_gpio_simple_xlate; 672 } 673 674 if (chip->of_gpio_n_cells > MAX_PHANDLE_ARGS) 675 return -EINVAL; 676 677 of_gpiochip_init_valid_mask(chip); 678 679 status = of_gpiochip_add_pin_range(chip); 680 if (status) 681 return status; 682 683 /* If the chip defines names itself, these take precedence */ 684 if (!chip->names) 685 devprop_gpiochip_set_names(chip, 686 of_fwnode_handle(chip->of_node)); 687 688 of_node_get(chip->of_node); 689 690 return of_gpiochip_scan_gpios(chip); 691 } 692 693 void of_gpiochip_remove(struct gpio_chip *chip) 694 { 695 gpiochip_remove_pin_ranges(chip); 696 of_node_put(chip->of_node); 697 } 698