1.\" $NetBSD: gpio.4,v 1.22 2011/10/06 11:05:42 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 October 3, 2011 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 GPIOPULSE (struct gpio_pulse) 127Starts pulsing the pin: 128.Bd -literal 129/* GPIO pulse request */ 130struct gpio_pulse { 131 char gp_name[GPIOMAXNAME]; /* pin name */ 132 int gp_pin; /* pin number */ 133 struct timeval gp_pulse_on; /* "on" period */ 134 struct timeval gp_pulse_off; /* "off" period */ 135}; 136.Ed 137.Pp 138The 139.Fa gp_name 140or 141.Fa gp_pin 142field must be set before calling. 143If 144.Fa gp_pulse_on 145or 146.Fa gp_pulse_off 147is set to zero, a default of 148.Xr hz 9 / 2 149is assumed for both periods. 150.Pp 151.It Dv GPIOSET (struct gpio_set) 152Changes pin configuration flags with the new ones provided in the 153.Fa gpio_set 154structure: 155.Bd -literal 156#define GPIOMAXNAME 64 157 158struct gpio_set { 159 char gp_name[GPIOMAXNAME]; /* pin name */ 160 int gp_pin; /* pin number */ 161 int gp_caps; /* pin capabilities (ro) */ 162 int gp_flags; /* pin configuration flags */ 163 char gp_name2[GPIOMAXNAME]; /* new name */ 164}; 165.Ed 166.Pp 167The 168.Fa gp_flags 169field is a combination of the following flags: 170.Pp 171.Bl -tag -width GPIO_PIN_OPENDRAIN -compact 172.It Dv GPIO_PIN_INPUT 173input direction 174.It Dv GPIO_PIN_OUTPUT 175output direction 176.It Dv GPIO_PIN_INOUT 177bi-directional 178.It Dv GPIO_PIN_OPENDRAIN 179open-drain output 180.It Dv GPIO_PIN_PUSHPULL 181push-pull output 182.It Dv GPIO_PIN_TRISTATE 183output disabled 184.It Dv GPIO_PIN_PULLUP 185internal pull-up enabled 186.It Dv GPIO_PIN_PULLDOWN 187internal pull-down enabled 188.It Dv GPIO_PIN_INVIN 189invert input 190.It Dv GPIO_PIN_INVOUT 191invert output 192.It Dv GPIO_PIN_PULSE 193pulse output 194.El 195.Pp 196Note that the GPIO controller 197may not support all of these flags. 198On return the 199.Fa gp_caps 200field contains flags that are supported. 201If no flags are specified, the pin configuration stays unchanged. 202.Pp 203Only GPIO pins that have been set using 204.Ar GPIOSET 205will be accessible at securelevels greater than 0. 206.Pp 207.It Dv GPIOUNSET (struct gpio_set) 208Unset the specified pin, i.e. clear its name and make it unaccessible 209at securelevels greater than 0. 210.Pp 211.It Dv GPIOATTACH (struct gpio_attach) 212Attach the device described in the 213.Fa gpio_attach 214structure on this gpio device. 215.Bd -literal 216struct gpio_attach { 217 char ga_dvname[16]; /* device name */ 218 int ga_offset; /* pin number */ 219 uint32_t ga_mask; /* binary mask */ 220 uint32_t ga_flags; /* driver dependent */ 221}; 222.Ed 223.Pp 224The 225.Xr drvctl 8 226command can be used to detach a device from a gpio pin. 227.El 228.Sh FILES 229.Bl -tag -width "/dev/gpiou" -compact 230.It /dev/gpio Ns Ar u 231GPIO device unit 232.Ar u 233file. 234.El 235.Sh SEE ALSO 236.Xr ioctl 2 , 237.Xr drvctl 8 , 238.Xr gpioctl 8 239.Sh HISTORY 240The 241.Nm 242device first appeared in 243.Ox 3.6 244and 245.Nx 4.0 . 246.Sh AUTHORS 247.An -nosplit 248The 249.Nm 250driver was written by 251.An Alexander Yurchenko Aq grange@openbsd.org . 252.Nm 253and was ported to 254.Nx 255by 256.An Jared D. McNeill Aq jmcneill@NetBSD.org . 257Runtime device attachment was added by 258.An Marc Balmer Aq marc@msys.ch . 259.Sh BUGS 260Event capabilities are not supported. 261