drivers/gpio/gpiolib.c

   1 #include <linux/kernel.h>
   2 #include <linux/module.h>
   3 #include <linux/irq.h>
   4 #include <linux/spinlock.h>
   5
   6 #include <asm/gpio.h>
   7
   8
   9 /* Optional implementation infrastructure for GPIO interfaces.
  10  *
  11  * Platforms may want to use this if they tend to use very many GPIOs
  12  * that aren't part of a System-On-Chip core; or across I2C/SPI/etc.
  13  *
  14  * When kernel footprint or instruction count is an issue, simpler
  15  * implementations may be preferred.  The GPIO programming interface
  16  * allows for inlining speed-critical get/set operations for common
  17  * cases, so that access to SOC-integrated GPIOs can sometimes cost
  18  * only an instruction or two per bit.
  19  */
  20
  21
  22 /* When debugging, extend minimal trust to callers and platform code.
  23  * Also emit diagnostic messages that may help initial bringup, when
  24  * board setup or driver bugs are most common.
  25  *
  26  * Otherwise, minimize overhead in what may be bitbanging codepaths.
  27  */
  28 #ifdef  DEBUG
  29 #define extra_checks    1
  30 #else
  31 #define extra_checks    0
  32 #endif
  33
  34 /* gpio_lock prevents conflicts during gpio_desc[] table updates.
  35  * While any GPIO is requested, its gpio_chip is not removable;
  36  * each GPIO's "requested" flag serves as a lock and refcount.
  37  */
  38 static DEFINE_SPINLOCK(gpio_lock);
  39
  40 struct gpio_desc {
  41         struct gpio_chip        *chip;
  42         unsigned long           flags;
  43 /* flag symbols are bit numbers */
  44 #define FLAG_REQUESTED  0
  45 #define FLAG_IS_OUT     1
  46
  47 #ifdef CONFIG_DEBUG_FS
  48         const char              *label;
  49 #endif
  50 };
  51 static struct gpio_desc gpio_desc[ARCH_NR_GPIOS];
  52
  53 static inline void desc_set_label(struct gpio_desc *d, const char *label)
  54 {
  55 #ifdef CONFIG_DEBUG_FS
  56         d->label = label;
  57 #endif
  58 }
  59
  60 /* Warn when drivers omit gpio_request() calls -- legal but ill-advised
  61  * when setting direction, and otherwise illegal.  Until board setup code
  62  * and drivers use explicit requests everywhere (which won't happen when
  63  * those calls have no teeth) we can't avoid autorequesting.  This nag
  64  * message should motivate switching to explicit requests...
  65  */
  66 static void gpio_ensure_requested(struct gpio_desc *desc)
  67 {
  68         if (test_and_set_bit(FLAG_REQUESTED, &desc->flags) == 0) {
  69                 pr_warning("GPIO-%d autorequested\n", (int)(desc - gpio_desc));
  70                 desc_set_label(desc, "[auto]");
  71                 if (!try_module_get(desc->chip->owner))
  72                         pr_err("GPIO-%d: module can't be gotten \n",
  73                                         (int)(desc - gpio_desc));
  74         }
  75 }
  76
  77 /* caller holds gpio_lock *OR* gpio is marked as requested */
  78 static inline struct gpio_chip *gpio_to_chip(unsigned gpio)
  79 {
  80         return gpio_desc[gpio].chip;
  81 }
  82
  83 /**
  84  * gpiochip_add() - register a gpio_chip
  85  * @chip: the chip to register, with chip->base initialized
  86  * Context: potentially before irqs or kmalloc will work
  87  *
  88  * Returns a negative errno if the chip can't be registered, such as
  89  * because the chip->base is invalid or already associated with a
  90  * different chip.  Otherwise it returns zero as a success code.
  91  */
  92 int gpiochip_add(struct gpio_chip *chip)
  93 {
  94         unsigned long   flags;
  95         int             status = 0;
  96         unsigned        id;
  97
  98         /* NOTE chip->base negative is reserved to mean a request for
  99          * dynamic allocation.  We don't currently support that.
 100          */
 101
 102         if (chip->base < 0 || !gpio_is_valid(chip->base  + chip->ngpio)) {
 103                 status = -EINVAL;
 104                 goto fail;
 105         }
 106
 107         spin_lock_irqsave(&gpio_lock, flags);
 108
 109         /* these GPIO numbers must not be managed by another gpio_chip */
 110         for (id = chip->base; id < chip->base + chip->ngpio; id++) {
 111                 if (gpio_desc[id].chip != NULL) {
 112                         status = -EBUSY;
 113                         break;
 114                 }
 115         }
 116         if (status == 0) {
 117                 for (id = chip->base; id < chip->base + chip->ngpio; id++) {
 118                         gpio_desc[id].chip = chip;
 119                         gpio_desc[id].flags = 0;
 120                 }
 121         }
 122
 123         spin_unlock_irqrestore(&gpio_lock, flags);
 124 fail:
 125         /* failures here can mean systems won't boot... */
 126         if (status)
 127                 pr_err("gpiochip_add: gpios %d..%d (%s) not registered\n",
 128                         chip->base, chip->base + chip->ngpio,
 129                         chip->label ? : "generic");
 130         return status;
 131 }
 132 EXPORT_SYMBOL_GPL(gpiochip_add);
 133
 134 /**
 135  * gpiochip_remove() - unregister a gpio_chip
 136  * @chip: the chip to unregister
 137  *
 138  * A gpio_chip with any GPIOs still requested may not be removed.
 139  */
 140 int gpiochip_remove(struct gpio_chip *chip)
 141 {
 142         unsigned long   flags;
 143         int             status = 0;
 144         unsigned        id;
 145
 146         spin_lock_irqsave(&gpio_lock, flags);
 147
 148         for (id = chip->base; id < chip->base + chip->ngpio; id++) {
 149                 if (test_bit(FLAG_REQUESTED, &gpio_desc[id].flags)) {
 150                         status = -EBUSY;
 151                         break;
 152                 }
 153         }
 154         if (status == 0) {
 155                 for (id = chip->base; id < chip->base + chip->ngpio; id++)
 156                         gpio_desc[id].chip = NULL;
 157         }
 158
 159         spin_unlock_irqrestore(&gpio_lock, flags);
 160         return status;
 161 }
 162 EXPORT_SYMBOL_GPL(gpiochip_remove);
 163
 164
 165 /* These "optional" allocation calls help prevent drivers from stomping
 166  * on each other, and help provide better diagnostics in debugfs.
 167  * They're called even less than the "set direction" calls.
 168  */
 169 int gpio_request(unsigned gpio, const char *label)
 170 {
 171         struct gpio_desc        *desc;
 172         int                     status = -EINVAL;
 173         unsigned long           flags;
 174
 175         spin_lock_irqsave(&gpio_lock, flags);
 176
 177         if (!gpio_is_valid(gpio))
 178                 goto done;
 179         desc = &gpio_desc[gpio];
 180         if (desc->chip == NULL)
 181                 goto done;
 182
 183         if (!try_module_get(desc->chip->owner))
 184                 goto done;
 185
 186         /* NOTE:  gpio_request() can be called in early boot,
 187          * before IRQs are enabled.
 188          */
 189
 190         if (test_and_set_bit(FLAG_REQUESTED, &desc->flags) == 0) {
 191                 desc_set_label(desc, label ? : "?");
 192                 status = 0;
 193         } else {
 194                 status = -EBUSY;
 195                 module_put(desc->chip->owner);
 196         }
 197
 198 done:
 199         if (status)
 200                 pr_debug("gpio_request: gpio-%d (%s) status %d\n",
 201                         gpio, label ? : "?", status);
 202         spin_unlock_irqrestore(&gpio_lock, flags);
 203         return status;
 204 }
 205 EXPORT_SYMBOL_GPL(gpio_request);
 206
 207 void gpio_free(unsigned gpio)
 208 {
 209         unsigned long           flags;
 210         struct gpio_desc        *desc;
 211
 212         if (!gpio_is_valid(gpio)) {
 213                 WARN_ON(extra_checks);
 214                 return;
 215         }
 216
 217         spin_lock_irqsave(&gpio_lock, flags);
 218
 219         desc = &gpio_desc[gpio];
 220         if (desc->chip && test_and_clear_bit(FLAG_REQUESTED, &desc->flags)) {
 221                 desc_set_label(desc, NULL);
 222                 module_put(desc->chip->owner);
 223         } else
 224                 WARN_ON(extra_checks);
 225
 226         spin_unlock_irqrestore(&gpio_lock, flags);
 227 }
 228 EXPORT_SYMBOL_GPL(gpio_free);
 229
 230
 231 /**
 232  * gpiochip_is_requested - return string iff signal was requested
 233  * @chip: controller managing the signal
 234  * @offset: of signal within controller's 0..(ngpio - 1) range
 235  *
 236  * Returns NULL if the GPIO is not currently requested, else a string.
 237  * If debugfs support is enabled, the string returned is the label passed
 238  * to gpio_request(); otherwise it is a meaningless constant.
 239  *
 240  * This function is for use by GPIO controller drivers.  The label can
 241  * help with diagnostics, and knowing that the signal is used as a GPIO
 242  * can help avoid accidentally multiplexing it to another controller.
 243  */
 244 const char *gpiochip_is_requested(struct gpio_chip *chip, unsigned offset)
 245 {
 246         unsigned gpio = chip->base + offset;
 247
 248         if (!gpio_is_valid(gpio) || gpio_desc[gpio].chip != chip)
 249                 return NULL;
 250         if (test_bit(FLAG_REQUESTED, &gpio_desc[gpio].flags) == 0)
 251                 return NULL;
 252 #ifdef CONFIG_DEBUG_FS
 253         return gpio_desc[gpio].label;
 254 #else
 255         return "?";
 256 #endif
 257 }
 258 EXPORT_SYMBOL_GPL(gpiochip_is_requested);
 259
 260
 261 /* Drivers MUST set GPIO direction before making get/set calls.  In
 262  * some cases this is done in early boot, before IRQs are enabled.
 263  *
 264  * As a rule these aren't called more than once (except for drivers
 265  * using the open-drain emulation idiom) so these are natural places
 266  * to accumulate extra debugging checks.  Note that we can't (yet)
 267  * rely on gpio_request() having been called beforehand.
 268  */
 269
 270 int gpio_direction_input(unsigned gpio)
 271 {
 272         unsigned long           flags;
 273         struct gpio_chip        *chip;
 274         struct gpio_desc        *desc = &gpio_desc[gpio];
 275         int                     status = -EINVAL;
 276
 277         spin_lock_irqsave(&gpio_lock, flags);
 278
 279         if (!gpio_is_valid(gpio))
 280                 goto fail;
 281         chip = desc->chip;
 282         if (!chip || !chip->get || !chip->direction_input)
 283                 goto fail;
 284         gpio -= chip->base;
 285         if (gpio >= chip->ngpio)
 286                 goto fail;
 287         gpio_ensure_requested(desc);
 288
 289         /* now we know the gpio is valid and chip won't vanish */
 290
 291         spin_unlock_irqrestore(&gpio_lock, flags);
 292
 293         might_sleep_if(extra_checks && chip->can_sleep);
 294
 295         status = chip->direction_input(chip, gpio);
 296         if (status == 0)
 297                 clear_bit(FLAG_IS_OUT, &desc->flags);
 298         return status;
 299 fail:
 300         spin_unlock_irqrestore(&gpio_lock, flags);
 301         if (status)
 302                 pr_debug("%s: gpio-%d status %d\n",
 303                         __FUNCTION__, gpio, status);
 304         return status;
 305 }
 306 EXPORT_SYMBOL_GPL(gpio_direction_input);
 307
 308 int gpio_direction_output(unsigned gpio, int value)
 309 {
 310         unsigned long           flags;
 311         struct gpio_chip        *chip;
 312         struct gpio_desc        *desc = &gpio_desc[gpio];
 313         int                     status = -EINVAL;
 314
 315         spin_lock_irqsave(&gpio_lock, flags);
 316
 317         if (!gpio_is_valid(gpio))
 318                 goto fail;
 319         chip = desc->chip;
 320         if (!chip || !chip->set || !chip->direction_output)
 321                 goto fail;
 322         gpio -= chip->base;
 323         if (gpio >= chip->ngpio)
 324                 goto fail;
 325         gpio_ensure_requested(desc);
 326
 327         /* now we know the gpio is valid and chip won't vanish */
 328
 329         spin_unlock_irqrestore(&gpio_lock, flags);
 330
 331         might_sleep_if(extra_checks && chip->can_sleep);
 332
 333         status = chip->direction_output(chip, gpio, value);
 334         if (status == 0)
 335                 set_bit(FLAG_IS_OUT, &desc->flags);
 336         return status;
 337 fail:
 338         spin_unlock_irqrestore(&gpio_lock, flags);
 339         if (status)
 340                 pr_debug("%s: gpio-%d status %d\n",
 341                         __FUNCTION__, gpio, status);
 342         return status;
 343 }
 344 EXPORT_SYMBOL_GPL(gpio_direction_output);
 345
 346
 347 /* I/O calls are only valid after configuration completed; the relevant
 348  * "is this a valid GPIO" error checks should already have been done.
 349  *
 350  * "Get" operations are often inlinable as reading a pin value register,
 351  * and masking the relevant bit in that register.
 352  *
 353  * When "set" operations are inlinable, they involve writing that mask to
 354  * one register to set a low value, or a different register to set it high.
 355  * Otherwise locking is needed, so there may be little value to inlining.
 356  *
 357  *------------------------------------------------------------------------
 358  *
 359  * IMPORTANT!!!  The hot paths -- get/set value -- assume that callers
 360  * have requested the GPIO.  That can include implicit requesting by
 361  * a direction setting call.  Marking a gpio as requested locks its chip
 362  * in memory, guaranteeing that these table lookups need no more locking
 363  * and that gpiochip_remove() will fail.
 364  *
 365  * REVISIT when debugging, consider adding some instrumentation to ensure
 366  * that the GPIO was actually requested.
 367  */
 368
 369 /**
 370  * __gpio_get_value() - return a gpio's value
 371  * @gpio: gpio whose value will be returned
 372  * Context: any
 373  *
 374  * This is used directly or indirectly to implement gpio_get_value().
 375  * It returns the zero or nonzero value provided by the associated
 376  * gpio_chip.get() method; or zero if no such method is provided.
 377  */
 378 int __gpio_get_value(unsigned gpio)
 379 {
 380         struct gpio_chip        *chip;
 381
 382         chip = gpio_to_chip(gpio);
 383         WARN_ON(extra_checks && chip->can_sleep);
 384         return chip->get ? chip->get(chip, gpio - chip->base) : 0;
 385 }
 386 EXPORT_SYMBOL_GPL(__gpio_get_value);
 387
 388 /**
 389  * __gpio_set_value() - assign a gpio's value
 390  * @gpio: gpio whose value will be assigned
 391  * @value: value to assign
 392  * Context: any
 393  *
 394  * This is used directly or indirectly to implement gpio_set_value().
 395  * It invokes the associated gpio_chip.set() method.
 396  */
 397 void __gpio_set_value(unsigned gpio, int value)
 398 {
 399         struct gpio_chip        *chip;
 400
 401         chip = gpio_to_chip(gpio);
 402         WARN_ON(extra_checks && chip->can_sleep);
 403         chip->set(chip, gpio - chip->base, value);
 404 }
 405 EXPORT_SYMBOL_GPL(__gpio_set_value);
 406
 407 /**
 408  * __gpio_cansleep() - report whether gpio value access will sleep
 409  * @gpio: gpio in question
 410  * Context: any
 411  *
 412  * This is used directly or indirectly to implement gpio_cansleep().  It
 413  * returns nonzero if access reading or writing the GPIO value can sleep.
 414  */
 415 int __gpio_cansleep(unsigned gpio)
 416 {
 417         struct gpio_chip        *chip;
 418
 419         /* only call this on GPIOs that are valid! */
 420         chip = gpio_to_chip(gpio);
 421
 422         return chip->can_sleep;
 423 }
 424 EXPORT_SYMBOL_GPL(__gpio_cansleep);
 425
 426
 427
 428 /* There's no value in making it easy to inline GPIO calls that may sleep.
 429  * Common examples include ones connected to I2C or SPI chips.
 430  */
 431
 432 int gpio_get_value_cansleep(unsigned gpio)
 433 {
 434         struct gpio_chip        *chip;
 435
 436         might_sleep_if(extra_checks);
 437         chip = gpio_to_chip(gpio);
 438         return chip->get(chip, gpio - chip->base);
 439 }
 440 EXPORT_SYMBOL_GPL(gpio_get_value_cansleep);
 441
 442 void gpio_set_value_cansleep(unsigned gpio, int value)
 443 {
 444         struct gpio_chip        *chip;
 445
 446         might_sleep_if(extra_checks);
 447         chip = gpio_to_chip(gpio);
 448         chip->set(chip, gpio - chip->base, value);
 449 }
 450 EXPORT_SYMBOL_GPL(gpio_set_value_cansleep);
 451
 452
 453 #ifdef CONFIG_DEBUG_FS
 454
 455 #include <linux/debugfs.h>
 456 #include <linux/seq_file.h>
 457
 458
 459 static void gpiolib_dbg_show(struct seq_file *s, struct gpio_chip *chip)
 460 {
 461         unsigned                i;
 462         unsigned                gpio = chip->base;
 463         struct gpio_desc        *gdesc = &gpio_desc[gpio];
 464         int                     is_out;
 465
 466         for (i = 0; i < chip->ngpio; i++, gpio++, gdesc++) {
 467                 if (!test_bit(FLAG_REQUESTED, &gdesc->flags))
 468                         continue;
 469
 470                 is_out = test_bit(FLAG_IS_OUT, &gdesc->flags);
 471                 seq_printf(s, " gpio-%-3d (%-12s) %s %s",
 472                         gpio, gdesc->label,
 473                         is_out ? "out" : "in ",
 474                         chip->get
 475                                 ? (chip->get(chip, i) ? "hi" : "lo")
 476                                 : "?  ");
 477
 478                 if (!is_out) {
 479                         int             irq = gpio_to_irq(gpio);
 480                         struct irq_desc *desc = irq_desc + irq;
 481
 482                         /* This races with request_irq(), set_irq_type(),
 483                          * and set_irq_wake() ... but those are "rare".
 484                          *
 485                          * More significantly, trigger type flags aren't
 486                          * currently maintained by genirq.
 487                          */
 488                         if (irq >= 0 && desc->action) {
 489                                 char *trigger;
 490
 491                                 switch (desc->status & IRQ_TYPE_SENSE_MASK) {
 492                                 case IRQ_TYPE_NONE:
 493                                         trigger = "(default)";
 494                                         break;
 495                                 case IRQ_TYPE_EDGE_FALLING:
 496                                         trigger = "edge-falling";
 497                                         break;
 498                                 case IRQ_TYPE_EDGE_RISING:
 499                                         trigger = "edge-rising";
 500                                         break;
 501                                 case IRQ_TYPE_EDGE_BOTH:
 502                                         trigger = "edge-both";
 503                                         break;
 504                                 case IRQ_TYPE_LEVEL_HIGH:
 505                                         trigger = "level-high";
 506                                         break;
 507                                 case IRQ_TYPE_LEVEL_LOW:
 508                                         trigger = "level-low";
 509                                         break;
 510                                 default:
 511                                         trigger = "?trigger?";
 512                                         break;
 513                                 }
 514
 515                                 seq_printf(s, " irq-%d %s%s",
 516                                         irq, trigger,
 517                                         (desc->status & IRQ_WAKEUP)
 518                                                 ? " wakeup" : "");
 519                         }
 520                 }
 521
 522                 seq_printf(s, "\n");
 523         }
 524 }
 525
 526 static int gpiolib_show(struct seq_file *s, void *unused)
 527 {
 528         struct gpio_chip        *chip = NULL;
 529         unsigned                gpio;
 530         int                     started = 0;
 531
 532         /* REVISIT this isn't locked against gpio_chip removal ... */
 533
 534         for (gpio = 0; gpio_is_valid(gpio); gpio++) {
 535                 if (chip == gpio_desc[gpio].chip)
 536                         continue;
 537                 chip = gpio_desc[gpio].chip;
 538                 if (!chip)
 539                         continue;
 540
 541                 seq_printf(s, "%sGPIOs %d-%d, %s%s:\n",
 542                                 started ? "\n" : "",
 543                                 chip->base, chip->base + chip->ngpio - 1,
 544                                 chip->label ? : "generic",
 545                                 chip->can_sleep ? ", can sleep" : "");
 546                 started = 1;
 547                 if (chip->dbg_show)
 548                         chip->dbg_show(s, chip);
 549                 else
 550                         gpiolib_dbg_show(s, chip);
 551         }
 552         return 0;
 553 }
 554
 555 static int gpiolib_open(struct inode *inode, struct file *file)
 556 {
 557         return single_open(file, gpiolib_show, NULL);
 558 }
 559
 560 static struct file_operations gpiolib_operations = {
 561         .open           = gpiolib_open,
 562         .read           = seq_read,
 563         .llseek         = seq_lseek,
 564         .release        = single_release,
 565 };
 566
 567 static int __init gpiolib_debugfs_init(void)
 568 {
 569         /* /sys/kernel/debug/gpio */
 570         (void) debugfs_create_file("gpio", S_IFREG | S_IRUGO,
 571                                 NULL, NULL, &gpiolib_operations);
 572         return 0;
 573 }
 574 subsys_initcall(gpiolib_debugfs_init);
 575
 576 #endif  /* DEBUG_FS */