Tool/software:
The objective of this FAQ is for someone with a TI EVM to enable using GPIOs in Linux. This guide will walk through how to setup a GPIO in the Linux Device Tree and how to toggle it in user space. This guide will also cover some common questions and issues someone may run into.
This applies to Linux SDK 10.0+ for AM64x, AM62x, AM62A, AM62P, AM62L.
TI EVMs have RPI headers that are exposed on the board which includes Main Domain GPIOs and some MCU GPIOs. Refer to the schematic of the TI EVM to see what pins are connected to the RPI header.
Refer to the common links to see the EVM product pages where the schematics can be found.
The RPI headers are usually labeled as "User Expansion Connector" and "MCU Header". Here is an example for SK-AM62B-P1:
Refer to the device's datasheet to see which signals can be used as GPIOs. Some pins are labeled for a different function, but still can be used as GPIOs.
Use this information to select a GPIO to use and then it can be enabled in the Linux device tree.
After the device tree is configured, compiled and loaded, the next step is to control the GPIO in userspace after the Linux kernel has booted. In userspace, we can use the GPIO SYSFS (deprecated) or the libgpiod command set. Important to note that you should only use one of these userspace methods, not both at the same time.
In later Linux SDK versions, its recommended to use Libgpiod userspace commands. This tool set and API are not written by TI so please refer to the Github repo: https://github.com/brgl/libgpiod
In the default Linux SDK, this is enabled, but refer to the menuconfig entry if needed:
As seen in the sample device tree, its recommended to add 'gpio-line-names' parameter in the device tree because it makes calling the GPIO in userspace easier. See below for an example of enabling GPIO0_38:
root@am62xx-evm:~# gpioset TEST_GPIO0_38=1 #use ctrl + c to send an interrupt to end the command root@am62xx-evm:~# gpioset -z TEST_GPIO0_38=1 #add the -z flag to daemonize the command
Just be aware when daemonizing the GPIO command, trying to change the GPIO again will return a 'Device or resource busy error' so kill the PID of the existing command.
In case a GPIO doesn't have a name, follow this process for GPIO0_38:
root@am62xx-evm:~# gpiodetect #run gpiodetect to understand how gpio modules are assigned to chips gpiochip0 [600000.gpio] (92 lines) gpiochip1 [601000.gpio] (52 lines) gpiochip2 [1-0022] (24 lines) root@am62xx-evm:~# gpioset --unquoted -c 0 38=1 #use ctrl + c to send an interrupt to end the command, unquoted will not search for gpio line names. root@am62xx-evm:~# gpioset --unquoted -z -c 0 38=1 #add the -z flag to daemonize the command
For the most up to date commands, refer to the man page for the GPIO command or use the --help flag.
For an example of using the libgpiod commands in Linux SDK versions 9.0 and prior, refer to this FAQ: https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1260373/faq-transitioning-the-gpio-userspace-interface-from-sysfs-to-chardev
GPIO SYSFS has been deprecated as noted in the Documentation: https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/Documentation/admin-guide/gpio/sysfs.rst?h=ti-linux-6.6.y
In the case that it needs to be re-enabled, refer to Kernel config below:
Once the kernel config is updated, refer to the Linux documentation for compiling a Kernel Image.
For this example, GPIO0_38 will be enabled. GPIO0's memory mapped address is 0x600000.
root@am62xx-evm:~# cd /sys/class/gpio/ root@am62xx-evm:/sys/class/gpio# ls -l total 0 --w------- 1 root root 4096 Feb 24 04:51 export lrwxrwxrwx 1 root root 0 Feb 24 04:51 gpiochip287 -> ../../devices/platform/bus@f0000/20010000.i2c/i2c-1/1-0022/gpio/gpiochip287 lrwxrwxrwx 1 root root 0 Feb 24 04:51 gpiochip311 -> ../../devices/platform/bus@f0000/601000.gpio/gpio/gpiochip311 lrwxrwxrwx 1 root root 0 Feb 24 04:51 gpiochip399 -> ../../devices/platform/bus@f0000/600000.gpio/gpio/gpiochip399 #Use for GPIO0 lrwxrwxrwx 1 root root 0 Feb 24 04:51 gpiochip486 -> ../../devices/platform/bus@f0000/bus@f0000:bus@4000000/4201000.gpio/gpio/gpiochip486 lrwxrwxrwx 1 root root 0 Feb 24 04:51 gpiochip510 -> ../../devices/platform/bus@f0000/3b000000.memory-controller/gpio/gpiochip510 --w------- 1 root root 4096 Feb 24 04:51 unexport root@am62xx-evm:/sys/class/gpio# echo 437 > export #GPIO0=399 + pin 38 = 437 root@am62xx-evm:/sys/class/gpio# cd gpio437 root@am62xx-evm:/sys/class/gpio/gpio437# echo out > direction root@am62xx-evm:/sys/class/gpio/gpio437# echo 1 > value
The first field is the PADCONFIG register address offset which is the last 3 hex bits defined in the device's TRM and datasheet. This tells Linux which pin these settings apply to.
The second field controls the input/output buffer which will be discussed in the next section. This does not define if a GPIO is input/output direction.
The third field is the Mux Mode of the pad. Typically, GPIOs use Mux Mode 7 but refer to the device's datasheet for complete information.
At a hardware level, for each pad on the SoC, there is a PADCONFIG register to control the settings of the Pad. See Pad Configuration Registers Section in the device's TRM for more information.
Each Pad as a Transceiver (Bit21) and Receiver (Bit18) buffer like the diagram below. By using the independent enable signals on each buffer, we can allow the pad to receive and/or transmit. These buffers allow the capability to receive and transmit data. This is true for most pads on the SoC, but refer to the datasheet for complete information.
So how does Linux configure the hardware? Refer to k3-pinctrl.h which defines the pin control bindings: https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/tree/arch/arm64/boot/dts/ti/k3-pinctrl.h?h=ti-linux-6.6.y
The definitions are the exact same as the PADCONFIG registers bit fields seen in the TRM Section named 'Pad Configuration Registers'. Linux will use PIN_INPUT/PIN_OUTPUT and any other parameters to configure the pin when Linux is booting.
#define PULLUDEN_SHIFT (16) #define PULLTYPESEL_SHIFT (17) #define RXACTIVE_SHIFT (18) #define DEBOUNCE_SHIFT (11) #define WKUP_EN_SHIFT (29) #define PULL_DISABLE (1 << PULLUDEN_SHIFT) #define PULL_ENABLE (0 << PULLUDEN_SHIFT) #define PULL_UP (1 << PULLTYPESEL_SHIFT | PULL_ENABLE) #define PULL_DOWN (0 << PULLTYPESEL_SHIFT | PULL_ENABLE) #define INPUT_EN (1 << RXACTIVE_SHIFT) #define INPUT_DISABLE (0 << RXACTIVE_SHIFT) /* Only these macros are expected be used directly in device tree files */ #define PIN_OUTPUT (INPUT_DISABLE | PULL_DISABLE) #define PIN_OUTPUT_PULLUP (INPUT_DISABLE | PULL_UP) #define PIN_OUTPUT_PULLDOWN (INPUT_DISABLE | PULL_DOWN) #define PIN_INPUT (INPUT_EN | PULL_DISABLE) #define PIN_INPUT_PULLUP (INPUT_EN | PULL_UP) #define PIN_INPUT_PULLDOWN (INPUT_EN | PULL_DOWN)
Notice the following:
This means in the device tree, PIN_INPUT means both the input buffer and the output buffer is enabled. PIN_OUTPUT means only the output buffer is enabled and input buffer is disabled. Remember, enabling the buffers allow for the functionality to receive and transmit on the pad.
This also means that configuring the PIN_INPUT/PIN_OUTPUT does not impact the GPIO state.
