1.\" $NetBSD: gpio.4,v 1.18 2010/03/22 18:58:31 joerg 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 September 27, 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 epgpio?" 27.Cd "gpio* at gcscpcib?" 28.Cd "gpio* at gpiosim?" 29.Cd "gpio* at gscpcib?" 30.Cd "gpio* at ichlpcib?" 31.Cd "gpio* at nsclpcsio?" 32.Cd "gpio* at ppbus?" 33.Pp 34.In sys/types.h 35.In sys/gpio.h 36.In sys/ioctl.h 37.Sh DESCRIPTION 38The 39.Nm 40device attaches to the 41.Tn GPIO 42controller and provides a uniform programming interface to its pins. 43.Pp 44Each 45.Tn GPIO 46controller 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 56Whether the layout of the GPIO device can be configured is subject to 57authorization by the 58.Xr kauth 9 59framework. 60.Pp 61If for example 62.Xr secmodel_securelevel 9 63is active, the layout of the GPIO device is defined at a securelevel 64less than 1, i.e. typically during system boot, and cannot be changed later. 65GPIO pins can be configured and given a symbolic name and device drivers 66that use GPIO pins can be attached to the 67.Nm 68device at a securelevel less than 1. 69All other pins will not be accessible once the runlevel has been raised. 70.Sh IOCTL INTERFACE 71The following structures and constants are defined in the 72.In sys/gpio.h 73header file: 74.Pp 75.Bl -tag -width XXXX -compact 76.It Dv GPIOINFO (struct gpio_info) 77Returns information about the 78.Tn GPIO 79controller in the 80.Fa gpio_info 81structure: 82.Bd -literal 83struct gpio_info { 84 int gpio_npins; /* total number of pins available */ 85}; 86.Ed 87.Pp 88.It Dv GPIOREAD (struct gpio_req) 89Returns the input pin value in the 90.Fa gpio_pin_op 91structure: 92.Bd -literal 93#define GPIOMAXNAME 64 94 95struct gpio_req { 96 char gp_name[GPIOMAXNAME]; /* pin name */ 97 int gp_pin; /* pin number */ 98 int gp_value; /* value */ 99}; 100.Ed 101.Pp 102The 103.Fa gp_name 104or 105.Fa gp_pin 106field must be set before calling. 107.Pp 108.It Dv GPIOWRITE (struct gpio_req) 109Writes the output value to the pin. 110The value set in the 111.Fa gp_value 112field must be either 113.Dv GPIO_PIN_LOW 114(logical 0) or 115.Dv GPIO_PIN_HIGH 116(logical 1). 117On return, the 118.Fa gp_value 119field contains the old pin state. 120.Pp 121.It Dv GPIOTOGGLE (struct gpio_req) 122Toggles the pin output value, i.e. changes it to the opposite. 123.Fa gp_value 124field is ignored and on return contains the old pin state. 125.Pp 126.It Dv GPIOSET (struct gpio_set) 127Changes pin configuration flags with the new ones provided in the 128.Fa gpio_set 129structure: 130.Bd -literal 131#define GPIOMAXNAME 64 132 133struct gpio_set { 134 char gp_name[GPIOMAXNAME]; /* pin name */ 135 int gp_pin; /* pin number */ 136 int gp_caps; /* pin capabilities (ro) */ 137 int gp_flags; /* pin configuration flags */ 138 char gp_name2[GPIOMAXNAME]; /* new name */ 139}; 140.Ed 141.Pp 142The 143.Fa gp_flags 144field is a combination of the following flags: 145.Pp 146.Bl -tag -width GPIO_PIN_OPENDRAIN -compact 147.It Dv GPIO_PIN_INPUT 148input direction 149.It Dv GPIO_PIN_OUTPUT 150output direction 151.It Dv GPIO_PIN_INOUT 152bi-directional 153.It Dv GPIO_PIN_OPENDRAIN 154open-drain output 155.It Dv GPIO_PIN_PUSHPULL 156push-pull output 157.It Dv GPIO_PIN_TRISTATE 158output disabled 159.It Dv GPIO_PIN_PULLUP 160internal pull-up enabled 161.It Dv GPIO_PIN_PULLDOWN 162internal pull-down enabled 163.It Dv GPIO_PIN_INVIN 164invert input 165.It Dv GPIO_PIN_INVOUT 166invert output 167.It Dv GPIO_PIN_PULSE 168pulse output 169.El 170.Pp 171Note that the GPIO controller 172may not support all of these flags. 173On return the 174.Fa gp_caps 175field contains flags that are supported. 176If no flags are specified, the pin configuration stays unchanged. 177.Pp 178Only GPIO pins that have been set using 179.Ar GPIOSET 180will be accessible at securelevels greater than 0. 181.Pp 182.It Dv GPIOUNSET (struct gpio_set) 183Unset the specified pin, i.e. clear its name and make it unaccessible 184at securelevels greater than 0. 185.Pp 186.It Dv GPIOATTACH (struct gpio_attach) 187Attach the device described in the 188.Fa gpio_attach 189structure on this gpio device. 190.Bd -literal 191struct gpio_attach { 192 char ga_dvname[16]; /* device name */ 193 int ga_offset; /* pin number */ 194 u_int32_t ga_mask; /* binary mask */ 195}; 196.Ed 197.Pp 198.It Dv GPIODETACH (struct gpio_attach) 199Detach a device from this gpio device that was previously attached using the 200.Dv GPIOATTACH 201.Xr ioctl 2 . 202The 203.Fa ga_offset 204and 205.Fa ga_mask 206fields of the 207.Fa gpio_attach 208structure are ignored. 209.El 210.Sh FILES 211.Bl -tag -width "/dev/gpiou" -compact 212.It /dev/gpio Ns Ar u 213GPIO device unit 214.Ar u 215file. 216.El 217.Sh SEE ALSO 218.Xr ioctl 2 , 219.Xr gpioctl 8 220.Sh HISTORY 221The 222.Nm 223device first appeared in 224.Ox 3.6 225and 226.Nx 4.0 . 227.Sh AUTHORS 228.An -nosplit 229The 230.Nm 231driver was written by 232.An Alexander Yurchenko Aq grange@openbsd.org . 233.Nm 234and was ported to 235.Nx 236by 237.An Jared D. McNeill Aq jmcneill@NetBSD.org . 238Runtime device attachment was added by 239.An Marc Balmer Aq marc@msys.ch . 240.Sh BUGS 241Event capabilities are not supported. 242