Identifying GPIOs¶

GPIOs are identified by unsigned integers in the range 0..MAX_INT. Thatreserves “negative” numbers for other purposes like marking signals as“not available on this board”, or indicating faults. Code that doesn’ttouch the underlying hardware treats these integers as opaque cookies.

Platforms define how they use those integers, and usually #define symbolsfor the GPIO lines so that board-specific setup code directly correspondsto the relevant schematics. In contrast, drivers should only use GPIOnumbers passed to them from that setup code, using platform_data to holdboard-specific pin configuration data (along with other board specificdata they need). That avoids portability problems.

So for example one platform uses numbers 32-159 for GPIOs; while anotheruses numbers 0..63 with one set of GPIO controllers, 64-79 with anothertype of GPIO controller, and on one particular board 80-95 with an FPGA.The numbers need not be contiguous; either of those platforms could alsouse numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.

If you want to initialize a structure with an invalid GPIO number, usesome negative number (perhaps “-EINVAL”); that will never be valid. Totest if such number from such a structure could reference a GPIO, youmay use this predicate:

int gpio_is_valid(int number);

A number that’s not valid will be rejected by calls which may requestor free GPIOs (see below). Other numbers may also be rejected; forexample, a number might be valid but temporarily unused on a given board.

Whether a platform supports multiple GPIO controllers is a platform-specificimplementation issue, as are whether that support can leave “holes” in the spaceof GPIO numbers, and whether new controllers can be added at runtime. Such issuescan affect things including whether adjacent GPIO numbers are both valid.

Using GPIOs¶

The first thing a system should do with a GPIO is allocate it, usingthe gpio_request() call; see later.

One of the next things to do with a GPIO, often in board setup code whensetting up a platform_device using the GPIO, is mark its direction:

/* set as input or output, returning 0 or negative errno */int gpio_direction_input(unsigned gpio);int gpio_direction_output(unsigned gpio, int value);

The return value is zero for success, else a negative errno. It shouldbe checked, since the get/set calls don’t have error returns and sincemisconfiguration is possible. You should normally issue these calls froma task context. However, for spinlock-safe GPIOs it’s OK to use thembefore tasking is enabled, as part of early board setup.

For output GPIOs, the value provided becomes the initial output value.This helps avoid signal glitching during system startup.

For compatibility with legacy interfaces to GPIOs, setting the directionof a GPIO implicitly requests that GPIO (see below) if it has not beenrequested already. That compatibility is being removed from the optionalgpiolib framework.

Setting the direction can fail if the GPIO number is invalid, or whenthat particular GPIO can’t be used in that mode. It’s generally a badidea to rely on boot firmware to have set the direction correctly, sinceit probably wasn’t validated to do more than boot Linux. (Similarly,that board setup code probably needs to multiplex that pin as a GPIO,and configure pullups/pulldowns appropriately.)

Spinlock-Safe GPIO access¶

Most GPIO controllers can be accessed with memory read/write instructions.Those don’t need to sleep, and can safely be done from inside hard(nonthreaded) IRQ handlers and similar contexts.

Use the following calls to access such GPIOs,for which gpio_cansleep() will always return false (see below):

/* GPIO INPUT:  return zero or nonzero */int gpio_get_value(unsigned gpio);/* GPIO OUTPUT */void gpio_set_value(unsigned gpio, int value);

The values are boolean, zero for low, nonzero for high. When reading thevalue of an output pin, the value returned should be what’s seen on thepin … that won’t always match the specified output value, because ofissues including open-drain signaling and output latencies.

The get/set calls have no error returns because “invalid GPIO” should havebeen reported earlier from gpio_direction_*(). However, note that not allplatforms can read the value of output pins; those that can’t should alwaysreturn zero. Also, using these calls for GPIOs that can’t safely be accessedwithout sleeping (see below) is an error.

Platform-specific implementations are encouraged to optimize the twocalls to access the GPIO value in cases where the GPIO number (and foroutput, value) are constant. It’s normal for them to need only a coupleof instructions in such cases (reading or writing a hardware register),and not to need spinlocks. Such optimized calls can make bitbangingapplications a lot more efficient (in both space and time) than spendingdozens of instructions on subroutine calls.

GPIO access that may sleep¶

Some GPIO controllers must be accessed using message based busses like I2Cor SPI. Commands to read or write those GPIO values require waiting toget to the head of a queue to transmit a command and get its response.This requires sleeping, which can’t be done from inside IRQ handlers.

