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