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