Platforms that support this type of GPIO distinguish them from other GPIOsby returning nonzero from this call (which requires a valid GPIO number,which should have been previously allocated with gpio_request):

int gpio_cansleep(unsigned gpio);

To access such GPIOs, a different set of accessors is defined:

/* GPIO INPUT:  return zero or nonzero, might sleep */int gpio_get_value_cansleep(unsigned gpio);/* GPIO OUTPUT, might sleep */void gpio_set_value_cansleep(unsigned gpio, int value);

Accessing such GPIOs requires a context which may sleep, for examplea threaded IRQ handler, and those accessors must be used instead ofspinlock-safe accessors without the cansleep() name suffix.

Other than the fact that these accessors might sleep, and will workon GPIOs that can’t be accessed from hardIRQ handlers, these calls actthe same as the spinlock-safe calls.

IN ADDITION calls to setup and configure such GPIOs must be madefrom contexts which may sleep, since they may need to access the GPIOcontroller chip too (These setup calls are usually made from boardsetup or driver probe/teardown code, so this is an easy constraint.):

        gpio_direction_input()        gpio_direction_output()        gpio_request()##      gpio_request_one()##      gpio_request_array()##      gpio_free_array()        gpio_free()        gpio_set_debounce()

Claiming and Releasing GPIOs¶

To help catch system configuration errors, two calls are defined:

/* request GPIO, returning 0 or negative errno. * non-null labels may be useful for diagnostics. */int gpio_request(unsigned gpio, const char *label);/* release previously-claimed GPIO */void gpio_free(unsigned gpio);

Passing invalid GPIO numbers to gpio_request() will fail, as will requestingGPIOs that have already been claimed with that call. The return value ofgpio_request() must be checked. You should normally issue these calls froma task context. However, for spinlock-safe GPIOs it’s OK to request GPIOsbefore tasking is enabled, as part of early board setup.

These calls serve two basic purposes. One is marking the signals whichare actually in use as GPIOs, for better diagnostics; systems may haveseveral hundred potential GPIOs, but often only a dozen are used on anygiven board. Another is to catch conflicts, identifying errors when(a) two or more drivers wrongly think they have exclusive use of thatsignal, or (b) something wrongly believes it’s safe to remove driversneeded to manage a signal that’s in active use. That is, requesting aGPIO can serve as a kind of lock.

Some platforms may also use knowledge about what GPIOs are active forpower management, such as by powering down unused chip sectors and, moreeasily, gating off unused clocks.

For GPIOs that use pins known to the pinctrl subsystem, that subsystem shouldbe informed of their use; a gpiolib driver’s .request() operation may callpinctrl_gpio_request(), and a gpiolib driver’s .free() operation may callpinctrl_gpio_free(). The pinctrl subsystem allows a pinctrl_gpio_request()to succeed concurrently with a pin or pingroup being “owned” by a device forpin multiplexing.

Any programming of pin multiplexing hardware that is needed to route theGPIO signal to the appropriate pin should occur within a GPIO driver’s.direction_input() or .direction_output() operations, and occur after anysetup of an output GPIO’s value. This allows a glitch-free migration from apin’s special function to GPIO. This is sometimes required when using a GPIOto implement a workaround on signals typically driven by a non-GPIO HW block.

Some platforms allow some or all GPIO signals to be routed to different pins.Similarly, other aspects of the GPIO or pin may need to be configured, such aspullup/pulldown. Platform software should arrange that any such details areconfigured prior to gpio_request() being called for those GPIOs, e.g. usingthe pinctrl subsystem’s mapping table, so that GPIO users need not be awareof these details.

Also note that it’s your responsibility to have stopped using a GPIObefore you free it.

Considering in most cases GPIOs are actually configured right after theyare claimed, three additional calls are defined:

/* request a single GPIO, with initial configuration specified by * 'flags', identical to gpio_request() wrt other arguments and * return value */int gpio_request_one(unsigned gpio, unsigned long flags, const char *label);/* request multiple GPIOs in a single call */int gpio_request_array(struct gpio *array, size_t num);/* release multiple GPIOs in a single call */void gpio_free_array(struct gpio *array, size_t num);

where ‘flags’ is currently defined to specify the following properties:

• GPIOF_DIR_IN - to configure direction as input
• GPIOF_DIR_OUT - to configure direction as output
• GPIOF_INIT_LOW - as output, set initial level to LOW
• GPIOF_INIT_HIGH - as output, set initial level to HIGH
• GPIOF_OPEN_DRAIN - gpio pin is open drain type.
• GPIOF_OPEN_SOURCE - gpio pin is open source type.
• GPIOF_EXPORT_DIR_FIXED - export gpio to sysfs, keep direction
• GPIOF_EXPORT_DIR_CHANGEABLE - also export, allow changing direction

