1.\" $NetBSD: gpioctl.8,v 1.20 2014/03/18 18:20:46 riastradh Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011, 2013 Marc Balmer <marc@msys.ch> 4.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd May 19, 2013 19.Dt GPIOCTL 8 20.Os 21.Sh NAME 22.Nm gpioctl 23.Nd control GPIO devices 24.Sh SYNOPSIS 25.Nm gpioctl 26.Op Fl qs 27.Ar device 28.Nm gpioctl 29.Op Fl q 30.Ar device 31.Cm attach 32.Ar device 33.Ar offset 34.Ar mask 35.Op Ar flag 36.Nm gpioctl 37.Op Fl qs 38.Ar device 39.Ar pin 40.Op Ar 0 | 1 | 2 41.Nm gpioctl 42.Op Fl qs 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 50.Cm set 51.Op Ar flags 52.Op Ar name 53.Nm gpioctl 54.Op Fl q 55.Ar device 56.Ar pin 57.Cm unset 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 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. 113Such drivers can be detached at runtime using the 114.Xr drvctl 8 115command. 116.Pp 117The following configuration 118.Ar flags 119are supported by the GPIO framework: 120.Pp 121.Bl -tag -width Ds -offset indent -compact 122.It in 123input direction 124.It out 125output direction 126.It inout 127bi-directional 128.It od 129open-drain output 130.It pp 131push-pull output 132.It tri 133tri-state (output disabled) 134.It pu 135internal pull-up enabled 136.It pd 137internal pull-down enabled 138.It iin 139invert input 140.It iout 141invert output 142.It pulsate 143pulsate output at a hardware-defined frequency and duty cycle 144.El 145.Pp 146Note that not all the flags may be supported by the particular GPIO controller. 147.Pp 148When executed with only the 149.Xr gpio 4 150device name as argument, 151.Nm 152reads information about the 153.Tn GPIO 154device and displays it. 155At securelevel 0 the number of physically available pins is displayed, 156at higher securelevels the number of configured (set) pins is displayed. 157.Pp 158The options are as follows: 159.Bl -tag -width Ds 160.It Fl q 161Operate quietly i.e. nothing is printed to stdout. 162.It Fl s 163Only output a single number on stdout, representing either the state of the 164pin or the number of available pins if no pin number was passed as argument. 165This option is useful e.g. when 166.Nm 167is used in shell scripts to query the state of a pin. 168.El 169.Sh FILES 170.Bl -tag -width "/dev/gpiou" -compact 171.It /dev/gpio Ns Ar u 172GPIO device unit 173.Ar u 174file. 175.El 176.Sh EXAMPLES 177Configure pin 20 to have push-pull output: 178.Pp 179.Dl # gpioctl gpio0 20 set out pp 180.Pp 181Write logical 1 to pin 20: 182.Pp 183.Dl # gpioctl gpio0 20 1 184.Pp 185Attach a 186.Xr onewire 4 187bus on a 188.Xr gpioow 4 189device on pin 4: 190.Pp 191.Dl # gpioctl gpio0 attach gpioow 4 0x01 192.Pp 193Detach the gpioow0 device: 194.Pp 195.Dl # drvctl -d gpioow0 196.Pp 197Configure pin 5 as output and name it error_led: 198.Pp 199.Dl # gpioctl gpio0 5 set out error_led 200.Pp 201Toggle the error_led: 202.Pp 203.Dl # gpioctl gpio0 error_led 2 204.Sh SEE ALSO 205.Xr gpio 4 , 206.Xr drvctl 8 207.Sh HISTORY 208The 209.Nm 210command first appeared in 211.Ox 3.6 212and 213.Nx 4.0 . 214.Sh AUTHORS 215.An -nosplit 216The 217.Nm 218program was written by 219.An Alexander Yurchenko Aq Mt grange@openbsd.org . 220Device attachment was added by 221.An Marc Balmer Aq Mt marc@msys.ch . 222