1.\" $NetBSD: gpio.4,v 1.35 2020/02/13 22:48:11 sevan 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 February 13, 2020 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 soekrisgpio?" 33.Cd "gpio* at ppbus?" 34.Cd "gpio* at ptcd?" 35.Cd "gpio* at wbsio?" 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 controller and provides a uniform 44programming 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 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 GPIO controller in the 78.Fa gpio_info 79structure: 80.Bd -literal 81struct gpio_info { 82 int gpio_npins; /* total number of pins available */ 83}; 84.Ed 85.Pp 86.It Dv GPIOREAD ( struct gpio_req ) 87Returns the input pin value in the 88.Fa gpio_pin_op 89structure: 90.Bd -literal 91#define GPIOMAXNAME 64 92 93struct gpio_req { 94 char gp_name[GPIOMAXNAME]; /* pin name */ 95 int gp_pin; /* pin number */ 96 int gp_value; /* value */ 97}; 98.Ed 99.Pp 100The 101.Fa gp_name 102or 103.Fa gp_pin 104field must be set before calling. 105If both are set, gp_name takes precedence. 106On return, the 107.Fa gp_name 108field contains the current name of the pin, if set by the controller driver 109or an earlier call to 110.Dv GPIOSET . 111.Pp 112.It Dv GPIOWRITE ( struct gpio_req ) 113Writes the output value to the pin. 114The value set in the 115.Fa gp_value 116field must be either 117.Dv GPIO_PIN_LOW 118(logical 0) or 119.Dv GPIO_PIN_HIGH 120(logical 1). 121On return, the 122.Fa gp_value 123field contains the old pin state. 124.Pp 125.It Dv GPIOTOGGLE ( struct gpio_req ) 126Toggles the pin output value, i.e. changes it to the opposite. 127.Fa gp_value 128field is ignored and on return contains the old pin state. 129.Pp 130.It Dv GPIOSET ( struct gpio_set ) 131Changes pin configuration flags with the new ones provided in the 132.Fa gpio_set 133structure: 134.Bd -literal 135#define GPIOMAXNAME 64 136 137struct gpio_set { 138 char gp_name[GPIOMAXNAME]; /* pin name */ 139 int gp_pin; /* pin number */ 140 int gp_caps; /* pin capabilities (ro) */ 141 int gp_flags; /* pin configuration flags */ 142 char gp_name2[GPIOMAXNAME]; /* new name */ 143}; 144.Ed 145.Pp 146The 147.Fa gp_flags 148field is a combination of the following flags: 149.Pp 150.Bl -tag -width GPIO_PIN_OPENDRAIN -compact 151.It Dv GPIO_PIN_INPUT 152input direction 153.It Dv GPIO_PIN_OUTPUT 154output direction 155.It Dv GPIO_PIN_INOUT 156bi-directional 157.It Dv GPIO_PIN_OPENDRAIN 158open-drain output 159.It Dv GPIO_PIN_PUSHPULL 160push-pull output 161.It Dv GPIO_PIN_TRISTATE 162output disabled 163.It Dv GPIO_PIN_PULLUP 164internal pull-up enabled 165.It Dv GPIO_PIN_PULLDOWN 166internal pull-down enabled 167.It Dv GPIO_PIN_INVIN 168invert input 169.It Dv GPIO_PIN_INVOUT 170invert output 171.It Dv GPIO_PIN_PULSATE 172pulsate output 173.It Dv GPIO_PIN_ALT0 - 174.It Dv GPIO_PIN_ALT7 175select alternate pin function 0 to 7 176.El 177.Pp 178Note that the GPIO controller 179may not support all of these flags. 180On return the 181.Fa gp_caps 182field contains flags that are supported. 183If no flags are specified, the pin configuration stays unchanged. 184.Pp 185Only GPIO pins that have been set using 186.Ar GPIOSET 187will be accessible at securelevels greater than 0. 188.Pp 189.It Dv GPIOUNSET ( struct gpio_set ) 190Unset the specified pin, i.e. clear its name and make it unaccessible 191at securelevels greater than 0. 192.Pp 193.It Dv GPIOATTACH ( struct gpio_attach ) 194Attach the device described in the 195.Fa gpio_attach 196structure on this gpio device. 197.Bd -literal 198struct gpio_attach { 199 char ga_dvname[16]; /* device name */ 200 int ga_offset; /* pin number */ 201 uint32_t ga_mask; /* binary mask */ 202 uint32_t ga_flags; /* driver dependent */ 203}; 204.Ed 205.Pp 206The 207.Xr drvctl 8 208command can be used to detach a device from a gpio pin. 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 drvctl 8 , 220.Xr gpioctl 8 221.Sh HISTORY 222The 223.Nm 224device first appeared in 225.Ox 3.6 226and 227.Nx 4.0 . 228.Sh AUTHORS 229.An -nosplit 230The 231.Nm 232driver was written by 233.An Alexander Yurchenko Aq Mt grange@openbsd.org . 234.Nm 235was ported to 236.Nx 237by 238.An Jared D. McNeill Aq Mt jmcneill@NetBSD.org . 239Runtime device attachment was added by 240.An Marc Balmer Aq Mt marc@msys.ch . 241.Sh BUGS 242Event capabilities are not supported. 243