since GPIOF_INIT_* are only valid when configured as output, so group validcombinations as:

• GPIOF_IN - configure as input
• GPIOF_OUT_INIT_LOW - configured as output, initial level LOW
• GPIOF_OUT_INIT_HIGH - configured as output, initial level HIGH

When setting the flag as GPIOF_OPEN_DRAIN then it will assume that pins isopen drain type. Such pins will not be driven to 1 in output mode. It isrequire to connect pull-up on such pins. By enabling this flag, gpio lib willmake the direction to input when it is asked to set value of 1 in output modeto make the pin HIGH. The pin is make to LOW by driving value 0 in output mode.

When setting the flag as GPIOF_OPEN_SOURCE then it will assume that pins isopen source type. Such pins will not be driven to 0 in output mode. It isrequire to connect pull-down on such pin. By enabling this flag, gpio lib willmake the direction to input when it is asked to set value of 0 in output modeto make the pin LOW. The pin is make to HIGH by driving value 1 in output mode.

In the future, these flags can be extended to support more properties.

Further more, to ease the claim/release of multiple GPIOs, ‘struct gpio’ isintroduced to encapsulate all three fields as:

struct gpio {        unsigned        gpio;        unsigned long   flags;        const char      *label;};

A typical example of usage:

static struct gpio leds_gpios[] = {        { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */        { 33, GPIOF_OUT_INIT_LOW,  "Green LED" }, /* default to OFF */        { 34, GPIOF_OUT_INIT_LOW,  "Red LED"   }, /* default to OFF */        { 35, GPIOF_OUT_INIT_LOW,  "Blue LED"  }, /* default to OFF */        { ... },};err = gpio_request_one(31, GPIOF_IN, "Reset Button");if (err)        ...err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios));if (err)        ...gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios));

GPIOs mapped to IRQs¶

GPIO numbers are unsigned integers; so are IRQ numbers. These make uptwo logically distinct namespaces (GPIO 0 need not use IRQ 0). You canmap between them using calls like:

/* map GPIO numbers to IRQ numbers */int gpio_to_irq(unsigned gpio);/* map IRQ numbers to GPIO numbers (avoid using this) */int irq_to_gpio(unsigned irq);

Those return either the corresponding number in the other namespace, orelse a negative errno code if the mapping can’t be done. (For example,some GPIOs can’t be used as IRQs.) It is an unchecked error to use a GPIOnumber that wasn’t set up as an input using gpio_direction_input(), orto use an IRQ number that didn’t originally come from gpio_to_irq().

These two mapping calls are expected to cost on the order of a singleaddition or subtraction. They’re not allowed to sleep.

Non-error values returned from gpio_to_irq() can be passed torequest_irq()orfree_irq(). They will often be stored into IRQ resources for platformdevices, by the board-specific initialization code. Note that IRQ triggeroptions are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as aresystem wakeup capabilities.

Non-error values returned from irq_to_gpio() would most commonly be usedwith gpio_get_value(), for example to initialize or update driver statewhen the IRQ is edge-triggered. Note that some platforms don’t supportthis reverse mapping, so you should avoid using it.

Emulating Open Drain Signals¶

Sometimes shared signals need to use “open drain” signaling, where only thelow signal level is actually driven. (That term applies to CMOS transistors;“open collector” is used for TTL.) A pullup resistor causes the high signallevel. This is sometimes called a “wire-AND”; or more practically, from thenegative logic (low=true) perspective this is a “wire-OR”.

One common example of an open drain signal is a shared active-low IRQ line.Also, bidirectional data bus signals sometimes use open drain signals.

Some GPIO controllers directly support open drain outputs; many don’t. Whenyou need open drain signaling but your hardware doesn’t directly support it,there’s a common idiom you can use to emulate it with any GPIO pin that canbe used as either an input or an output:

LOW: gpio_direction_output(gpio, 0) … this drives the signal

and overrides the pullup.

HIGH: gpio_direction_input(gpio) … this turns off the output,

so the pullup (or some other device) controls the signal.

