diff --git a/source/images/sk-am62b-p1-top-2.png b/source/images/sk-am62b-p1-top-2.png new file mode 100644 index 000000000..ee8ff234c Binary files /dev/null and b/source/images/sk-am62b-p1-top-2.png differ diff --git a/source/images/sk-am62b-p1-top.png b/source/images/sk-am62b-p1-top.png new file mode 100644 index 000000000..c4680380c Binary files /dev/null and b/source/images/sk-am62b-p1-top.png differ diff --git a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO.rst b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO.rst index 268b9b286..677b3ae0c 100644 --- a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO.rst +++ b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO.rst @@ -1,9 +1,8 @@ -.. http://processors.wiki.ti.com/index.php/Processor_SDK_Linux_GPIO_Driver_Overview - .. please note that there is no GPIO user guide from LCPD +---- GPIO ---------------------------------- +---- .. rubric:: GPIO Driver Overview :name: gpio-driver-overview @@ -48,33 +47,192 @@ and interrupt generation. .. rubric:: User Layer :name: user-layer -The GPIO driver can be used via user space or by -other drivers that may need to access pins as either input/outputs or -interrupts. More information about this driver and GPIO usage in Linux -can be found in the kernel documentation: +The GPIO driver can be used in user space via Linux CLI. This section provides examples, command-line-tools, and guidance for using GPIOs in user space. + +.. note :: -- GPIO Interface: - Under Kernel directory Documentation/gpio/gpio.txt -- GPIO Driver: - Under Kernel directory Documentation/gpio/driver.txt + Since Linux 4.8, the GPIO sysfs interface is deprecated. User space should use the character device instead. +Example: Using GPIOs with the *libgpiod* library in user space to toggle a GPIO pin, which is connected to an LED on the SK-AM62B-P1 board: -.. note :: - Since linux 4.8 the GPIO sysfs interface is deprecated. User space should use - the character device instead. +#. Locate *Table 2-23* under **2.6.16.3 User Test LEDs** in the *AM62x Starter Kit User's Guide (Rev. C)*: https://www.ti.com/lit/pdf/spruj40. + + - This example uses LED "LD11", AKA the **IO_EXP_TEST_LED**. It is connected to GPIO *U70.24(P27)*, AKA pin 27 of the *GPIO Port Expander* on the SK-AM62B-P1 board: + + .. Image:: /images/sk-am62b-p1-top.png + :width: 625 + +#. Detect every available **gpiochip**: + + .. code-block:: console + + $ gpiodetect + gpiochip0 [600000.gpio] (92 lines) + gpiochip1 [601000.gpio] (52 lines) + gpiochip2 [1-0022] (24 lines) + + - This shows 92+52+24=168 total GPIO lines available across 3 GPIO chips: 0, 1, and 2. + +#. Read info for every available **gpiochip**: + + .. code-block:: console + + $ gpioinfo + gpiochip0 - 92 lines: + line 0: unnamed input + line 1: unnamed input + {...} + line 91: unnamed input + gpiochip1 - 52 lines: + line 0: unnamed input + line 1: unnamed input + {...} + line 51: unnamed input + gpiochip2 - 24 lines: + line 0: "GPIO_CPSW2_RST" input + line 1: "GPIO_CPSW1_RST" input + {...} + line 23: "IO_EXP_TEST_LED" input + + - This should result in a large output, 168+ lines in this case. It outputs all GPIO lines available on every GPIO chip, as well as their names and input/output directions. The above output is truncated. + + - For more info on *gpioinfo*, see its man page: https://libgpiod.readthedocs.io/en/latest/gpioinfo.html. + + - To see info for a specific GPIO chip, use the '-c' flag and the GPIO chip number. + +#. Read info for **gpiochip2** (for this example): + + .. code-block:: console + + $ gpioinfo -c 2 + gpiochip2 - 24 lines: + line 0: "GPIO_CPSW2_RST" input + line 1: "GPIO_CPSW1_RST" input + line 2: "PRU_DETECT" input + line 3: "MMC1_SD_EN" output consumer="regulator-3" + line 4: "VPP_LDO_EN" input + line 5: "EXP_PS_3V3_En" input + line 6: "EXP_PS_5V0_En" input + line 7: "EXP_HAT_DETECT" input + line 8: "GPIO_AUD_RSTn" input + line 9: "GPIO_eMMC_RSTn" input + line 10: "UART1_FET_BUF_EN" input + line 11: "WL_LT_EN" input + line 12: "GPIO_HDMI_RSTn" input + line 13: "CSI_GPIO1" input + line 14: "CSI_GPIO2" input + line 15: "PRU_3V3_EN" input + line 16: "HDMI_INTn" input consumer="interrupt" + line 17: "PD_I2C_IRQ" input + line 18: "MCASP1_FET_EN" input + line 19: "MCASP1_BUF_BT_EN" input + line 20: "MCASP1_FET_SEL" input + line 21: "UART1_FET_SEL" input + line 22: "TSINT#" input + line 23: "IO_EXP_TEST_LED" output + + - We see that **IO_EXP_TEST_LED** is connected to *GPIO2_23* on the SK-AM62B-P1 board. + +#. Read the value of the GPIO pin: + + .. code-block:: console + + $ gpioget --numeric -c 2 23 + 0 + + - Use variations of *gpioget* to read the value of the GPIO pin: + + .. code-block:: console + + $ gpioget -c 2 23 + "23"=inactive + $ gpioget IO_EXP_TEST_LED + "IO_EXP_TEST_LED"=inactive + $ gpioget --numeric IO_EXP_TEST_LED + 0 + + - For more info on *gpioget*, see its man page: https://libgpiod.readthedocs.io/en/latest/gpioget.html. + +#. Set the GPIO pin to turn on the LED + + .. code-block:: console + + $ gpioset -c 2 23=1 + ^C + $ gpioset -c 2 23=0 + ^C + + - Note: + + - In Bash, *'^C' (Ctrl + C)* exits the command with *SIGINT*, else the *gpioset* command would not exit on its own. For more info, refer to the *3.7.6 Signals* section in the GNU Bash manual: https://www.gnu.org/software/bash/manual/bash.html. + + - The new GPIO value will remain until an exit signal, like *SIGKILL*, *SIGTERM*, or *SIGINT*; after that, its value is not guaranteed. For more info, reference the *Description* section of the *gpioset* man page: https://libgpiod.readthedocs.io/en/latest/gpioset.html. + + - This should have turned the active-high LED "LD11" on the SK-AM62B-P1 on and off. + + - Use variations of *gpioset* to set the value of the GPIO pin: + + .. code-block:: console + + $ gpioset IO_EXP_TEST_LED=1 + ^C + $ gpioset IO_EXP_TEST_LED=0 + ^C + + - This should have also turned the active-high LED "LD11" on the SK-AM62B-P1 on and off. + + - Example: Toggle *GPIO2_23* (blink "LD11") at 10Hz, then turn it off: + + .. code-block:: console + + $ gpioset --toggle 50ms IO_EXP_TEST_LED=1 + ^C + $ gpioset IO_EXP_TEST_LED=0 + ^C + + - For more info on *gpioset*, see its man page: https://libgpiod.readthedocs.io/en/latest/gpioset.html. + +- For more command-line tools, refer to the *libgpiod* documentation: https://libgpiod.readthedocs.io/en/latest/gpio_tools.html. + +Example: Using GPIOs on the Raspberry Pi Compatible 40-pin Header on the SK-AM62B-P1 board: + +.. Image:: /images/sk-am62b-p1-top-2.png + :width: 625 + +#. Locate *Table 2-25* under **2.6.17.2 User Expansion Connector** in the *AM62x Starter Kit User's Guide (Rev. C)*: https://www.ti.com/lit/pdf/spruj40. + +#. Identify the desired GPIO pin number and pin multiplexed signal. For example, *GPIO1_25* corresponds to physical pin 8 on the 40-pin header. + +#. Use *libgpiod* mentioned in the previous example to control the GPIO pin, ensuring that the GPIO pin is not being used already. + +Additional Resources + +- For more information about GPIO usage in Linux and U-Boot, refer to these resources: + + - SDK: + + - Kernel: ti-processor-sdk-linux-am62xx-evm-/board-support/ti-linux-kernel-+git-ti/Documentation/devicetree/bindings/gpio/gpio.txt + - U-Boot: ti-processor-sdk-linux-am62xx-evm-/board-support/ti-u-boot-+git/doc/device-tree-bindings/gpio/gpio.txt + + - Online: + + - Linux: https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1494485/faq-processor-sdk-getting-started-with-gpios-in-linux-using-the-am62-and-am64-family-processors + - U-Boot: https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1398803/faq-processor-sdk-am62x-how-to-toggle-gpios-and-leds-from-u-boot-command-prompt + - GPIO on Sitara: https://www.ti.com/lit/ab/spradk0/spradk0.pdf + - https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1398198/faq-am62x-how-to-allocate-use-gpios-from-different-device-domains + - https://support.criticallink.com/redmine/projects/mitysom_am62x/wiki/Example\_-_User_level_GPIO_Access + - https://software-dl.ti.com/processor-sdk-linux/esd/AM64X/10_01_10_04/exports/docs/linux/How_to_Guides/FAQ/How_to_Check_Device_Tree_Info.html + - https://docs.kernel.org/devicetree/usage-model.html + - (*Note: AM62P-specific, but similar to AM62x*): https://software-dl.ti.com/processor-sdk-linux/esd/AM62PX/09_02_01_09/exports/docs/linux/Foundational_Components/Tools/GPIO_Tools.html .. rubric:: Consuming Drivers :name: consuming-drivers -The GPIO Driver can also be easily leveraged by other drivers to -"consume" a GPIO. +The GPIO Driver can also be easily leveraged by other drivers to "consume" a GPIO. -- GPIO Consumer: - Under Kernel directory Documentation/gpio/consumer.txt +- For an example of a driver using a GPIO pin, examine this entry in a dts file for how the MMC/SD interface could use a GPIO as a card detect pin: -For an example of a driver using a GPIO pin, examine this entry in a dts -file for how the MMC/SD interface could use a GPIO as a card detect pin -Under Kernel directory arch/arm/boot/dts/am335x-bone-common.dtsi line 401 + - ti-processor-sdk-linux-am62xx-evm-/board-support/ti-linux-kernel-+git-ti/arch/arm/boot/dts/ti/omap/am335x-bone-common.dtsi. |