Skip to content

Commit 1a6b96e

Browse files
jonaswood01praneethbajjuri
jonaswood01
authored and
praneethbajjuri
committed
docs(GPIO): Updates Kernel GPIO driver doc
Updates Linux Kernel GPIO doc with user space examples and resources. Adjusts formatting. Signed-off-by: Jonas Wood <[email protected]>
1 parent 59b142b commit 1a6b96e

File tree

3 files changed

+179
-21
lines changed

3 files changed

+179
-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: 179 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,192 @@ 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:
166+
167+
- 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.
168+
169+
- 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.
170+
171+
- This should have turned the active-high LED "LD11" on the SK-AM62B-P1 on and off.
172+
173+
- Use variations of *gpioset* to set the value of the GPIO pin:
174+
175+
.. code-block:: console
176+
177+
$ gpioset IO_EXP_TEST_LED=1
178+
^C
179+
$ gpioset IO_EXP_TEST_LED=0
180+
^C
181+
182+
- This should have also turned the active-high LED "LD11" on the SK-AM62B-P1 on and off.
183+
184+
- Example: Toggle *GPIO2_23* (blink "LD11") at 10Hz, then turn it off:
185+
186+
.. code-block:: console
187+
188+
$ gpioset --toggle 50ms IO_EXP_TEST_LED=1
189+
^C
190+
$ gpioset IO_EXP_TEST_LED=0
191+
^C
192+
193+
- For more info on *gpioset*, see its man page: https://libgpiod.readthedocs.io/en/latest/gpioset.html.
194+
195+
- For more command-line tools, refer to the *libgpiod* documentation: https://libgpiod.readthedocs.io/en/latest/gpio_tools.html.
196+
197+
Example: Using GPIOs on the Raspberry Pi Compatible 40-pin Header on the SK-AM62B-P1 board:
198+
199+
.. Image:: /images/sk-am62b-p1-top-2.png
200+
:width: 625
201+
202+
#. 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.
203+
204+
#. Identify the desired GPIO pin number and pin multiplexed signal. For example, *GPIO1_25* corresponds to physical pin 8 on the 40-pin header.
205+
206+
#. Use *libgpiod* mentioned in the previous example to control the GPIO pin, ensuring that the GPIO pin is not being used already.
207+
208+
Additional Resources
209+
210+
- For more information about GPIO usage in Linux and U-Boot, refer to these resources:
211+
212+
- SDK:
213+
214+
- Kernel: ti-processor-sdk-linux-am62xx-evm-<sdk version>/board-support/ti-linux-kernel-<kernel version>+git-ti/Documentation/devicetree/bindings/gpio/gpio.txt
215+
- 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
216+
217+
- Online:
218+
219+
- 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
220+
- 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
221+
- GPIO on Sitara: https://www.ti.com/lit/ab/spradk0/spradk0.pdf
222+
- https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1398198/faq-am62x-how-to-allocate-use-gpios-from-different-device-domains
223+
- https://support.criticallink.com/redmine/projects/mitysom_am62x/wiki/Example\_-_User_level_GPIO_Access
224+
- 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
225+
- https://docs.kernel.org/devicetree/usage-model.html
226+
- (*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
65227

66228
.. rubric:: Consuming Drivers
67229
:name: consuming-drivers
68230

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

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

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
235+
- 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.
78236

79237
|
80238

0 commit comments

Comments
 (0)