If you are “driving” the signal high but gpio_get_value(gpio) reports a lowvalue (after the appropriate rise time passes), you know some other componentis driving the shared signal low. That’s not necessarily an error. As onecommon example, that’s how I2C clocks are stretched: a slave that needs aslower clock delays the rising edge of SCK, and the I2C master adjusts itssignaling rate accordingly.

GPIO controllers and the pinctrl subsystem¶

A GPIO controller on a SOC might be tightly coupled with the pinctrlsubsystem, in the sense that the pins can be used by other functionstogether with an optional gpio feature. We have already covered thecase where e.g. a GPIO controller need to reserve a pin or set thedirection of a pin by calling any of:

pinctrl_gpio_request()pinctrl_gpio_free()pinctrl_gpio_direction_input()pinctrl_gpio_direction_output()

But how does the pin control subsystem cross-correlate the GPIOnumbers (which are a global business) to a certain pin on a certainpin controller?

This is done by registering “ranges” of pins, which are essentiallycross-reference tables. These are described inDocumentation/driver-api/pinctl.rst

While the pin allocation is totally managed by the pinctrl subsystem,gpio (under gpiolib) is still maintained by gpio drivers. It may happenthat different pin ranges in a SoC is managed by different gpio drivers.

This makes it logical to let gpio drivers announce their pin ranges tothe pin ctrl subsystem before it will call ‘pinctrl_gpio_request’ in orderto request the corresponding pin to be prepared by the pinctrl subsystembefore any gpio usage.

For this, the gpio controller can register its pin range with pinctrlsubsystem. There are two ways of doing it currently: with or without DT.

For with DT support refer to Documentation/devicetree/bindings/gpio/gpio.txt.

For non-DT support, user can callgpiochip_add_pin_range() with appropriateparameters to register a range of gpio pins with a pinctrl driver. For thisexact name string of pinctrl device has to be passed as one of theargument to this routine.

Controller Drivers: gpio_chip¶

In this framework each GPIO controller is packaged as a “struct gpio_chip”with information common to each controller of that type:

• methods to establish GPIO direction
• methods used to access GPIO values
• flag saying whether calls to its methods may sleep
• optional debugfs dump method (showing extra state like pullup config)
• label for diagnostics

There is also per-instance data, which may come from device.platform_data:the number of its first GPIO, and how many GPIOs it exposes.

The code implementing a gpio_chip should support multiple instances of thecontroller, possibly using the driver model. That code will configure eachgpio_chip and issue gpiochip_add(). Removing a GPIO controller should berare; usegpiochip_remove() when it is unavoidable.

Most often a gpio_chip is part of an instance-specific structure with statenot exposed by the GPIO interfaces, such as addressing, power management,and more. Chips such as codecs will have complex non-GPIO state.

Any debugfs dump method should normally ignore signals which haven’t beenrequested as GPIOs. They can usegpiochip_is_requested(), which returnseither NULL or the label associated with that GPIO when it was requested.

Platform Support¶

To force-enable this framework, a platform’s Kconfig will “select” GPIOLIB,else it is up to the user to configure support for GPIO.

It may also provide a custom value for ARCH_NR_GPIOS, so that it betterreflects the number of GPIOs in actual use on that platform, withoutwasting static table space. (It should count both built-in/SoC GPIOs andalso ones on GPIO expanders.

If neither of these options are selected, the platform does not supportGPIOs through GPIO-lib and the code cannot be enabled by the user.

Trivial implementations of those functions can directly use frameworkcode, which always dispatches through the gpio_chip:

#define gpio_get_value        __gpio_get_value#define gpio_set_value        __gpio_set_value#define gpio_cansleep         __gpio_cansleep

Fancier implementations could instead define those as inline functions withlogic optimizing access to specific SOC-based GPIOs. For example, if thereferenced GPIO is the constant “12”, getting or setting its value couldcost as little as two or three instructions, never sleeping. When such anoptimization is not possible those calls must delegate to the frameworkcode, costing at least a few dozen instructions. For bitbanged I/O, suchinstruction savings can be significant.

For SOCs, platform-specific code defines and registers gpio_chip instancesfor each bank of on-chip GPIOs. Those GPIOs should be numbered/labeled tomatch chip vendor documentation, and directly match board schematics. Theymay well start at zero and go up to a platform-specific limit. Such GPIOsare normally integrated into platform initialization to make them always beavailable, from arch_initcall() or earlier; they can often serve as IRQs.

Board Support¶

For external GPIO controllers – such as I2C or SPI expanders, ASICs, multifunction devices, FPGAs or CPLDs – most often board-specific code handlesregistering controller devices and ensures that their drivers know what GPIOnumbers to use with gpiochip_add(). Their numbers often start right afterplatform-specific GPIOs.

For example, board setup code could create structures identifying the rangeof GPIOs that chip will expose, and passes them to each GPIO expander chipusing platform_data. Then the chip driver’s probe() routine could pass thatdata to gpiochip_add().

Initialization order can be important. For example, when a device relies onan I2C-based GPIO, its probe() routine should only be called after that GPIObecomes available. That may mean the device should not be registered untilcalls for that GPIO can work. One way to address such dependencies is forsuch gpio_chip controllers to provide setup() and teardown() callbacks toboard specific code; those board specific callbacks would register devicesonce all the necessary resources are available, and remove them later whenthe GPIO controller device becomes unavailable.

Paths in Sysfs¶

There are three kinds of entry in /sys/class/gpio:

• Control interfaces used to get userspace control over GPIOs;
• GPIOs themselves; and
• GPIO controllers (“gpio_chip” instances).

That’s in addition to standard files including the “device” symlink.

The control interfaces are write-only:

/sys/class/gpio/

“export” … Userspace may ask the kernel to export control of

a GPIO to userspace by writing its number to this file.

Example: “echo 19 > export” will create a “gpio19” nodefor GPIO #19, if that’s not requested by kernel code.

“unexport” … Reverses the effect of exporting to userspace.

Example: “echo 19 > unexport” will remove a “gpio19”node exported using the “export” file.

GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)and have the following read/write attributes:

