Using GPIO from a linux shell on iMX based products

Difficulty Levels: Intermediate
Date added: July 3, 2018
Affected Products: EDM1-CF-IMX6 , EDM1-CF-IMX6SX , EDM1-IMX6PLUS , EDM1-IMX6UL , EDM1-IMX7D , EDM2-IMX6PLUS , PICO-IMX6 , PICO-IMX6UL , PICO-IMX6UL-NAND , PICO-IMX6UL-NOR , PICO-IMX7 , PICO-IMX8M , TC-0700 , TC-0710 , TC-1010 , TEK3-IMX6 , TEK3-IMX6UL , TEP-0500-IMX6UL , TEP-0500-IMX7 , TEP-0700-IMX6UL , TEP-0700-IMX7 , TEP-1010-IMX6 , TEP-1560-IMX6 , TWP-1010-IMX6 , TWP-1560-IMX6 , WANDPI-8M , WBDUAL , WBQUAD , WBSOLO

Summary

This guide teaches how to find the correct GPIO number for a pin. It also shows how to read the value of an input gpio, or set the value of an output gpio.

Background

The iMX-series CPUs (iMX5, iMX6, iMX6SX, iMX6UL, iMX7D, iMX8M, …) refer to GPIOs using two parameters: a bank number and an io number. For example typical GPIOs can be GPIO2_IO12 or GPIO1_IO00.

The bank refers to the internal GPIO controller inside the CPU, and one controller has 32 IOs. For the example gpios, GPIO2_IO12 uses bank 2 and io 12.

Finding gpio number

To use a GPIO its number needs to be known. If we know the bank and io number, the kernel’s number can be calculated with
N = (BANK – 1) * 32 + IO

For example GPIO2_IO12 would get the kernel GPIO number
N = (2 – 1) * 32 + 12 = 44

Finding out which bank and io a pin has, one has to consult the schematics.

Once the pin name has been found, it’s corresponding GPIO bank and io number can be looked up either in the processor’s reference manual, or from within the kernel source code. In the latter the pinmuxes are defined in the device tree folder arch/arm/boot/dts/, usually in a file named *pinfunc.h or so.

A pin can only have one pinmux as GPIO, and a GPIO+IO can only be present on one pin (it is a one-to-one mapping).

Setting and reading a GPIO

The GPIOs are typically accessible in /sys/class/gpio folder.

Each GPIO has its own folder. For instance GPIO 44 will use folder named /sys/class/gpio/gpio44. If the folder is not present, the GPIO needs to be exported first. This can be done by:
# echo 44 > /sys/class/gpio/export
and similarily unexported by
# echo 44 > /sys/class/gpio/unexport

Inside the gpio folder are the two important ‘files’: value and direction.

To read the value of a gpio, first set the gpio as an input by
# echo in > /sys/class/gpio/gpio44/direction
and then read the value by
# cat /sys/class/gpio/gpio44/value

Similarily, set the value of output GPIOs by first setting the direction
# echo out > /sys/class/gpio/gpio44/direction
and then set the value low by
# echo 0 > /sys/class/gpio/gpio44/value
or to high
# echo 1 > /sys/class/gpio/gpio44/value

NB: On products that have isolated GPIOs this semantic is reversed, use 1 for low and 0 for high.

GPIO expanders

GPIO expanders appear on some TechNexion products. Typically the GPIOs on expander chips do not follow the bank/io priniciple. Instead
the GPIOs are directly mapped to the end of the gpio number space. Look for folders name gpiochip* in /sys/class/gpio/.
Easiest way to find the expander is to look at the ngpio file in the gpiochipN folder. A 8-bit expander will have an 8 in ngpio.
Then the GPIO numbers can be found by looking at the base file. A value of, say, 208 means that the expanders gpios will be number
208, 209, 210, …

When the GPIO numbers have been identified, they can be exported and used just as the CPU native banked GPIOs.

Future of GPIOs

Since 2016 there is a movement in Linux kernel community to move away from the sysfs based GPIOs to character devices (/dev/gpiochipN). The current /sys/class/gpio/ folder is likely to be around for quite some time – but applications that want to be futureproof should considering
using the character devices instead.

Troubleshooting GPIOs

Sometimes it might appear that writes to the value file have no effect, the value stays 0 and measuring the voltage on the gpio line gives the same result.

Some common causes for this type of problems are:

  • The pin is already used by something else, typically defined to do so in the device tree. Look there first.
  • The pin number is wrong. Do the math again. 🙂
  • The pin is not muxed as GPIO after all. Re-check the device tree.
  • The pin is an isolated GPIO and cannot be set in desired mode
  • The pin is an isolated output GPIO, and there is no external power connected to the GPIO port

Stay up to date with all the latest TechNexion news...

Sign-up for our Newsletter