Using Gpio¶

Objective¶

The objective of this wiki page is to provide information about GPIOs, how to access them from Linux user-space, and how to verify that they are working.

Information¶

Converting ARM ball names to Linux GPIO numbers¶

The ARM names for GPIOs use a bank and an offset within that bank (0-31). The bank numbers start at bank 1. (no bank 0). Examples: gpio1_5, gpio3_4.

The Linux names use GPIO chip numbers (these start at 0) with an offset. Linux also use GPIO numbers (gpionum). The formula for turning an ARM bank-offset into a Linux gpionum is:

Formula: 
     gpio<bank>_<offset> => (bank-1)*32 + offset = Linux gpio number

Example: gpio1_0 => (1-1)*32 + 0 = 0

Example: gpio7_6 => (7-1)*32 + 6 = 198

GPIOs and the device tree¶

The device tree specifies that specific gpios will be used for special functions on various peripherals. These gpios are "owned" by the kernel and can't be used from user space.

User-level access to GPIOs¶

Details of user-level access are given in https://www.kernel.org/doc/Documentation/gpio/sysfs.txt. What follows is a brief sampling of what can be done.

Assume we want to access GPIO4_23. This gpio has a gpionum of (4-1)*32 + 23 = 96 + 23 = 119.

• Making the GPIO accessible from user-space.
  

  echo 119 >/sys/class/gpio/export
  

• Input GPIOs
  • Setting the direction of the GPIO for input
    

    echo in >/sys/class/gpio/gpio119/direction
    

  • See the current value
    

    cat /sys/class/gpio/gpio119/value
    

• Output GPIOs
  • Setting the direction of the GPIO for output
    

    echo out >/sys/class/gpio/gpio119/direction
    echo high >/sys/class/gpio/gpio119/direction  # sets direction and initial value
    echo low >/sys/class/gpio/gpio119/direction
    

  • See the current value
    

    cat /sys/class/gpio/gpio119/value
    

  • Set the current value
    

    echo 1 >/sys/class/gpio/gpio138/value
    

• Checking the direction
  

  cat /sys/class/gpio/gpio119/direction
  

• Stopping access from user-level
  

  echo 119 >/sys/class/gpio/unexport
  

Seeing current usage of GPIOs.¶

To see the list of all exported or claimed gpios (i.e. specified in the device tree)

cat /sys/kernel/debug/gpio

This list will show exported gpios as marked with "sysfs".

Verifying that the gpios are working¶

On the development kit, several gpios are available on the pin connectors like J11 or J13. For example, GPIO4_23 is on pin 5 of the J11 connector.

To verify that the gpio is working, try the following:

echo 119 >/sys/class/gpio/export
echo low >/sys/class/gpio/gpio119

Use a multimeter to measure the voltage level at pin 5 of the J11 connector. It should be 0.

echo 1 >/sys/class/gpio/gpio119/value

Use a multimeter to measure the voltage level at pin 5 of the J11 connector. It should now be ~1.7v.

Enabling a GPIO bank for DSP usage¶

If you are using gpios from the DSP, you may need some special device tree entries in order to automatically have the GPIO bank enabled by Linux. It is possible to do this manually, but it is usually better to make these entries so Linux knows which gpios are being used.

If no gpios in a bank are being used, then the bank is not enabled by Linux. If any gpios are being used, then the bank is enabled. If a gpio is exported, then the corresponding bank is enabled if it needs to be. When the last gpio is unexported, the bank is disabled.

The enable/disable actions affect the clock control registers for the bank in question. As described in AM57x Technical Reference, the clock control register for gpio bank 2 is named CM_L4PER_GPIO2_CLKCTRL and is located at address 0x4a009760. The register for gpio bank 3 is at 0x4a009768. To look at the values of these registers try the following:

omapconf dump 0x4a009760 0x4a00977F
|----------------------------|
| Address (hex) | Data (hex) |
|----------------------------|
| 0x4A009760    | 0x00030000 |
| 0x4A009764    | 0x00000000 |
| 0x4A009768    | 0x00020001 |
| 0x4A00976C    | 0x00000000 |
| 0x4A009770    | 0x00020001 |
| 0x4A009774    | 0x00000000 |
| 0x4A009778    | 0x00020001 |
| 0x4A00977C    | 0x00000000 |
|----------------------------|

The above shows the clock control register has a value of 0x30000 which means the bank is disabled. The values of 0x20001 indicate that banks 3, 4, and 5 are enabled.

If you want to use a gpio in bank 2, then adding the following entry in your device tree will tell Linux that you are using a gpio in that bank and that the bank should be enabled.

// end of am57xx-mitysom-baseboard.dtsi

&gpio2 {
    status = "okay"; 
    line_b {
        gpio-hog;
        gpios = <30 0>; 
        input;
        line-name = "foo-bar-gpio";
    };
};

The above would mark GPIO2_30 as in use. This gpio would not be available in Linux at user-level. The contents of /sys/kernel/debug/gpio will show the name foo-bar-gpio for this gpio.

Conclusion¶

Information about GPIOs has been provided indicating:

• How to convert ARM GPIO<bank>_<offset> notation to Linux gpio numbers.
• How to see which gpios are in use
• How to export a gpio for use in user-space
• How to verify that a gpio is working on the development board.
• How to change the kernel device tree so that a gpio is marked for usage by in the DSP and to make sure the bank is enabled.

C++ gpio helper classes can be provided upon request.