xref: /netbsd/usr.sbin/gpioctl/gpioctl.8 (revision b1f2ec74) 
1.\" $NetBSD: gpioctl.8,v 1.24 2019/10/20 17:45:08 wiz Exp $
2.\"
3.\" Copyright (c) 2009, 2010, 2011, 2013 Marc Balmer <marc@msys.ch>
4.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org>
5.\"
6.\" Permission to use, copy, modify, and distribute this software for any
7.\" purpose with or without fee is hereby granted, provided that the above
8.\" copyright notice and this permission notice appear in all copies.
9.\"
10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17.\"
18.Dd October 20, 2019
19.Dt GPIOCTL 8
20.Os
21.Sh NAME
22.Nm gpioctl
23.Nd control GPIO devices
24.Sh SYNOPSIS
25.Nm gpioctl
26.Op Fl qs
27.Ar device
28.Nm gpioctl
29.Op Fl q
30.Ar device
31.Cm attach
32.Ar device
33.Ar offset
34.Ar mask
35.Op Ar flag
36.Nm gpioctl
37.Op Fl qs
38.Ar device
39.Ar pin
40.Op Ar 0 | 1 | 2
41.Nm gpioctl
42.Op Fl qs
43.Ar device
44.Ar pin
45.Op Ar on | off | toggle
46.Nm gpioctl
47.Op Fl q
48.Ar device
49.Ar pin
50.Cm set
51.Op Ar flags
52.Op Ar name
53.Nm gpioctl
54.Op Fl q
55.Ar device
56.Ar pin
57.Cm unset
58.Nm gpioctl
59.Op Fl q
60.Ar device
61.Ar list
62.Sh DESCRIPTION
63The
64.Nm
65program allows manipulation of GPIO
66(General Purpose Input/Output) device pins.
67Such devices can be either part of the chipset or embedded CPU,
68or a separate chip.
69The usual way of using GPIO
70is to connect some simple devices such as LEDs and 1-wire thermal sensors
71to its pins.
72.Pp
73Each GPIO device has an associated device file in the
74.Pa /dev
75directory.
76.Ar device
77can be specified with or without the
78.Pa /dev
79prefix.
80For example,
81.Pa /dev/gpio0
82or
83.Pa gpio0 .
84.Pp
85GPIO pins can be either
86.Dq read
87or
88.Dq written
89with the values of logical 0 or 1.
90If only a
91.Ar pin
92number is specified on the command line, the pin state will be read
93from the GPIO controller and displayed.
94To write to a pin, a value must be specified after the
95.Ar pin
96number.
97Values can be either 0 or 1.
98A value of 2
99.Dq toggles
100the pin, i.e. changes its state to the opposite.
101Instead of the numerical values, the word
102.Ar on ,
103.Ar off ,
104or
105.Ar toggle
106can be used.
107.Pp
108Only pins that have been configured at securelevel 0, typically during system
109startup, are accessible once the securelevel has been raised.
110Pins can be given symbolic names for easier use.
111Besides using individual pins, device drivers that use GPIO pins can be
112attached to a
113.Xr gpio 4
114device using the
115.Nm
116command.
117Such drivers can be detached at runtime using the
118.Xr drvctl 8
119command.
120.Pp
121The following configuration
122.Ar flags
123are supported by the GPIO framework:
124.Pp
125.Bl -tag -width Ds -offset indent -compact
126.It in
127input direction
128.It out
129output direction
130.It inout
131bi-directional
132.It od
133open-drain output
134.It pp
135push-pull output
136.It tri
137tri-state (output disabled)
138.It pu
139internal pull-up enabled
140.It pd
141internal pull-down enabled
142.It iin
143invert input
144.It iout
145invert output
146.It pulsate
147pulsate output at a hardware-defined frequency and duty cycle
148.It alt0 - alt7
149select alternate pin function 0 to 7
150.El
151.Pp
152Note that not all the flags may be supported by the particular GPIO controller.
153.Pp
154When executed with only the
155.Xr gpio 4
156device name as argument,
157.Nm
158reads information about the GPIO device and displays it.
159At securelevel 0 the number of physically available pins is displayed,
160at higher securelevels the number of configured (set) pins is displayed.
161.Pp
162The options are as follows:
163.Bl -tag -width Ds
164.It Fl q
165Operate quietly i.e. nothing is printed to stdout.
166.It Fl s
167Only output a single number on stdout, representing either the state of the
168pin or the number of available pins if no pin number was passed as argument.
169This option is useful e.g. when
170.Nm
171is used in shell scripts to query the state of a pin.
172.El
173.Sh FILES
174.Bl -tag -width "/dev/gpiou" -compact
175.It /dev/gpio Ns Ar u
176GPIO device unit
177.Ar u
178file.
179.El
180.Sh EXAMPLES
181Configure pin 20 to have push-pull output:
182.Pp
183.Dl # gpioctl gpio0 20 set out pp
184.Pp
185Write logical 1 to pin 20:
186.Pp
187.Dl # gpioctl gpio0 20 1
188.Pp
189Attach a
190.Xr onewire 4
191bus on a
192.Xr gpioow 4
193device on pin 4:
194.Pp
195.Dl # gpioctl gpio0 attach gpioow 4 0x01
196.Pp
197Detach the gpioow0 device:
198.Pp
199.Dl # drvctl -d  gpioow0
200.Pp
201Configure pin 5 as output and name it error_led:
202.Pp
203.Dl # gpioctl gpio0 5 set out error_led
204.Pp
205Toggle the error_led:
206.Pp
207.Dl # gpioctl gpio0 error_led 2
208.Pp
209Enumerate all pins and display their symbolic names:
210.Pp
211.Dl # gpioctl gpio0 list
212.Sh SEE ALSO
213.Xr gpio 4 ,
214.Xr drvctl 8
215.Sh HISTORY
216The
217.Nm
218command first appeared in
219.Ox 3.6
220and
221.Nx 4.0 .
222.Sh AUTHORS
223.An -nosplit
224The
225.Nm
226program was written by
227.An Alexander Yurchenko Aq Mt grange@openbsd.org .
228Device attachment was added by
229.An Marc Balmer Aq Mt marc@msys.ch .
230