1.\" $OpenBSD: gpio.4,v 1.15 2008/11/27 14:15:02 jmc 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: November 27 2008 $ 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* ar glxpcib?" Pq i386 27.Cd "gpio* at gscpcib?" Pq i386 28.Cd "gpio* at isagpio?" 29.Cd "gpio* at nsclpcsio?" 30.Cd "gpio* at pcagpio?" 31.Cd "gpio* at pcaled?" 32.Pp 33.Fd #include <sys/types.h> 34.Fd #include <sys/gpio.h> 35.Fd #include <sys/ioctl.h> 36.Sh DESCRIPTION 37The 38.Nm 39device attaches to the GPIO 40controller and provides a uniform programming interface to its pins. 41.Pp 42Each GPIO controller with an attached 43.Nm 44device has an associated device file under the 45.Pa /dev 46directory, e.g.\& 47.Pa /dev/gpio0 . 48Access from userland is performed through 49.Xr ioctl 2 50calls on these devices. 51.Pp 52The layout of the GPIO device is defined at securelevel 0, i.e. typically 53during system boot, and cannot be changed later. 54GPIO pins can be configured and given a symbolic name and device drivers 55that use GPIO pins can be attached to the 56.Nm 57device at securelevel 0. 58All other pins will not be accessible once the runlevel has been raised. 59.Sh IOCTL INTERFACE 60The following structures and constants are defined in the 61.Aq Pa sys/gpio.h 62header file: 63.Bl -tag -width XXXX 64.It Dv GPIOINFO (struct gpio_info) 65Returns information about the GPIO 66controller in the 67.Fa gpio_info 68structure: 69.Bd -literal 70struct gpio_info { 71 int gpio_npins; /* total number of pins available */ 72}; 73.Ed 74.It Dv GPIOPINREAD (struct gpio_pin_op) 75Returns the input pin value in the 76.Fa gpio_pin_op 77structure: 78.Bd -literal 79#define GPIOPINMAXNAME 64 80 81struct gpio_pin_op { 82 char gp_name[GPIOPINMAXNAME]; /* pin name */ 83 int gp_pin; /* pin number */ 84 int gp_value; /* value */ 85}; 86.Ed 87.Pp 88The 89.Fa gp_name 90or 91.Fa gp_pin 92field must be set before calling. 93.It Dv GPIOPINWRITE (struct gpio_pin_op) 94Writes the output value to the pin. 95The value set in the 96.Fa gp_value 97field must be either 98.Dv GPIO_PIN_LOW 99(logical 0) or 100.Dv GPIO_PIN_HIGH 101(logical 1). 102On return, the 103.Fa gp_value 104field contains the old pin state. 105.It Dv GPIOPINTOGGLE (struct gpio_pin_op) 106Toggles the pin output value, i.e. changes it to the opposite. 107.Fa gp_value 108field is ignored and on return contains the old pin state. 109.It Dv GPIOPINSET (struct gpio_pin_set) 110Changes pin configuration flags with the new ones provided in the 111.Fa gpio_pin_set 112structure: 113.Bd -literal 114#define GPIOPINMAXNAME 64 115 116struct gpio_pin_set { 117 char gp_name[GPIOPINMAXNAME]; /* pin name */ 118 int gp_pin; /* pin number */ 119 int gp_caps; /* pin capabilities (ro) */ 120 int gp_flags; /* pin configuration flags */ 121 char gp_name2[GPIOPINMAXNAME]; /* new name */ 122}; 123.Ed 124.Pp 125The 126.Fa gp_flags 127field is a combination of the following flags: 128.Pp 129.Bl -tag -width GPIO_PIN_OPENDRAIN -compact 130.It Dv GPIO_PIN_INPUT 131input direction 132.It Dv GPIO_PIN_OUTPUT 133output direction 134.It Dv GPIO_PIN_INOUT 135bi-directional 136.It Dv GPIO_PIN_OPENDRAIN 137open-drain output 138.It Dv GPIO_PIN_PUSHPULL 139push-pull output 140.It Dv GPIO_PIN_TRISTATE 141output disabled 142.It Dv GPIO_PIN_PULLUP 143internal pull-up enabled 144.It Dv GPIO_PIN_PULLDOWN 145internal pull-down enabled 146.It Dv GPIO_PIN_INVIN 147invert input 148.It Dv GPIO_PIN_INVOUT 149invert output 150.El 151.Pp 152Note that the GPIO controller 153may not support all of these flags. 154On return the 155.Fa gp_caps 156field contains flags that are supported. 157If no flags are specified, the pin configuration stays unchanged. 158.Pp 159Only GPIO pins that have been set using 160.Ar GPIOPINSET 161will be accessible at securelevels greater than 0. 162.It Dv GPIOPINUNSET (struct gpio_pin_set) 163Unset the specified pin, i.e. clear its name and make it unaccessible 164at securelevels greater than 0. 165.It Dv GPIOATTACH (struct gpio_attach) 166Attach the device described in the 167.Fa gpio_attach 168structure on this gpio device. 169.Bd -literal 170struct gpio_attach { 171 char ga_dvname[16]; /* device name */ 172 int ga_offset; /* pin number */ 173 u_int32_t ga_mask; /* binary mask */ 174}; 175.Ed 176.It Dv GPIODETACH (struct gpio_attach) 177Detach a device from this gpio device that was previously attached using the 178.Dv GPIOATTACH 179.Xr ioctl 2 . 180The 181.Fa ga_offset 182and 183.Fa ga_mask 184fields of the 185.Fa gpio_attach 186structure are ignored. 187.El 188.Sh FILES 189.Bl -tag -width "/dev/gpiou" -compact 190.It /dev/gpio Ns Ar u 191GPIO device unit 192.Ar u 193file. 194.El 195.Sh SEE ALSO 196.Xr ioctl 2 , 197.Xr gpioctl 8 198.Sh HISTORY 199The 200.Nm 201device first appeared in 202.Ox 3.6 . 203.Sh AUTHORS 204The 205.Nm 206driver was written by 207.An Alexander Yurchenko Aq grange@openbsd.org . 208Runtime device attachment was added by 209.An Marc Balmer Aq mbalmer@openbsd.org . 210.Sh BUGS 211Event capabilities are not supported. 212