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