1.\" $NetBSD: gpioctl.8,v 1.7 2009/09/25 20:27:50 mbalmer Exp $ 2.\" 3.\" Copyright (c) 2009 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 September 25, 2009 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 28attach 29.Ar device 30.Ar offset 31.Ar mask 32.Nm gpioctl 33.Op Fl q 34.Ar device 35detach 36.Ar device 37.Nm gpioctl 38.Op Fl q 39.Ar device 40.Ar pin 41.Op Ar 0 | 1 | 2 42.Nm gpioctl 43.Op Fl q 44.Ar device 45.Ar pin 46.Op Ar on | off | toggle 47.Nm gpioctl 48.Op Fl q 49.Ar device 50.Ar pin 51set 52.Op Ar flags 53.Op Ar name 54.Nm gpioctl 55.Op Fl q 56.Ar device 57.Ar pin 58unset 59.Sh DESCRIPTION 60The 61.Nm 62program allows manipulation of GPIO 63(General Purpose Input/Output) device pins. 64Such devices can be either part of the chipset or embedded CPU, 65or a separate chip. 66The usual way of using GPIO 67is to connect some simple devices such as LEDs and 1-wire thermal sensors 68to its pins. 69.Pp 70Each GPIO device has an associated device file in the 71.Pa /dev 72directory. 73.Ar device 74can be specified with or without the 75.Pa /dev 76prefix. 77For example, 78.Pa /dev/gpio0 79or 80.Pa gpio0 . 81.Pp 82GPIO pins can be either 83.Dq read 84or 85.Dq written 86with the values of logical 0 or 1. 87If only a 88.Ar pin 89number is specified on the command line, the pin state will be read 90from the GPIO controller and displayed. 91To write to a pin, a value must be specified after the 92.Ar pin 93number. 94Values can be either 0 or 1. 95A value of 2 has a special meaning: it 96.Dq toggles 97the pin, i.e. changes its state to the opposite. 98Instead of the numerical values, the word 99.Ar on , 100.Ar off , 101or 102.Ar toggle 103can be used. 104.Pp 105Only pins that have been configured at securelevel 0, typically during system 106startup, are accessible once the securelevel has been raised. 107Pins can be given symbolic names for easier use. 108Besides using individual pins, device drivers that use GPIO pins can be 109attached to a 110.Xr gpio 4 111device using the 112.Nm 113command. 114.Pp 115The following configuration 116.Ar flags 117are supported by the GPIO framework: 118.Pp 119.Bl -tag -width Ds -offset indent -compact 120.It in 121input direction 122.It out 123output direction 124.It inout 125bi-directional 126.It od 127open-drain output 128.It pp 129push-pull output 130.It tri 131tri-state (output disabled) 132.It pu 133internal pull-up enabled 134.It pd 135internal pull-down enabled 136.It iin 137invert input 138.It iout 139invert output 140.It pulsate 141pulsate output at a hardware-defined frequency and duty cycle 142.El 143.Pp 144Note that not all the flags may be supported by the particular GPIO controller. 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 203and 204.Nx 4.0 . 205.Sh AUTHORS 206The 207.Nm 208program was written by 209.An Alexander Yurchenko Aq grange@openbsd.org . 210Device attachment was added by 211.An Marc Balmer Aq marc@msys.ch . 212