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