1.\" $OpenBSD: gpioctl.8,v 1.25 2018/03/12 12:52:14 jmc 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: March 12 2018 $ 18.Dt GPIOCTL 8 19.Os 20.Sh NAME 21.Nm gpioctl 22.Nd control GPIO devices 23.Sh SYNOPSIS 24.Nm gpioctl 25.Op Fl q 26.Ar device 27.Ar pin 28.Op Cm 0 | 1 | 2 | on | off | toggle 29.Nm gpioctl 30.Op Fl q 31.Ar device 32.Ar pin 33.Cm set 34.Op Ar flags 35.Op Ar name 36.Nm gpioctl 37.Op Fl q 38.Ar device 39.Ar pin 40.Cm unset 41.Nm gpioctl 42.Op Fl q 43.Ar device 44.Cm attach 45.Ar device 46.Ar offset 47.Ar mask 48.Op Ar flag 49.Nm gpioctl 50.Op Fl q 51.Ar device 52.Cm detach 53.Ar device 54.Sh DESCRIPTION 55The 56.Nm 57program allows manipulation of GPIO 58(General Purpose Input/Output) device pins. 59Such devices can be either part of the chipset or embedded CPU, 60or a separate chip. 61The usual way of using GPIO 62is to connect some simple devices such as LEDs and 1-wire thermal sensors 63to its pins. 64.Pp 65Each GPIO device has an associated device file in the 66.Pa /dev 67directory. 68.Ar device 69can be specified with or without the 70.Pa /dev 71prefix. 72For example, 73.Pa /dev/gpio0 74or 75.Pa gpio0 . 76.Pp 77GPIO pins can be either 78.Dq read 79or 80.Dq written 81with the values of logical 0 or 1. 82If only a 83.Ar pin 84number is specified on the command line, the pin state will be read 85from the GPIO controller and displayed. 86To write to a pin, a value must be specified after the 87.Ar pin 88number. 89Values can be either 90.Cm 0 91or 92.Cm 1 . 93A value of 94.Cm 2 95has a special meaning: it 96.Dq toggles 97the pin, i.e. changes its state to the opposite. 98Instead of the numerical values, the word 99.Cm on , 100.Cm off , 101or 102.Cm toggle 103can be used. 104.Pp 105Only pins that have been configured at securelevel 0, typically during system 106startup, are accessible once the securelevel has been raised. 107Pins can be given symbolic names for easier use. 108Besides using individual pins, device drivers that use GPIO pins can be 109attached to a 110.Xr gpio 4 111device using the 112.Nm 113command. 114.Pp 115The following configuration 116.Ar flags 117are supported by the GPIO framework. 118Note that not all the flags can be supported by the particular GPIO controller. 119.Pp 120.Bl -tag -width Ds -offset indent -compact 121.It in 122input direction 123.It out 124output direction 125.It inout 126bi-directional 127.It od 128open-drain output 129.It pp 130push-pull output 131.It tri 132tri-state (output disabled) 133.It pu 134internal pull-up enabled 135.It pd 136internal pull-down enabled 137.It iin 138invert input 139.It iout 140invert output 141.El 142.Pp 143When attaching an I2C device, 144if the 145.Ar flag 146argument is set to 1, 147the order of the SDA and SCL signals is reversed 148(see 149.Xr gpioiic 4 ) . 150.Pp 151When executed with only the 152.Xr gpio 4 153device name as argument, 154.Nm 155reads information about the GPIO device and displays it. 156At securelevel 0 the number of physically available pins is displayed, 157at higher securelevels the number of configured 158.Pq Cm set 159pins is displayed. 160.Pp 161The options are as follows: 162.Bl -tag -width Ds 163.It Fl q 164Operate quietly i.e. nothing is printed to stdout. 165.El 166.Sh FILES 167.Bl -tag -width "/dev/gpiou" -compact 168.It /dev/gpio Ns Ar u 169GPIO device unit 170.Ar u 171file. 172.El 173.Sh EXAMPLES 174Configure pin 20 to have push-pull output: 175.Pp 176.Dl # gpioctl gpio0 20 set out pp 177.Pp 178Write logical 1 to pin 20: 179.Pp 180.Dl # gpioctl gpio0 20 1 181.Pp 182Attach a 183.Xr onewire 4 184bus on a 185.Xr gpioow 4 186device on pin 4: 187.Pp 188.Dl # gpioctl gpio0 attach gpioow 4 0x01 189.Pp 190Detach the gpioow0 device: 191.Pp 192.Dl # gpioctl gpio0 detach gpioow0 193.Pp 194Configure pin 5 as output and name it error_led: 195.Pp 196.Dl # gpioctl gpio0 5 set out error_led 197.Pp 198Toggle the error_led: 199.Pp 200.Dl # gpioctl gpio0 error_led 2 201.Sh SEE ALSO 202.Xr gpio 4 203.Sh HISTORY 204The 205.Nm 206command first appeared in 207.Ox 3.6 . 208.Sh AUTHORS 209.An -nosplit 210The 211.Nm 212program was written by 213.An Alexander Yurchenko Aq Mt grange@openbsd.org . 214Device attachment was added by 215.An Marc Balmer Aq Mt mbalmer@openbsd.org . 216