1.\" $OpenBSD: gpioctl.8,v 1.23 2013/11/20 22:34:13 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: November 20 2013 $ 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 Ar 0 | 1 | 2 | on | off | toggle 29.Nm gpioctl 30.Op Fl q 31.Ar device 32.Ar pin 33set 34.Op Ar flags 35.Op Ar name 36.Nm gpioctl 37.Op Fl q 38.Ar device 39.Ar pin 40unset 41.Nm gpioctl 42.Op Fl q 43.Ar device 44attach 45.Ar device 46.Ar offset 47.Ar mask 48.Op Ar flag 49.Nm gpioctl 50.Op Fl q 51.Ar device 52detach 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 0 or 1. 90A value of 2 has a special meaning: it 91.Dq toggles 92the pin, i.e. changes its state to the opposite. 93Instead of the numerical values, the word 94.Ar on , 95.Ar off , 96or 97.Ar toggle 98can be used. 99.Pp 100Only pins that have been configured at securelevel 0, typically during system 101startup, are accessible once the securelevel has been raised. 102Pins can be given symbolic names for easier use. 103Besides using individual pins, device drivers that use GPIO pins can be 104attached to a 105.Xr gpio 4 106device using the 107.Nm 108command. 109.Pp 110The following configuration 111.Ar flags 112are supported by the GPIO framework. 113Note that not all the flags can be supported by the particular GPIO controller. 114.Pp 115.Bl -tag -width Ds -offset indent -compact 116.It in 117input direction 118.It out 119output direction 120.It inout 121bi-directional 122.It od 123open-drain output 124.It pp 125push-pull output 126.It tri 127tri-state (output disabled) 128.It pu 129internal pull-up enabled 130.It pd 131internal pull-down enabled 132.It iin 133invert input 134.It iout 135invert output 136.El 137.Pp 138When attaching an I2C device, 139if the 140.Ar flag 141argument is set to 0x01, 142the order of the SDA and SCL signals is reversed 143(see 144.Xr gpioiic 4 ) . 145.Pp 146When executed with only the 147.Xr gpio 4 148device name as argument, 149.Nm 150reads information about the 151.Tn GPIO 152device and displays it. 153At securelevel 0 the number of physically available pins is displayed, 154at higher securelevels the number of configured (set) pins is displayed. 155.Pp 156The options are as follows: 157.Bl -tag -width Ds 158.It Fl q 159Operate quietly i.e. nothing is printed to stdout. 160.El 161.Sh FILES 162.Bl -tag -width "/dev/gpiou" -compact 163.It /dev/gpio Ns Ar u 164GPIO device unit 165.Ar u 166file. 167.El 168.Sh EXAMPLES 169Configure pin 20 to have push-pull output: 170.Pp 171.Dl # gpioctl gpio0 20 set out pp 172.Pp 173Write logical 1 to pin 20: 174.Pp 175.Dl # gpioctl gpio0 20 1 176.Pp 177Attach a 178.Xr onewire 4 179bus on a 180.Xr gpioow 4 181device on pin 4: 182.Pp 183.Dl # gpioctl gpio0 attach gpioow 4 0x01 184.Pp 185Detach the gpioow0 device: 186.Pp 187.Dl # gpioctl gpio0 detach gpioow0 188.Pp 189Configure pin 5 as output and name it error_led: 190.Pp 191.Dl # gpioctl gpio0 5 set out error_led 192.Pp 193Toggle the error_led: 194.Pp 195.Dl # gpioctl gpio0 error_led 2 196.Sh SEE ALSO 197.Xr gpio 4 198.Sh HISTORY 199The 200.Nm 201command first appeared in 202.Ox 3.6 . 203.Sh AUTHORS 204.An -nosplit 205The 206.Nm 207program was written by 208.An Alexander Yurchenko Aq Mt grange@openbsd.org . 209Device attachment was added by 210.An Marc Balmer Aq Mt mbalmer@openbsd.org . 211