1======================
2Legacy GPIO Interfaces
3======================
4
5This provides an overview of GPIO access conventions on Linux.
6
7These calls use the gpio_* naming prefix.  No other calls should use that
8prefix, or the related __gpio_* prefix.
9
10
11What is a GPIO?
12===============
13A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
14digital signal.  They are provided from many kinds of chip, and are familiar
15to Linux developers working with embedded and custom hardware.  Each GPIO
16represents a bit connected to a particular pin, or "ball" on Ball Grid Array
17(BGA) packages.  Board schematics show which external hardware connects to
18which GPIOs.  Drivers can be written generically, so that board setup code
19passes such pin configuration data to drivers.
20
21System-on-Chip (SOC) processors heavily rely on GPIOs.  In some cases, every
22non-dedicated pin can be configured as a GPIO; and most chips have at least
23several dozen of them.  Programmable logic devices (like FPGAs) can easily
24provide GPIOs; multifunction chips like power managers, and audio codecs
25often have a few such pins to help with pin scarcity on SOCs; and there are
26also "GPIO Expander" chips that connect using the I2C or SPI serial busses.
27Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
28firmware knowing how they're used).
29
30The exact capabilities of GPIOs vary between systems.  Common options:
31
32  - Output values are writable (high=1, low=0).  Some chips also have
33    options about how that value is driven, so that for example only one
34    value might be driven ... supporting "wire-OR" and similar schemes
35    for the other value (notably, "open drain" signaling).
36
37  - Input values are likewise readable (1, 0).  Some chips support readback
38    of pins configured as "output", which is very useful in such "wire-OR"
39    cases (to support bidirectional signaling).  GPIO controllers may have
40    input de-glitch/debounce logic, sometimes with software controls.
41
42  - Inputs can often be used as IRQ signals, often edge triggered but
43    sometimes level triggered.  Such IRQs may be configurable as system
44    wakeup events, to wake the system from a low power state.
45
46  - Usually a GPIO will be configurable as either input or output, as needed
47    by different product boards; single direction ones exist too.
48
49  - Most GPIOs can be accessed while holding spinlocks, but those accessed
50    through a serial bus normally can't.  Some systems support both types.
51
52On a given board each GPIO is used for one specific purpose like monitoring
53MMC/SD card insertion/removal, detecting card writeprotect status, driving
54a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware
55watchdog, sensing a switch, and so on.
56
57
58GPIO conventions
59================
60Note that this is called a "convention" because you don't need to do it this
61way, and it's no crime if you don't.  There **are** cases where portability
62is not the main issue; GPIOs are often used for the kind of board-specific
63glue logic that may even change between board revisions, and can't ever be
64used on a board that's wired differently.  Only least-common-denominator
65functionality can be very portable.  Other features are platform-specific,
66and that can be critical for glue logic.
67
68Plus, this doesn't require any implementation framework, just an interface.
69One platform might implement it as simple inline functions accessing chip
70registers; another might implement it by delegating through abstractions
71used for several very different kinds of GPIO controller.  (There is some
72optional code supporting such an implementation strategy, described later
73in this document, but drivers acting as clients to the GPIO interface must
74not care how it's implemented.)
75
76That said, if the convention is supported on their platform, drivers should
77use it when possible.  Platforms must select GPIOLIB if GPIO functionality
78is strictly required.  Drivers that can't work without
79standard GPIO calls should have Kconfig entries which depend on GPIOLIB.  The
80GPIO calls are available, either as "real code" or as optimized-away stubs,
81when drivers use the include file:
82
83	#include <linux/gpio.h>
84
85If you stick to this convention then it'll be easier for other developers to
86see what your code is doing, and help maintain it.
87
88Note that these operations include I/O barriers on platforms which need to
89use them; drivers don't need to add them explicitly.
90
91
92Identifying GPIOs
93-----------------
94GPIOs are identified by unsigned integers in the range 0..MAX_INT.  That
95reserves "negative" numbers for other purposes like marking signals as
96"not available on this board", or indicating faults.  Code that doesn't
97touch the underlying hardware treats these integers as opaque cookies.
98
99Platforms define how they use those integers, and usually #define symbols
100for the GPIO lines so that board-specific setup code directly corresponds
101to the relevant schematics.  In contrast, drivers should only use GPIO
102numbers passed to them from that setup code, using platform_data to hold
103board-specific pin configuration data (along with other board specific
104data they need).  That avoids portability problems.
105
106So for example one platform uses numbers 32-159 for GPIOs; while another
107uses numbers 0..63 with one set of GPIO controllers, 64-79 with another
108type of GPIO controller, and on one particular board 80-95 with an FPGA.
109The numbers need not be contiguous; either of those platforms could also
110use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.
111
112If you want to initialize a structure with an invalid GPIO number, use
113some negative number (perhaps "-EINVAL"); that will never be valid.  To
114test if such number from such a structure could reference a GPIO, you
115may use this predicate:
116
117	int gpio_is_valid(int number);
118
119A number that's not valid will be rejected by calls which may request
120or free GPIOs (see below).  Other numbers may also be rejected; for
121example, a number might be valid but temporarily unused on a given board.
122
123Whether a platform supports multiple GPIO controllers is a platform-specific
124implementation issue, as are whether that support can leave "holes" in the space
125of GPIO numbers, and whether new controllers can be added at runtime.  Such issues
126can affect things including whether adjacent GPIO numbers are both valid.
127
128Using GPIOs
129-----------
130The first thing a system should do with a GPIO is allocate it, using
131the gpio_request() call; see later.
132
133One of the next things to do with a GPIO, often in board setup code when
134setting up a platform_device using the GPIO, is mark its direction::
135
136	/* set as input or output, returning 0 or negative errno */
137	int gpio_direction_input(unsigned gpio);
138	int gpio_direction_output(unsigned gpio, int value);
139
140The return value is zero for success, else a negative errno.  It should
141be checked, since the get/set calls don't have error returns and since
142misconfiguration is possible.  You should normally issue these calls from
143a task context.  However, for spinlock-safe GPIOs it's OK to use them
144before tasking is enabled, as part of early board setup.
145
146For output GPIOs, the value provided becomes the initial output value.
147This helps avoid signal glitching during system startup.
148
149For compatibility with legacy interfaces to GPIOs, setting the direction
150of a GPIO implicitly requests that GPIO (see below) if it has not been
151requested already.  That compatibility is being removed from the optional
152gpiolib framework.
153
154Setting the direction can fail if the GPIO number is invalid, or when
155that particular GPIO can't be used in that mode.  It's generally a bad
156idea to rely on boot firmware to have set the direction correctly, since
157it probably wasn't validated to do more than boot Linux.  (Similarly,
158that board setup code probably needs to multiplex that pin as a GPIO,
159and configure pullups/pulldowns appropriately.)
160
161
162Spinlock-Safe GPIO access
163-------------------------
164Most GPIO controllers can be accessed with memory read/write instructions.
165Those don't need to sleep, and can safely be done from inside hard
166(nonthreaded) IRQ handlers and similar contexts.
167
168Use the following calls to access such GPIOs,
169for which gpio_cansleep() will always return false (see below)::
170
171	/* GPIO INPUT:  return zero or nonzero */
172	int gpio_get_value(unsigned gpio);
173
174	/* GPIO OUTPUT */
175	void gpio_set_value(unsigned gpio, int value);
176
177The values are boolean, zero for low, nonzero for high.  When reading the
178value of an output pin, the value returned should be what's seen on the
179pin ... that won't always match the specified output value, because of
180issues including open-drain signaling and output latencies.
181
182The get/set calls have no error returns because "invalid GPIO" should have
183been reported earlier from gpio_direction_*().  However, note that not all
184platforms can read the value of output pins; those that can't should always
185return zero.  Also, using these calls for GPIOs that can't safely be accessed
186without sleeping (see below) is an error.
187
188Platform-specific implementations are encouraged to optimize the two
189calls to access the GPIO value in cases where the GPIO number (and for
190output, value) are constant.  It's normal for them to need only a couple
191of instructions in such cases (reading or writing a hardware register),
192and not to need spinlocks.  Such optimized calls can make bitbanging
193applications a lot more efficient (in both space and time) than spending
194dozens of instructions on subroutine calls.
195
196
197GPIO access that may sleep
198--------------------------
199Some GPIO controllers must be accessed using message based busses like I2C
200or SPI.  Commands to read or write those GPIO values require waiting to
201get to the head of a queue to transmit a command and get its response.
202This requires sleeping, which can't be done from inside IRQ handlers.
203
204Platforms that support this type of GPIO distinguish them from other GPIOs
205by returning nonzero from this call (which requires a valid GPIO number,
206which should have been previously allocated with gpio_request)::
207
208	int gpio_cansleep(unsigned gpio);
209
210To access such GPIOs, a different set of accessors is defined::
211
212	/* GPIO INPUT:  return zero or nonzero, might sleep */
213	int gpio_get_value_cansleep(unsigned gpio);
214
215	/* GPIO OUTPUT, might sleep */
216	void gpio_set_value_cansleep(unsigned gpio, int value);
217
218
219Accessing such GPIOs requires a context which may sleep,  for example
220a threaded IRQ handler, and those accessors must be used instead of
221spinlock-safe accessors without the cansleep() name suffix.
222
223Other than the fact that these accessors might sleep, and will work
224on GPIOs that can't be accessed from hardIRQ handlers, these calls act
225the same as the spinlock-safe calls.
226
227**IN ADDITION** calls to setup and configure such GPIOs must be made
228from contexts which may sleep, since they may need to access the GPIO
229controller chip too  (These setup calls are usually made from board
230setup or driver probe/teardown code, so this is an easy constraint.)::
231
232                gpio_direction_input()
233                gpio_direction_output()
234                gpio_request()
235
236        ## 	gpio_request_one()
237        ##	gpio_request_array()
238        ## 	gpio_free_array()
239
240                gpio_free()
241                gpio_set_debounce()
242
243
244
245Claiming and Releasing GPIOs
246----------------------------
247To help catch system configuration errors, two calls are defined::
248
249	/* request GPIO, returning 0 or negative errno.
250	 * non-null labels may be useful for diagnostics.
251	 */
252	int gpio_request(unsigned gpio, const char *label);
253
254	/* release previously-claimed GPIO */
255	void gpio_free(unsigned gpio);
256
257Passing invalid GPIO numbers to gpio_request() will fail, as will requesting
258GPIOs that have already been claimed with that call.  The return value of
259gpio_request() must be checked.  You should normally issue these calls from
260a task context.  However, for spinlock-safe GPIOs it's OK to request GPIOs
261before tasking is enabled, as part of early board setup.
262
263These calls serve two basic purposes.  One is marking the signals which
264are actually in use as GPIOs, for better diagnostics; systems may have
265several hundred potential GPIOs, but often only a dozen are used on any
266given board.  Another is to catch conflicts, identifying errors when
267(a) two or more drivers wrongly think they have exclusive use of that
268signal, or (b) something wrongly believes it's safe to remove drivers
269needed to manage a signal that's in active use.  That is, requesting a
270GPIO can serve as a kind of lock.
271
272Some platforms may also use knowledge about what GPIOs are active for
273power management, such as by powering down unused chip sectors and, more
274easily, gating off unused clocks.
275
276For GPIOs that use pins known to the pinctrl subsystem, that subsystem should
277be informed of their use; a gpiolib driver's .request() operation may call
278pinctrl_gpio_request(), and a gpiolib driver's .free() operation may call
279pinctrl_gpio_free(). The pinctrl subsystem allows a pinctrl_gpio_request()
280to succeed concurrently with a pin or pingroup being "owned" by a device for
281pin multiplexing.
282
283Any programming of pin multiplexing hardware that is needed to route the
284GPIO signal to the appropriate pin should occur within a GPIO driver's
285.direction_input() or .direction_output() operations, and occur after any
286setup of an output GPIO's value. This allows a glitch-free migration from a
287pin's special function to GPIO. This is sometimes required when using a GPIO
288to implement a workaround on signals typically driven by a non-GPIO HW block.
289
290Some platforms allow some or all GPIO signals to be routed to different pins.
291Similarly, other aspects of the GPIO or pin may need to be configured, such as
292pullup/pulldown. Platform software should arrange that any such details are
293configured prior to gpio_request() being called for those GPIOs, e.g. using
294the pinctrl subsystem's mapping table, so that GPIO users need not be aware
295of these details.
296
297Also note that it's your responsibility to have stopped using a GPIO
298before you free it.
299
300Considering in most cases GPIOs are actually configured right after they
301are claimed, three additional calls are defined::
302
303	/* request a single GPIO, with initial configuration specified by
304	 * 'flags', identical to gpio_request() wrt other arguments and
305	 * return value
306	 */
307	int gpio_request_one(unsigned gpio, unsigned long flags, const char *label);
308
309	/* request multiple GPIOs in a single call
310	 */
311	int gpio_request_array(struct gpio *array, size_t num);
312
313	/* release multiple GPIOs in a single call
314	 */
315	void gpio_free_array(struct gpio *array, size_t num);
316
317where 'flags' is currently defined to specify the following properties:
318
319	* GPIOF_DIR_IN		- to configure direction as input
320	* GPIOF_DIR_OUT		- to configure direction as output
321
322	* GPIOF_INIT_LOW	- as output, set initial level to LOW
323	* GPIOF_INIT_HIGH	- as output, set initial level to HIGH
324	* GPIOF_OPEN_DRAIN	- gpio pin is open drain type.
325	* GPIOF_OPEN_SOURCE	- gpio pin is open source type.
326
327	* GPIOF_EXPORT_DIR_FIXED	- export gpio to sysfs, keep direction
328	* GPIOF_EXPORT_DIR_CHANGEABLE	- also export, allow changing direction
329
330since GPIOF_INIT_* are only valid when configured as output, so group valid
331combinations as:
332
333	* GPIOF_IN		- configure as input
334	* GPIOF_OUT_INIT_LOW	- configured as output, initial level LOW
335	* GPIOF_OUT_INIT_HIGH	- configured as output, initial level HIGH
336
337When setting the flag as GPIOF_OPEN_DRAIN then it will assume that pins is
338open drain type. Such pins will not be driven to 1 in output mode. It is
339require to connect pull-up on such pins. By enabling this flag, gpio lib will
340make the direction to input when it is asked to set value of 1 in output mode
341to make the pin HIGH. The pin is make to LOW by driving value 0 in output mode.
342
343When setting the flag as GPIOF_OPEN_SOURCE then it will assume that pins is
344open source type. Such pins will not be driven to 0 in output mode. It is
345require to connect pull-down on such pin. By enabling this flag, gpio lib will
346make the direction to input when it is asked to set value of 0 in output mode
347to make the pin LOW. The pin is make to HIGH by driving value 1 in output mode.
348
349In the future, these flags can be extended to support more properties.
350
351Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is
352introduced to encapsulate all three fields as::
353
354	struct gpio {
355		unsigned	gpio;
356		unsigned long	flags;
357		const char	*label;
358	};
359
360A typical example of usage::
361
362	static struct gpio leds_gpios[] = {
363		{ 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */
364		{ 33, GPIOF_OUT_INIT_LOW,  "Green LED" }, /* default to OFF */
365		{ 34, GPIOF_OUT_INIT_LOW,  "Red LED"   }, /* default to OFF */
366		{ 35, GPIOF_OUT_INIT_LOW,  "Blue LED"  }, /* default to OFF */
367		{ ... },
368	};
369
370	err = gpio_request_one(31, GPIOF_IN, "Reset Button");
371	if (err)
372		...
373
374	err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios));
375	if (err)
376		...
377
378	gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios));
379
380
381GPIOs mapped to IRQs
382--------------------
383GPIO numbers are unsigned integers; so are IRQ numbers.  These make up
384two logically distinct namespaces (GPIO 0 need not use IRQ 0).  You can
385map between them using calls like::
386
387	/* map GPIO numbers to IRQ numbers */
388	int gpio_to_irq(unsigned gpio);
389
390	/* map IRQ numbers to GPIO numbers (avoid using this) */
391	int irq_to_gpio(unsigned irq);
392
393Those return either the corresponding number in the other namespace, or
394else a negative errno code if the mapping can't be done.  (For example,
395some GPIOs can't be used as IRQs.)  It is an unchecked error to use a GPIO
396number that wasn't set up as an input using gpio_direction_input(), or
397to use an IRQ number that didn't originally come from gpio_to_irq().
398
399These two mapping calls are expected to cost on the order of a single
400addition or subtraction.  They're not allowed to sleep.
401
402Non-error values returned from gpio_to_irq() can be passed to request_irq()
403or free_irq().  They will often be stored into IRQ resources for platform
404devices, by the board-specific initialization code.  Note that IRQ trigger
405options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are
406system wakeup capabilities.
407
408Non-error values returned from irq_to_gpio() would most commonly be used
409with gpio_get_value(), for example to initialize or update driver state
410when the IRQ is edge-triggered.  Note that some platforms don't support
411this reverse mapping, so you should avoid using it.
412
413
414Emulating Open Drain Signals
415----------------------------
416Sometimes shared signals need to use "open drain" signaling, where only the
417low signal level is actually driven.  (That term applies to CMOS transistors;
418"open collector" is used for TTL.)  A pullup resistor causes the high signal
419level.  This is sometimes called a "wire-AND"; or more practically, from the
420negative logic (low=true) perspective this is a "wire-OR".
421
422One common example of an open drain signal is a shared active-low IRQ line.
423Also, bidirectional data bus signals sometimes use open drain signals.
424
425Some GPIO controllers directly support open drain outputs; many don't.  When
426you need open drain signaling but your hardware doesn't directly support it,
427there's a common idiom you can use to emulate it with any GPIO pin that can
428be used as either an input or an output:
429
430 LOW:	gpio_direction_output(gpio, 0) ... this drives the signal
431	and overrides the pullup.
432
433 HIGH:	gpio_direction_input(gpio) ... this turns off the output,
434	so the pullup (or some other device) controls the signal.
435
436If you are "driving" the signal high but gpio_get_value(gpio) reports a low
437value (after the appropriate rise time passes), you know some other component
438is driving the shared signal low.  That's not necessarily an error.  As one
439common example, that's how I2C clocks are stretched:  a slave that needs a
440slower clock delays the rising edge of SCK, and the I2C master adjusts its
441signaling rate accordingly.
442
443
444GPIO controllers and the pinctrl subsystem
445------------------------------------------
446
447A GPIO controller on a SOC might be tightly coupled with the pinctrl
448subsystem, in the sense that the pins can be used by other functions
449together with an optional gpio feature. We have already covered the
450case where e.g. a GPIO controller need to reserve a pin or set the
451direction of a pin by calling any of::
452
453  pinctrl_gpio_request()
454  pinctrl_gpio_free()
455  pinctrl_gpio_direction_input()
456  pinctrl_gpio_direction_output()
457
458But how does the pin control subsystem cross-correlate the GPIO
459numbers (which are a global business) to a certain pin on a certain
460pin controller?
461
462This is done by registering "ranges" of pins, which are essentially
463cross-reference tables. These are described in
464Documentation/driver-api/pinctl.rst
465
466While the pin allocation is totally managed by the pinctrl subsystem,
467gpio (under gpiolib) is still maintained by gpio drivers. It may happen
468that different pin ranges in a SoC is managed by different gpio drivers.
469
470This makes it logical to let gpio drivers announce their pin ranges to
471the pin ctrl subsystem before it will call 'pinctrl_gpio_request' in order
472to request the corresponding pin to be prepared by the pinctrl subsystem
473before any gpio usage.
474
475For this, the gpio controller can register its pin range with pinctrl
476subsystem. There are two ways of doing it currently: with or without DT.
477
478For with DT support refer to Documentation/devicetree/bindings/gpio/gpio.txt.
479
480For non-DT support, user can call gpiochip_add_pin_range() with appropriate
481parameters to register a range of gpio pins with a pinctrl driver. For this
482exact name string of pinctrl device has to be passed as one of the
483argument to this routine.
484
485
486What do these conventions omit?
487===============================
488One of the biggest things these conventions omit is pin multiplexing, since
489this is highly chip-specific and nonportable.  One platform might not need
490explicit multiplexing; another might have just two options for use of any
491given pin; another might have eight options per pin; another might be able
492to route a given GPIO to any one of several pins.  (Yes, those examples all
493come from systems that run Linux today.)
494
495Related to multiplexing is configuration and enabling of the pullups or
496pulldowns integrated on some platforms.  Not all platforms support them,
497or support them in the same way; and any given board might use external
498pullups (or pulldowns) so that the on-chip ones should not be used.
499(When a circuit needs 5 kOhm, on-chip 100 kOhm resistors won't do.)
500Likewise drive strength (2 mA vs 20 mA) and voltage (1.8V vs 3.3V) is a
501platform-specific issue, as are models like (not) having a one-to-one
502correspondence between configurable pins and GPIOs.
503
504There are other system-specific mechanisms that are not specified here,
505like the aforementioned options for input de-glitching and wire-OR output.
506Hardware may support reading or writing GPIOs in gangs, but that's usually
507configuration dependent:  for GPIOs sharing the same bank.  (GPIOs are
508commonly grouped in banks of 16 or 32, with a given SOC having several such
509banks.)  Some systems can trigger IRQs from output GPIOs, or read values
510from pins not managed as GPIOs.  Code relying on such mechanisms will
511necessarily be nonportable.
512
513Dynamic definition of GPIOs is not currently standard; for example, as
514a side effect of configuring an add-on board with some GPIO expanders.
515
516
517GPIO implementor's framework (OPTIONAL)
518=======================================
519As noted earlier, there is an optional implementation framework making it
520easier for platforms to support different kinds of GPIO controller using
521the same programming interface.  This framework is called "gpiolib".
522
523As a debugging aid, if debugfs is available a /sys/kernel/debug/gpio file
524will be found there.  That will list all the controllers registered through
525this framework, and the state of the GPIOs currently in use.
526
527
528Controller Drivers: gpio_chip
529-----------------------------
530In this framework each GPIO controller is packaged as a "struct gpio_chip"
531with information common to each controller of that type:
532
533 - methods to establish GPIO direction
534 - methods used to access GPIO values
535 - flag saying whether calls to its methods may sleep
536 - optional debugfs dump method (showing extra state like pullup config)
537 - label for diagnostics
538
539There is also per-instance data, which may come from device.platform_data:
540the number of its first GPIO, and how many GPIOs it exposes.
541
542The code implementing a gpio_chip should support multiple instances of the
543controller, possibly using the driver model.  That code will configure each
544gpio_chip and issue gpiochip_add().  Removing a GPIO controller should be
545rare; use gpiochip_remove() when it is unavoidable.
546
547Most often a gpio_chip is part of an instance-specific structure with state
548not exposed by the GPIO interfaces, such as addressing, power management,
549and more.  Chips such as codecs will have complex non-GPIO state.
550
551Any debugfs dump method should normally ignore signals which haven't been
552requested as GPIOs.  They can use gpiochip_is_requested(), which returns
553either NULL or the label associated with that GPIO when it was requested.
554
555
556Platform Support
557----------------
558To force-enable this framework, a platform's Kconfig will "select" GPIOLIB,
559else it is up to the user to configure support for GPIO.
560
561It may also provide a custom value for ARCH_NR_GPIOS, so that it better
562reflects the number of GPIOs in actual use on that platform, without
563wasting static table space.  (It should count both built-in/SoC GPIOs and
564also ones on GPIO expanders.
565
566If neither of these options are selected, the platform does not support
567GPIOs through GPIO-lib and the code cannot be enabled by the user.
568
569Trivial implementations of those functions can directly use framework
570code, which always dispatches through the gpio_chip::
571
572  #define gpio_get_value	__gpio_get_value
573  #define gpio_set_value	__gpio_set_value
574  #define gpio_cansleep		__gpio_cansleep
575
576Fancier implementations could instead define those as inline functions with
577logic optimizing access to specific SOC-based GPIOs.  For example, if the
578referenced GPIO is the constant "12", getting or setting its value could
579cost as little as two or three instructions, never sleeping.  When such an
580optimization is not possible those calls must delegate to the framework
581code, costing at least a few dozen instructions.  For bitbanged I/O, such
582instruction savings can be significant.
583
584For SOCs, platform-specific code defines and registers gpio_chip instances
585for each bank of on-chip GPIOs.  Those GPIOs should be numbered/labeled to
586match chip vendor documentation, and directly match board schematics.  They
587may well start at zero and go up to a platform-specific limit.  Such GPIOs
588are normally integrated into platform initialization to make them always be
589available, from arch_initcall() or earlier; they can often serve as IRQs.
590
591
592Board Support
593-------------
594For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi
595function devices, FPGAs or CPLDs -- most often board-specific code handles
596registering controller devices and ensures that their drivers know what GPIO
597numbers to use with gpiochip_add().  Their numbers often start right after
598platform-specific GPIOs.
599
600For example, board setup code could create structures identifying the range
601of GPIOs that chip will expose, and passes them to each GPIO expander chip
602using platform_data.  Then the chip driver's probe() routine could pass that
603data to gpiochip_add().
604
605Initialization order can be important.  For example, when a device relies on
606an I2C-based GPIO, its probe() routine should only be called after that GPIO
607becomes available.  That may mean the device should not be registered until
608calls for that GPIO can work.  One way to address such dependencies is for
609such gpio_chip controllers to provide setup() and teardown() callbacks to
610board specific code; those board specific callbacks would register devices
611once all the necessary resources are available, and remove them later when
612the GPIO controller device becomes unavailable.
613
614
615Sysfs Interface for Userspace (OPTIONAL)
616========================================
617Platforms which use the "gpiolib" implementors framework may choose to
618configure a sysfs user interface to GPIOs.  This is different from the
619debugfs interface, since it provides control over GPIO direction and
620value instead of just showing a gpio state summary.  Plus, it could be
621present on production systems without debugging support.
622
623Given appropriate hardware documentation for the system, userspace could
624know for example that GPIO #23 controls the write protect line used to
625protect boot loader segments in flash memory.  System upgrade procedures
626may need to temporarily remove that protection, first importing a GPIO,
627then changing its output state, then updating the code before re-enabling
628the write protection.  In normal use, GPIO #23 would never be touched,
629and the kernel would have no need to know about it.
630
631Again depending on appropriate hardware documentation, on some systems
632userspace GPIO can be used to determine system configuration data that
633standard kernels won't know about.  And for some tasks, simple userspace
634GPIO drivers could be all that the system really needs.
635
636Note that standard kernel drivers exist for common "LEDs and Buttons"
637GPIO tasks:  "leds-gpio" and "gpio_keys", respectively.  Use those
638instead of talking directly to the GPIOs; they integrate with kernel
639frameworks better than your userspace code could.
640
641
642Paths in Sysfs
643--------------
644There are three kinds of entry in /sys/class/gpio:
645
646   -	Control interfaces used to get userspace control over GPIOs;
647
648   -	GPIOs themselves; and
649
650   -	GPIO controllers ("gpio_chip" instances).
651
652That's in addition to standard files including the "device" symlink.
653
654The control interfaces are write-only:
655
656    /sys/class/gpio/
657
658    	"export" ... Userspace may ask the kernel to export control of
659		a GPIO to userspace by writing its number to this file.
660
661		Example:  "echo 19 > export" will create a "gpio19" node
662		for GPIO #19, if that's not requested by kernel code.
663
664    	"unexport" ... Reverses the effect of exporting to userspace.
665
666		Example:  "echo 19 > unexport" will remove a "gpio19"
667		node exported using the "export" file.
668
669GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
670and have the following read/write attributes:
671
672    /sys/class/gpio/gpioN/
673
674	"direction" ... reads as either "in" or "out".  This value may
675		normally be written.  Writing as "out" defaults to
676		initializing the value as low.  To ensure glitch free
677		operation, values "low" and "high" may be written to
678		configure the GPIO as an output with that initial value.
679
680		Note that this attribute *will not exist* if the kernel
681		doesn't support changing the direction of a GPIO, or
682		it was exported by kernel code that didn't explicitly
683		allow userspace to reconfigure this GPIO's direction.
684
685	"value" ... reads as either 0 (low) or 1 (high).  If the GPIO
686		is configured as an output, this value may be written;
687		any nonzero value is treated as high.
688
689		If the pin can be configured as interrupt-generating interrupt
690		and if it has been configured to generate interrupts (see the
691		description of "edge"), you can poll(2) on that file and
692		poll(2) will return whenever the interrupt was triggered. If
693		you use poll(2), set the events POLLPRI and POLLERR. If you
694		use select(2), set the file descriptor in exceptfds. After
695		poll(2) returns, either lseek(2) to the beginning of the sysfs
696		file and read the new value or close the file and re-open it
697		to read the value.
698
699	"edge" ... reads as either "none", "rising", "falling", or
700		"both". Write these strings to select the signal edge(s)
701		that will make poll(2) on the "value" file return.
702
703		This file exists only if the pin can be configured as an
704		interrupt generating input pin.
705
706	"active_low" ... reads as either 0 (false) or 1 (true).  Write
707		any nonzero value to invert the value attribute both
708		for reading and writing.  Existing and subsequent
709		poll(2) support configuration via the edge attribute
710		for "rising" and "falling" edges will follow this
711		setting.
712
713GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
714controller implementing GPIOs starting at #42) and have the following
715read-only attributes:
716
717    /sys/class/gpio/gpiochipN/
718
719    	"base" ... same as N, the first GPIO managed by this chip
720
721    	"label" ... provided for diagnostics (not always unique)
722
723    	"ngpio" ... how many GPIOs this manges (N to N + ngpio - 1)
724
725Board documentation should in most cases cover what GPIOs are used for
726what purposes.  However, those numbers are not always stable; GPIOs on
727a daughtercard might be different depending on the base board being used,
728or other cards in the stack.  In such cases, you may need to use the
729gpiochip nodes (possibly in conjunction with schematics) to determine
730the correct GPIO number to use for a given signal.
731
732
733Exporting from Kernel code
734--------------------------
735Kernel code can explicitly manage exports of GPIOs which have already been
736requested using gpio_request()::
737
738	/* export the GPIO to userspace */
739	int gpio_export(unsigned gpio, bool direction_may_change);
740
741	/* reverse gpio_export() */
742	void gpio_unexport();
743
744	/* create a sysfs link to an exported GPIO node */
745	int gpio_export_link(struct device *dev, const char *name,
746		unsigned gpio)
747
748After a kernel driver requests a GPIO, it may only be made available in
749the sysfs interface by gpio_export().  The driver can control whether the
750signal direction may change.  This helps drivers prevent userspace code
751from accidentally clobbering important system state.
752
753This explicit exporting can help with debugging (by making some kinds
754of experiments easier), or can provide an always-there interface that's
755suitable for documenting as part of a board support package.
756
757After the GPIO has been exported, gpio_export_link() allows creating
758symlinks from elsewhere in sysfs to the GPIO sysfs node.  Drivers can
759use this to provide the interface under their own device in sysfs with
760a descriptive name.
761
762
763API Reference
764=============
765
766The functions listed in this section are deprecated. The GPIO descriptor based
767API should be used in new code.
768
769.. kernel-doc:: drivers/gpio/gpiolib-legacy.c
770   :export:
771