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