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