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