Skip to content

Commit a735af5

Browse files
jonaswood01jonaswood01
committed
docs(Kernel_GPIO): Updated Kernel GPIO driver doc with examples and command-line tools
In response to the Linux Kernel GPIO in the SDK Docs feeling insufficient. So, this update walks someone through a quick example for using GPIO in user space and provides resources for command-line tools and additional guides.
1 parent 059c6c0 commit a735af5

File tree

3 files changed

+172
-21
lines changed

3 files changed

+172
-21
lines changed

‎source/images/sk-am62b-p1-top-2.png‎

1.2 MB
Loading

‎source/images/sk-am62b-p1-top.png‎

1.2 MB
Loading

‎source/linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO.rst‎

Lines changed: 172 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
1-
.. http://processors.wiki.ti.com/index.php/Processor_SDK_Linux_GPIO_Driver_Overview
2-
31
.. please note that there is no GPIO user guide from LCPD
42
53
GPIO
6-
---------------------------------
4+
----
75

86
.. rubric:: GPIO Driver Overview
97
:name: gpio-driver-overview
@@ -48,33 +46,186 @@ and interrupt generation.
4846
.. rubric:: User Layer
4947
:name: user-layer
5048

51-
The GPIO driver can be used via user space or by
52-
other drivers that may need to access pins as either input/outputs or
53-
interrupts. More information about this driver and GPIO usage in Linux
54-
can be found in the kernel documentation:
55-
56-
- GPIO Interface:
57-
Under Kernel directory Documentation/gpio/gpio.txt
58-
- GPIO Driver:
59-
Under Kernel directory Documentation/gpio/driver.txt
60-
49+
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.
6150

