1.\" $NetBSD: gpioctl.8,v 1.16 2011/11/13 14:39:42 mbalmer 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 November 13, 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 set 48.Op Ar flags 49.Op Ar name 50.Nm gpioctl 51.Op Fl q 52.Ar device 53.Ar pin 54.Cm unset 55.Sh DESCRIPTION 56The 57.Nm 58program allows manipulation of GPIO 59(General Purpose Input/Output) device pins. 60Such devices can be either part of the chipset or embedded CPU, 61or a separate chip. 62The usual way of using GPIO 63is to connect some simple devices such as LEDs and 1-wire thermal sensors 64to its pins. 65.Pp 66Each GPIO device has an associated device file in the 67.Pa /dev 68directory. 69.Ar device 70can be specified with or without the 71.Pa /dev 72prefix. 73For example, 74.Pa /dev/gpio0 75or 76.Pa gpio0 . 77.Pp 78GPIO pins can be either 79.Dq read 80or 81.Dq written 82with the values of logical 0 or 1. 83If only a 84.Ar pin 85number is specified on the command line, the pin state will be read 86from the GPIO controller and displayed. 87To write to a pin, a value must be specified after the 88.Ar pin 89number. 90Values can be either 0 or 1. 91A value of 2 92.Dq toggles 93the pin, i.e. changes its state to the opposite. 94Instead of the numerical values, the word 95.Ar on , 96.Ar off , 97or 98.Ar toggle 99can be used. 100.Pp 101To 102.Pp 103Only pins that have been configured at securelevel 0, typically during system 104startup, are accessible once the securelevel has been raised. 105Pins can be given symbolic names for easier use. 106Besides using individual pins, device drivers that use GPIO pins can be 107attached to a 108.Xr gpio 4 109device using the 110.Nm 111command. 112Such drivers can be detached at runtime using the 113.Xr drvctl 8 114command. 115.Pp 116The following configuration 117.Ar flags 118are supported by the GPIO framework: 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.It pulsate 142pulsate output at a hardware-defined frequency and duty cycle 143.El 144.Pp 145Note that not all the flags may be supported by the particular GPIO controller. 146.Pp 147When executed with only the 148.Xr gpio 4 149device name as argument, 150.Nm 151reads information about the 152.Tn GPIO 153device and displays it. 154At securelevel 0 the number of physically available pins is displayed, 155at higher securelevels the number of configured (set) pins is displayed. 156.Pp 157The options are as follows: 158.Bl -tag -width Ds 159.It Fl q 160Operate quietly i.e. nothing is printed to stdout. 161.El 162.Sh FILES 163.Bl -tag -width "/dev/gpiou" -compact 164.It /dev/gpio Ns Ar u 165GPIO device unit 166.Ar u 167file. 168.El 169.Sh EXAMPLES 170Configure pin 20 to have push-pull output: 171.Pp 172.Dl # gpioctl gpio0 20 set out pp 173.Pp 174Write logical 1 to pin 20: 175.Pp 176.Dl # gpioctl gpio0 20 1 177.Pp 178Attach a 179.Xr onewire 4 180bus on a 181.Xr gpioow 4 182device on pin 4: 183.Pp 184.Dl # gpioctl gpio0 attach gpioow 4 0x01 185.Pp 186Detach the gpioow0 device: 187.Pp 188.Dl # drvctl -d gpioow0 189.Pp 190Configure pin 5 as output and name it error_led: 191.Pp 192.Dl # gpioctl gpio0 5 set out error_led 193.Pp 194Toggle the error_led: 195.Pp 196.Dl # gpioctl gpio0 error_led 2 197.Sh SEE ALSO 198.Xr gpio 4 , 199.Xr drvctl 8 200.Sh HISTORY 201The 202.Nm 203command first appeared in 204.Ox 3.6 205and 206.Nx 4.0 . 207.Sh AUTHORS 208.An -nosplit 209The 210.Nm 211program was written by 212.An Alexander Yurchenko Aq grange@openbsd.org . 213Device attachment was added by 214.An Marc Balmer Aq marc@msys.ch . 215