docs(GPIO): Updated Kernel driver doc with examples

FournierMx · jonaswood01 · commit 1eb41f7a21f9 · 2025-04-01T17:42:52.000-05:00
Replaced Debian links with lgpiod links and cleaned a lengthy URL.

Signed-off-by: Jonas Wood &lt;jonaslwood@gmail.com&gt;
diff --git a/source/android/Foundational_Components_Bootloaders.rst b/source/android/Foundational_Components_Bootloaders.rst
@@ -31,7 +31,7 @@ Fetch the code using ``repo``:
 .. code-block:: console
 
    $ mkdir ${YOUR_PATH}/ti-bootloader-aosp/ && cd $_
-   $ repo init -u https://git.ti.com/git/android/manifest.git -b android15-release -m releases/RLS_10_01_Bootloader.xml
+   $ repo init -u https://git.ti.com/git/android/manifest.git -b android15-release -m releases/RLS_10_01_01_Bootloader.xml
    $ repo sync
 
 For more information about ``repo``, visit `Android's official
diff --git a/source/android/Foundational_Components_Kernel.rst b/source/android/Foundational_Components_Kernel.rst
@@ -23,7 +23,7 @@ Fetch the code using ``repo``:
 .. code-block:: console
 
    $ mkdir ${YOUR_PATH}/ti-kernel-aosp/ && cd $_
-   $ repo init -u https://git.ti.com/git/android/manifest.git -b android15-release -m releases/RLS_10_01_Kernel-6.6.xml
+   $ repo init -u https://git.ti.com/git/android/manifest.git -b android15-release -m releases/RLS_10_01_01_Kernel.xml
    $ repo sync
 
 .. tip::
@@ -32,7 +32,7 @@ Fetch the code using ``repo``:
 
    .. code-block:: console
 
-      $ repo init -u https://git.ti.com/git/android/manifest.git -b android15-release -m releases/RLS_10_01_Kernel-6.6.xml --depth=1
+      $ repo init -u https://git.ti.com/git/android/manifest.git -b android15-release -m releases/RLS_10_01_01_Kernel.xml --depth=1
 
 .. _android-build-kernel:
 
diff --git a/source/android/Overview_Building_the_SDK.rst b/source/android/Overview_Building_the_SDK.rst
@@ -40,7 +40,7 @@ Fetch the code using ``repo``:
 .. code-block:: console
 
    $ mkdir ${YOUR_PATH}/ti-aosp-15 && cd $_
-   $ repo init -u https://git.ti.com/git/android/manifest.git -b android15-release -m releases/RLS_10_01.xml
+   $ repo init -u https://git.ti.com/git/android/manifest.git -b android15-release -m releases/RLS_10_01_01.xml
    $ repo sync
 
 .. tip::
diff --git a/source/images/sk-am62b-p1-top-2.png b/source/images/sk-am62b-p1-top-2.png
diff --git a/source/images/sk-am62b-p1-top.png b/source/images/sk-am62b-p1-top.png
diff --git 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,186 @@ 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:
-
--  GPIO Interface:
-   Under Kernel directory Documentation/gpio/gpio.txt
--  GPIO Driver:
-   Under Kernel directory Documentation/gpio/driver.txt
-
+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 ::
-   Since linux 4.8 the GPIO sysfs interface is deprecated. User space should use
+   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:
+
+#. 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
+
+#. 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' option 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: '^C' (Ctrl + C) interrupts the command, else the command would not terminate on its own. Use '^C' (Ctrl + C) to stop the command, and the new GPIO value will still remain.*
+
+- 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
+
+#. 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-<sdk version>/board-support/ti-linux-kernel-<kernel version>+git-ti/Documentation/devicetree/bindings/gpio/gpio.txt
+      - U-Boot: ti-processor-sdk-linux-am62xx-evm-<sdk version>/board-support/ti-u-boot-<u-boot version>+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-<sdk version>/board-support/ti-linux-kernel-<kernel version>+git-ti/arch/arm/boot/dts/ti/omap/am335x-bone-common.dtsi.
 
 |
 