6251
.. note ::
63-
Since linux 4.8 the GPIO sysfs interface is deprecated. User space should use
52+
Since linux 4.8, the GPIO sysfs interface is deprecated. User space should use
6453
the character device instead.
6554
55+
# 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:
56+
57+
1. 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.
58+
59+
- 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:
60+
61+
.. Image:: /images/sk-am62b-p1-top.png
62+
63+
2. Detect every available **gpiochip**:
64+
65+
.. code-block:: console
66+
67+
$ gpiodetect
68+
gpiochip0 [600000.gpio] (92 lines)
69+
gpiochip1 [601000.gpio] (52 lines)
70+
gpiochip2 [1-0022] (24 lines)
71+
72+
- This shows 92+52+24=168 total GPIO lines available across 3 GPIO chips: 0, 1, and 2.
73+
74+
3. Read info for every available **gpiochip**:
75+
76+
.. code-block:: console
77+
78+
$ gpioinfo
79+
gpiochip0 - 92 lines:
80+
line 0: unnamed input
81+
line 1: unnamed input
82+
{...}
83+
line 91: unnamed input
84+
gpiochip1 - 52 lines:
85+
line 0: unnamed input
86+
line 1: unnamed input
87+
{...}
88+
line 51: unnamed input
89+
gpiochip2 - 24 lines:
90+
line 0: "GPIO_CPSW2_RST" input
91+
line 1: "GPIO_CPSW1_RST" input
92+
{...}
93+
line 23: "IO_EXP_TEST_LED" input
94+
95+
- 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.
96+
97+
- For more info on *gpioinfo*, see its man page: https://manpages.debian.org/experimental/gpiod/gpioinfo.1.en.html.
98+
99+
- To see info for a specific GPIO chip, use the '-c' option and the GPIO chip number.
100+
101+
4. Read info for **gpiochip2** (for this example):
102+
103+
.. code-block:: console
104+
105+
$ gpioinfo -c 2
106+
gpiochip2 - 24 lines:
107+
line 0: "GPIO_CPSW2_RST" input
108+
line 1: "GPIO_CPSW1_RST" input
109+
line 2: "PRU_DETECT" input
110+
line 3: "MMC1_SD_EN" output consumer="regulator-3"
111+
line 4: "VPP_LDO_EN" input
112+
line 5: "EXP_PS_3V3_En" input
113+
line 6: "EXP_PS_5V0_En" input
114+
line 7: "EXP_HAT_DETECT" input
115+
line 8: "GPIO_AUD_RSTn" input
116+
line 9: "GPIO_eMMC_RSTn" input
117+
line 10: "UART1_FET_BUF_EN" input
118+
line 11: "WL_LT_EN" input
119+
line 12: "GPIO_HDMI_RSTn" input
120+
line 13: "CSI_GPIO1" input
121+
line 14: "CSI_GPIO2" input
122+
line 15: "PRU_3V3_EN" input
123+
line 16: "HDMI_INTn" input consumer="interrupt"
124+
line 17: "PD_I2C_IRQ" input
125+
line 18: "MCASP1_FET_EN" input
126+
line 19: "MCASP1_BUF_BT_EN" input
127+
line 20: "MCASP1_FET_SEL" input
128+
line 21: "UART1_FET_SEL" input
129+
line 22: "TSINT#" input
130+
line 23: "IO_EXP_TEST_LED" output
131+
132+
- We see that **IO_EXP_TEST_LED** is connected to *GPIO2_23* on the SK-AM62B-P1 board.
133+
134+
5. Read the value of the GPIO pin:
135+
136+
.. code-block:: console
137+
138+
$ gpioget --numeric -c 2 23
139+
0
140+
141+
- Use variations of *gpioget* to read the value of the GPIO pin:
142+
143+
.. code-block:: console
144+
145+
$ gpioget -c 2 23
146+
"23"=inactive
147+
$ gpioget IO_EXP_TEST_LED
148+
"IO_EXP_TEST_LED"=inactive
149+
$ gpioget --numeric IO_EXP_TEST_LED
150+
0
151+
152+
- For more info on *gpioget*, see its man page: https://manpages.debian.org/experimental/gpiod/gpioget.1.en.html.
153+
154+
6. Set the GPIO pin to turn on the LED
155+
156+
.. code-block:: console
157+
158+
$ gpioset -c 2 23=1
159+
^C
160+
$ gpioset -c 2 23=0
161+
^C
162+
163+
- *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.*
164+
165+
- This should have turned the active-high LED "LD11" on the SK-AM62B-P1 on and off.
166+
167+
- Use variations of *gpioset* to set the value of the GPIO pin:
168+
169+
.. code-block:: console
170+
171+
$ gpioset IO_EXP_TEST_LED=1
172+
^C
173+
$ gpioset IO_EXP_TEST_LED=0
174+
^C
175+
176+
- This should have also turned the active-high LED "LD11" on the SK-AM62B-P1 on and off.
177+
178+
- Example: Toggle *GPIO2_23* (blink "LD11") at 10Hz, then turn it off:
179+
180+
.. code-block:: console
181+
182+
$ gpioset --toggle 50ms IO_EXP_TEST_LED=1
183+
^C
184+
$ gpioset IO_EXP_TEST_LED=0
185+
^C
186+
187+
- For more info on *gpioset*, see its man page: https://manpages.debian.org/experimental/gpiod/gpioset.1.en.html.
188+
189+
For more command-line tools, refer to the *libgpiod* documentation: https://libgpiod.readthedocs.io/en/latest/gpio_tools.html and the *gpiod* Debian documentation: https://manpages.debian.org/experimental/gpiod/index.html.
190+
191+
# Example: Using GPIOs on the Raspberry Pi Compatible 40-pin Header on the SK-AM62B-P1 board:
192+
193+
.. Image:: /images/sk-am62b-p1-top-2.png
194+
195+
1. 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.
196+
197+
2. Identify the desired GPIO pin number and pin multiplexed signal. For example, *GPIO1_25* corresponds to physical pin 8 on the 40-pin header.
198+
199+
3. Use *libgpiod* mentioned in the previous example to control the GPIO pin, ensuring that the GPIO pin is not being used already.
200+
201+
# Additional Resources
202+
203+
- For more information about GPIO usage in Linux and U-Boot, refer to these resources:
204+
205+
- SDK:
206+
207+
- Kernel: ti-processor-sdk-linux-am62xx-evm-<sdk version>/board-support/ti-linux-kernel-<kernel version>+git-ti/Documentation/devicetree/bindings/gpio/gpio.txt
208+
- 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
209+
210+
- Online:
211+
212+
- 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
213+
- 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
214+
- GPIO on Sitara: https://www.ti.com/lit/ab/spradk0/spradk0.pdf?ts=1743432396299&ref_url=https%253A%252F%252Fwww.google.com%252F
215+
- https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1398198/faq-am62x-how-to-allocate-use-gpios-from-different-device-domains
216+
- https://support.criticallink.com/redmine/projects/mitysom_am62x/wiki/Example\_-_User_level_GPIO_Access
217+
- 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
218+
- https://docs.kernel.org/devicetree/usage-model.html
219+
- (*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
220+
66221
.. rubric:: Consuming Drivers
67222
:name: consuming-drivers
68223

69-
The GPIO Driver can also be easily leveraged by other drivers to
70-
"consume" a GPIO.
224+
The GPIO Driver can also be easily leveraged by other drivers to "consume" a GPIO.
71225

72-
- GPIO Consumer:
73-
Under Kernel directory Documentation/gpio/consumer.txt
226+
- 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:
74227

75-
For an example of a driver using a GPIO pin, examine this entry in a dts
76-
file for how the MMC/SD interface could use a GPIO as a card detect pin
77-
Under Kernel directory arch/arm/boot/dts/am335x-bone-common.dtsi line 401
228+
- 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.
78229

79230
|
80231

0 commit comments

Comments
 (0)