xref: /openbsd/share/man/man4/gpio.4 (revision cecf84d4) 
1.\"	$OpenBSD: gpio.4,v 1.23 2014/12/10 05:42:25 jsg Exp $
2.\"
3.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: December 10 2014 $
18.Dt GPIO 4
19.Os
20.Sh NAME
21.Nm gpio
22.Nd General Purpose Input/Output
23.Sh SYNOPSIS
24.Cd "gpio* at ath?"
25.Cd "gpio* at elansc?" Pq i386
26.Cd "gpio* at glxpcib?" Pq i386
27.Cd "gpio* at gscpcib?" Pq i386
28.Cd "gpio* at isagpio?"
29.Cd "gpio* at nsclpcsio?"
30.Cd "gpio* at omgpio?" Pq armv7
31.Cd "gpio* at pcagpio?"
32.Cd "gpio* at pcaled?"
33.Cd "gpio* at skgpio?" Pq amd64, i386
34.Cd "gpio0 at voyager?" Pq loongson
35.Pp
36.Fd #include <sys/types.h>
37.Fd #include <sys/gpio.h>
38.Fd #include <sys/ioctl.h>
39.Sh DESCRIPTION
40The
41.Nm
42device attaches to the GPIO
43controller and provides a uniform programming interface to its pins.
44.Pp
45Each GPIO controller with an attached
46.Nm
47device has an associated device file under the
48.Pa /dev
49directory, e.g.\&
50.Pa /dev/gpio0 .
51Access from userland is performed through
52.Xr ioctl 2
53calls on these devices.
54.Pp
55The layout of the GPIO device is defined at securelevel 0, i.e. typically
56during system boot, and cannot be changed later.
57GPIO pins can be configured and given a symbolic name and device drivers
58that use GPIO pins can be attached to the
59.Nm
60device at securelevel 0.
61All other pins will not be accessible once the runlevel has been raised.
62.Sh IOCTL INTERFACE
63The following structures and constants are defined in the
64.In sys/gpio.h
65header file:
66.Bl -tag -width XXXX
67.It Dv GPIOINFO (struct gpio_info)
68Returns information about the GPIO
69controller in the
70.Fa gpio_info
71structure:
72.Bd -literal
73struct gpio_info {
74	int gpio_npins;		/* total number of pins available */
75};
76.Ed
77.It Dv GPIOPINREAD (struct gpio_pin_op)
78Returns the input pin value in the
79.Fa gpio_pin_op
80structure:
81.Bd -literal
82#define GPIOPINMAXNAME		64
83
84struct gpio_pin_op {
85	char gp_name[GPIOPINMAXNAME];	/* pin name */
86	int gp_pin;			/* pin number */
87	int gp_value;			/* value */
88};
89.Ed
90.Pp
91The
92.Fa gp_name
93or
94.Fa gp_pin
95field must be set before calling.
96.It Dv GPIOPINWRITE (struct gpio_pin_op)
97Writes the output value to the pin.
98The value set in the
99.Fa gp_value
100field must be either
101.Dv GPIO_PIN_LOW
102(logical 0) or
103.Dv GPIO_PIN_HIGH
104(logical 1).
105On return, the
106.Fa gp_value
107field contains the old pin state.
108.It Dv GPIOPINTOGGLE (struct gpio_pin_op)
109Toggles the pin output value, i.e. changes it to the opposite.
110.Fa gp_value
111field is ignored and on return contains the old pin state.
112.It Dv GPIOPINSET (struct gpio_pin_set)
113Changes pin configuration flags with the new ones provided in the
114.Fa gpio_pin_set
115structure:
116.Bd -literal
117#define GPIOPINMAXNAME		64
118
119struct gpio_pin_set {
120	char gp_name[GPIOPINMAXNAME];	/* pin name */
121	int gp_pin;			/* pin number */
122	int gp_caps;			/* pin capabilities (ro) */
123	int gp_flags;			/* pin configuration flags */
124	char gp_name2[GPIOPINMAXNAME];	/* new name */
125};
126.Ed
127.Pp
128The
129.Fa gp_flags
130field is a combination of the following flags:
131.Pp
132.Bl -tag -width GPIO_PIN_OPENDRAIN -compact
133.It Dv GPIO_PIN_INPUT
134input direction
135.It Dv GPIO_PIN_OUTPUT
136output direction
137.It Dv GPIO_PIN_INOUT
138bi-directional
139.It Dv GPIO_PIN_OPENDRAIN
140open-drain output
141.It Dv GPIO_PIN_PUSHPULL
142push-pull output
143.It Dv GPIO_PIN_TRISTATE
144output disabled
145.It Dv GPIO_PIN_PULLUP
146internal pull-up enabled
147.It Dv GPIO_PIN_PULLDOWN
148internal pull-down enabled
149.It Dv GPIO_PIN_INVIN
150invert input
151.It Dv GPIO_PIN_INVOUT
152invert output
153.El
154.Pp
155Note that the GPIO controller
156may not support all of these flags.
157On return the
158.Fa gp_caps
159field contains flags that are supported.
160If no flags are specified, the pin configuration stays unchanged.
161.Pp
162Only GPIO pins that have been set using
163.Ar GPIOPINSET
164will be accessible at securelevels greater than 0.
165.It Dv GPIOPINUNSET (struct gpio_pin_set)
166Unset the specified pin, i.e. clear its name and make it inaccessible
167at securelevels greater than 0.
168.It Dv GPIOATTACH (struct gpio_attach)
169Attach the device described in the
170.Fa gpio_attach
171structure on this gpio device.
172.Bd -literal
173struct gpio_attach {
174	char ga_dvname[16];     /* device name */
175	int ga_offset;		/* pin number */
176	u_int32_t ga_mask;	/* binary mask */
177};
178.Ed
179.It Dv GPIODETACH (struct gpio_attach)
180Detach a device from this gpio device that was previously attached using the
181.Dv GPIOATTACH
182.Xr ioctl 2 .
183The
184.Fa ga_offset
185and
186.Fa ga_mask
187fields of the
188.Fa gpio_attach
189structure are ignored.
190.El
191.Sh FILES
192.Bl -tag -width "/dev/gpiou" -compact
193.It /dev/gpio Ns Ar u
194GPIO device unit
195.Ar u
196file.
197.El
198.Sh SEE ALSO
199.Xr ioctl 2 ,
200.Xr gpioctl 8
201.Sh HISTORY
202The
203.Nm
204device first appeared in
205.Ox 3.6 .
206.Sh AUTHORS
207.An -nosplit
208The
209.Nm
210driver was written by
211.An Alexander Yurchenko Aq Mt grange@openbsd.org .
212Runtime device attachment was added by
213.An Marc Balmer Aq Mt mbalmer@openbsd.org .
214.Sh BUGS
215Event capabilities are not supported.
216