How To Use gpiolib

Table of Contents

Summary

gpiolib is the name of the General Purpose Input/Output framework in the Linux kernel. It was introduced in the 2.6.25 kernel, and augments the existing GPIO subsystem with additional functionality. It also standardizes the way in which GPIO pins are used.

From the kernel documentation:

As noted earlier, there is an optional implementation framework making it easier for platforms to support different kinds of GPIO controller using the same programming interface. This framework is called "gpiolib".

Some of the features of using gpiolib include:
  • Optional sysfs interface for using gpio pins in userspace.
  • Optional debugfs interface, which is standardized for all GPIO implementations using this framework.
  • Standardized methods for interacting with GPIO pins.

This document focuses on using the gpiolib sysfs interface. For information about adding gpiolib support to your kernel, see the kernel document: Documentation/gpio.txt

Prerequisites

  • Kernel with the following configuration options:
    • CONFIG_GPIOLIB=y
    • CONFIG_GPIO_SYSFS=y
  • Some systems relegate pin multiplexing to the bootloader, or even all at once in the kernel, rather than when a GPIO pin is requested. You may need to modify the bootloader or kernel source in this case.

Introduction to the gpiolib sysfs

From Documentation/gpio.txt in v2.6.28:

Platforms which use the "gpiolib" implementors framework may choose to
configure a sysfs user interface to GPIOs.  This is different from the
debugfs interface, since it provides control over GPIO direction and
value instead of just showing a gpio state summary.  Plus, it could be
present on production systems without debugging support.

Given approprate[sic] hardware documentation for the system, userspace could
know for example that GPIO 23 controls the write protect line used to
protect boot loader segments in flash memory.  System upgrade procedures
may need to temporarily remove that protection, first importing a GPIO,
then changing its output state, then updating the code before re-enabling
the write protection.  In normal use, GPIO 23 would never be touched,
and the kernel would have no need to know about it.

Essentially, gpiolib keeps track of the usage of gpio pins that have been properly registered with the kernel using the gpio_request method. If you have sysfs support enabled, you can also request pins in userspace for use in a number of situations. You can request a gpio pin and control its direction and value without having to modify any kernel code. Please note that entire frameworks exist for buttons and leds (gpio_keyboard and leds, respectively) connected to GPIO pins. These drivers, and not the gpiolib sysfs interface, should be used for those purposes.

NOTE: Unfortunately a good deal of drivers fail to call the gpio_request method, so there are often GPIO pins that are being used of which the kernel is unaware. Therefore, you should not use the gpiolib interface to guarantee that a given pin is not in use.

The GPIO pins on a processor are generally divided into a number of banks, or chips. This is generally due to the layout of the registers and datapath limitations. Each chip controls a number of GPIO pins. Information about the layout of the GPIO system can be found using the sysfs inteface.

The sysfs interface for gpiolib is located at /sys/class/gpio. The following is a listing of the contents of that directory:

  • /sys/class/gpio/
    • export — Writing an integer to this file will request the given GPIO pin.
    • unexport — Writing an integer to this file will release the given GPIO pin.
    • gpiochipN/ — Directory for gpio chip N
      • 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)
    • gpioXX/ — Directory for gpio pin XX
      • direction — either 'in' or 'out'. Direction of the GPIO pin.
      • value — either '0' or '1'. The value of the gpio pin. If the pin is an output, writing to this file will set the value of the pin.

Common Tasks

The following examples request pins 96 and 97, and configure them as an output and input, respectively.

Requesting a GPIO pin

echo 96 > /sys/class/gpio/export
echo 97 > /sys/class/gpio/export

Setting GPIO direction

echo out > /sys/class/gpio/gpio96/direction
echo in > /sys/class/gpio/gpio97/direction

Reading GPIO data

cat /sys/class/gpio/gpio97/value

Setting GPIO data

echo 1 > /sys/class/gpio/gpio96/value
echo 0 > /sys/class/gpio/gpio96/value

Troubleshooting

I've requested the pin, but my LED/Button doesn't work.

Check your hardware. Get a Digital Multimeter and test the voltage of the pin. If the value is correct, then you have a hardware issue. Otherwise, it is probably one of these issues:

  • The pin is set in the wrong directional mode, i.e. LED set to input, button set to output.
  • The pin multiplexing is incorrect. This can have a number of causes:
    • Another peripheral that does not "respect" gpio requests has set it to peripheral mode rather than GPIO mode. You'll have to fix or disable the driver.
    • The kernel GPIO driver does not set up the multiplexer to set the pin in GPIO mode. On the OMAPL138, there is a mux_config struct in the file arch/arm/mach-davinci/da850.c that controls the GPIO mux. On many PowerPC boards, such as the MPC8313, the mux is set up by U-Boot, defined in the configuration file.