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