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