Skip to content

Commit 06ea27d

Browse files
jonaswood01jonaswood01
committed
docs(GPIO): Updated Kernel driver doc with examples
Updates Linux Kernel GPIO doc with user space examples and resources. Adjusts formatting. Signed-off-by: Jonas Wood <[email protected]>
1 parent 09fa28c commit 06ea27d

File tree

3 files changed

+175
-21
lines changed

3 files changed

+175
-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: 175 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
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
3+
----
54
GPIO
6-
---------------------------------
5+
----
76

87
.. rubric:: GPIO Driver Overview
98
:name: gpio-driver-overview
@@ -48,33 +47,188 @@ and interrupt generation.
4847
.. rubric:: User Layer
4948
:name: user-layer
5049

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:
50+
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.
51+
52+
.. note ::
5553
56-
- GPIO Interface:
57-
Under Kernel directory Documentation/gpio/gpio.txt
58-
- GPIO Driver:
59-
Under Kernel directory Documentation/gpio/driver.txt
54+
Since Linux 4.8, the GPIO sysfs interface is deprecated. User space should use the character device instead.
6055
56+
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:
6157

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

66224
.. rubric:: Consuming Drivers
67225
:name: consuming-drivers
68226

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

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

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
231+
- 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.
78232

79233
|
80234

0 commit comments

Comments
 (0)