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