/sys/class/gpio/gpioN/

“direction” … reads as either “in” or “out”. This value may

normally be written. Writing as “out” defaults toinitializing the value as low. To ensure glitch freeoperation, values “low” and “high” may be written toconfigure the GPIO as an output with that initial value.

Note that this attributewill not exist if the kerneldoesn’t support changing the direction of a GPIO, orit was exported by kernel code that didn’t explicitlyallow userspace to reconfigure this GPIO’s direction.

“value” … reads as either 0 (low) or 1 (high). If the GPIO

is configured as an output, this value may be written;any nonzero value is treated as high.

If the pin can be configured as interrupt-generating interruptand if it has been configured to generate interrupts (see thedescription of “edge”), you can poll(2) on that file andpoll(2) will return whenever the interrupt was triggered. Ifyou use poll(2), set the events POLLPRI. If you use select(2),set the file descriptor in exceptfds. After poll(2) returns,either lseek(2) to the beginning of the sysfs file and read thenew value or close the file and re-open it to read the value.

“edge” … reads as either “none”, “rising”, “falling”, or

“both”. Write these strings to select the signal edge(s)that will make poll(2) on the “value” file return.

This file exists only if the pin can be configured as aninterrupt generating input pin.

“active_low” … reads as either 0 (false) or 1 (true). Write

any nonzero value to invert the value attribute bothfor reading and writing. Existing and subsequentpoll(2) support configuration via the edge attributefor “rising” and “falling” edges will follow thissetting.

GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for thecontroller implementing GPIOs starting at #42) and have the followingread-only attributes:

/sys/class/gpio/gpiochipN/

“base” … same as N, the first GPIO managed by this chip

“label” … provided for diagnostics (not always unique)

“ngpio” … how many GPIOs this manges (N to N + ngpio - 1)

Board documentation should in most cases cover what GPIOs are used forwhat purposes. However, those numbers are not always stable; GPIOs ona daughtercard might be different depending on the base board being used,or other cards in the stack. In such cases, you may need to use thegpiochip nodes (possibly in conjunction with schematics) to determinethe correct GPIO number to use for a given signal.

Exporting from Kernel code¶

Kernel code can explicitly manage exports of GPIOs which have already beenrequested using gpio_request():

/* export the GPIO to userspace */int gpio_export(unsigned gpio, bool direction_may_change);/* reverse gpio_export() */void gpio_unexport();/* create a sysfs link to an exported GPIO node */int gpio_export_link(struct device *dev, const char *name,        unsigned gpio)

After a kernel driver requests a GPIO, it may only be made available inthe sysfs interface by gpio_export(). The driver can control whether thesignal direction may change. This helps drivers prevent userspace codefrom accidentally clobbering important system state.

This explicit exporting can help with debugging (by making some kindsof experiments easier), or can provide an always-there interface that’ssuitable for documenting as part of a board support package.

After the GPIO has been exported, gpio_export_link() allows creatingsymlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers canuse this to provide the interface under their own device in sysfs witha descriptive name.