1*b1f2ec74Swiz.\" $NetBSD: gpioctl.8,v 1.24 2019/10/20 17:45:08 wiz Exp $ 2825ff184Sjmcneill.\" 3ed85705aSmbalmer.\" Copyright (c) 2009, 2010, 2011, 2013 Marc Balmer <marc@msys.ch> 4825ff184Sjmcneill.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org> 5825ff184Sjmcneill.\" 6825ff184Sjmcneill.\" Permission to use, copy, modify, and distribute this software for any 7825ff184Sjmcneill.\" purpose with or without fee is hereby granted, provided that the above 8825ff184Sjmcneill.\" copyright notice and this permission notice appear in all copies. 9825ff184Sjmcneill.\" 10825ff184Sjmcneill.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11825ff184Sjmcneill.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12825ff184Sjmcneill.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13825ff184Sjmcneill.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14825ff184Sjmcneill.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15825ff184Sjmcneill.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16825ff184Sjmcneill.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17825ff184Sjmcneill.\" 18d564a57eStnn.Dd October 20, 2019 19825ff184Sjmcneill.Dt GPIOCTL 8 20825ff184Sjmcneill.Os 21825ff184Sjmcneill.Sh NAME 22825ff184Sjmcneill.Nm gpioctl 23825ff184Sjmcneill.Nd control GPIO devices 24825ff184Sjmcneill.Sh SYNOPSIS 2532eeaba5Smbalmer.Nm gpioctl 261bdc60c3Smbalmer.Op Fl qs 271bdc60c3Smbalmer.Ar device 281bdc60c3Smbalmer.Nm gpioctl 2932eeaba5Smbalmer.Op Fl q 3032eeaba5Smbalmer.Ar device 317d98adacSwiz.Cm attach 3232eeaba5Smbalmer.Ar device 3332eeaba5Smbalmer.Ar offset 3432eeaba5Smbalmer.Ar mask 353b72c2b3Smbalmer.Op Ar flag 3632eeaba5Smbalmer.Nm gpioctl 371bdc60c3Smbalmer.Op Fl qs 3832eeaba5Smbalmer.Ar device 39825ff184Sjmcneill.Ar pin 4032eeaba5Smbalmer.Op Ar 0 | 1 | 2 4132eeaba5Smbalmer.Nm gpioctl 421bdc60c3Smbalmer.Op Fl qs 4332eeaba5Smbalmer.Ar device 4432eeaba5Smbalmer.Ar pin 4532eeaba5Smbalmer.Op Ar on | off | toggle 4632eeaba5Smbalmer.Nm gpioctl 47da668cdfSmbalmer.Op Fl q 48da668cdfSmbalmer.Ar device 49da668cdfSmbalmer.Ar pin 507d98adacSwiz.Cm set 51825ff184Sjmcneill.Op Ar flags 5232eeaba5Smbalmer.Op Ar name 5332eeaba5Smbalmer.Nm gpioctl 5432eeaba5Smbalmer.Op Fl q 5532eeaba5Smbalmer.Ar device 5632eeaba5Smbalmer.Ar pin 577d98adacSwiz.Cm unset 58d564a57eStnn.Nm gpioctl 59d564a57eStnn.Op Fl q 60d564a57eStnn.Ar device 61d564a57eStnn.Ar list 62825ff184Sjmcneill.Sh DESCRIPTION 63825ff184SjmcneillThe 64825ff184Sjmcneill.Nm 6532eeaba5Smbalmerprogram allows manipulation of GPIO 66825ff184Sjmcneill(General Purpose Input/Output) device pins. 6732eeaba5SmbalmerSuch devices can be either part of the chipset or embedded CPU, 68825ff184Sjmcneillor a separate chip. 6932eeaba5SmbalmerThe usual way of using GPIO 7032eeaba5Smbalmeris to connect some simple devices such as LEDs and 1-wire thermal sensors 7132eeaba5Smbalmerto its pins. 72825ff184Sjmcneill.Pp 7332eeaba5SmbalmerEach GPIO device has an associated device file in the 74825ff184Sjmcneill.Pa /dev 75825ff184Sjmcneilldirectory. 7632eeaba5Smbalmer.Ar device 7732eeaba5Smbalmercan be specified with or without the 7832eeaba5Smbalmer.Pa /dev 7932eeaba5Smbalmerprefix. 8032eeaba5SmbalmerFor example, 8132eeaba5Smbalmer.Pa /dev/gpio0 8232eeaba5Smbalmeror 8332eeaba5Smbalmer.Pa gpio0 . 84825ff184Sjmcneill.Pp 8532eeaba5SmbalmerGPIO pins can be either 86825ff184Sjmcneill.Dq read 87825ff184Sjmcneillor 88825ff184Sjmcneill.Dq written 89825ff184Sjmcneillwith the values of logical 0 or 1. 90825ff184SjmcneillIf only a 91825ff184Sjmcneill.Ar pin 92825ff184Sjmcneillnumber is specified on the command line, the pin state will be read 9332eeaba5Smbalmerfrom the GPIO controller and displayed. 94825ff184SjmcneillTo write to a pin, a value must be specified after the 95825ff184Sjmcneill.Ar pin 96825ff184Sjmcneillnumber. 97825ff184SjmcneillValues can be either 0 or 1. 98da668cdfSmbalmerA value of 2 99825ff184Sjmcneill.Dq toggles 100825ff184Sjmcneillthe pin, i.e. changes its state to the opposite. 10132eeaba5SmbalmerInstead of the numerical values, the word 10232eeaba5Smbalmer.Ar on , 10332eeaba5Smbalmer.Ar off , 10432eeaba5Smbalmeror 10532eeaba5Smbalmer.Ar toggle 10632eeaba5Smbalmercan be used. 107825ff184Sjmcneill.Pp 10832eeaba5SmbalmerOnly pins that have been configured at securelevel 0, typically during system 10932eeaba5Smbalmerstartup, are accessible once the securelevel has been raised. 11032eeaba5SmbalmerPins can be given symbolic names for easier use. 11132eeaba5SmbalmerBesides using individual pins, device drivers that use GPIO pins can be 11232eeaba5Smbalmerattached to a 11332eeaba5Smbalmer.Xr gpio 4 11432eeaba5Smbalmerdevice using the 11532eeaba5Smbalmer.Nm 11632eeaba5Smbalmercommand. 117dc2d28b2SmbalmerSuch drivers can be detached at runtime using the 118dc2d28b2Smbalmer.Xr drvctl 8 119dc2d28b2Smbalmercommand. 120825ff184Sjmcneill.Pp 12132eeaba5SmbalmerThe following configuration 12232eeaba5Smbalmer.Ar flags 12332eeaba5Smbalmerare supported by the GPIO framework: 12432eeaba5Smbalmer.Pp 12532eeaba5Smbalmer.Bl -tag -width Ds -offset indent -compact 126825ff184Sjmcneill.It in 127825ff184Sjmcneillinput direction 128825ff184Sjmcneill.It out 129825ff184Sjmcneilloutput direction 130825ff184Sjmcneill.It inout 131825ff184Sjmcneillbi-directional 132825ff184Sjmcneill.It od 133825ff184Sjmcneillopen-drain output 134825ff184Sjmcneill.It pp 135825ff184Sjmcneillpush-pull output 136825ff184Sjmcneill.It tri 137825ff184Sjmcneilltri-state (output disabled) 138825ff184Sjmcneill.It pu 139825ff184Sjmcneillinternal pull-up enabled 140cfebb94aSxtraeme.It pd 141cfebb94aSxtraemeinternal pull-down enabled 142cfebb94aSxtraeme.It iin 143cfebb94aSxtraemeinvert input 144cfebb94aSxtraeme.It iout 145cfebb94aSxtraemeinvert output 14698c90767Smbalmer.It pulsate 14798c90767Smbalmerpulsate output at a hardware-defined frequency and duty cycle 148847e3e85Smlelstv.It alt0 - alt7 149847e3e85Smlelstvselect alternate pin function 0 to 7 150825ff184Sjmcneill.El 151825ff184Sjmcneill.Pp 15232eeaba5SmbalmerNote that not all the flags may be supported by the particular GPIO controller. 153825ff184Sjmcneill.Pp 15432eeaba5SmbalmerWhen executed with only the 15532eeaba5Smbalmer.Xr gpio 4 15632eeaba5Smbalmerdevice name as argument, 157825ff184Sjmcneill.Nm 158*b1f2ec74Swizreads information about the GPIO device and displays it. 15932eeaba5SmbalmerAt securelevel 0 the number of physically available pins is displayed, 16032eeaba5Smbalmerat higher securelevels the number of configured (set) pins is displayed. 16132eeaba5Smbalmer.Pp 16232eeaba5SmbalmerThe options are as follows: 16332eeaba5Smbalmer.Bl -tag -width Ds 16432eeaba5Smbalmer.It Fl q 16532eeaba5SmbalmerOperate quietly i.e. nothing is printed to stdout. 1661bdc60c3Smbalmer.It Fl s 1671bdc60c3SmbalmerOnly output a single number on stdout, representing either the state of the 1681bdc60c3Smbalmerpin or the number of available pins if no pin number was passed as argument. 1691bdc60c3SmbalmerThis option is useful e.g. when 1701bdc60c3Smbalmer.Nm 1711bdc60c3Smbalmeris used in shell scripts to query the state of a pin. 17232eeaba5Smbalmer.El 173825ff184Sjmcneill.Sh FILES 174825ff184Sjmcneill.Bl -tag -width "/dev/gpiou" -compact 175825ff184Sjmcneill.It /dev/gpio Ns Ar u 176825ff184SjmcneillGPIO device unit 177825ff184Sjmcneill.Ar u 178825ff184Sjmcneillfile. 179825ff184Sjmcneill.El 180825ff184Sjmcneill.Sh EXAMPLES 181825ff184SjmcneillConfigure pin 20 to have push-pull output: 182825ff184Sjmcneill.Pp 18332eeaba5Smbalmer.Dl # gpioctl gpio0 20 set out pp 184825ff184Sjmcneill.Pp 185825ff184SjmcneillWrite logical 1 to pin 20: 186825ff184Sjmcneill.Pp 18732eeaba5Smbalmer.Dl # gpioctl gpio0 20 1 18832eeaba5Smbalmer.Pp 18932eeaba5SmbalmerAttach a 19032eeaba5Smbalmer.Xr onewire 4 19132eeaba5Smbalmerbus on a 19232eeaba5Smbalmer.Xr gpioow 4 19332eeaba5Smbalmerdevice on pin 4: 19432eeaba5Smbalmer.Pp 19532eeaba5Smbalmer.Dl # gpioctl gpio0 attach gpioow 4 0x01 19632eeaba5Smbalmer.Pp 19732eeaba5SmbalmerDetach the gpioow0 device: 19832eeaba5Smbalmer.Pp 199dc2d28b2Smbalmer.Dl # drvctl -d gpioow0 20032eeaba5Smbalmer.Pp 20132eeaba5SmbalmerConfigure pin 5 as output and name it error_led: 20232eeaba5Smbalmer.Pp 20332eeaba5Smbalmer.Dl # gpioctl gpio0 5 set out error_led 20432eeaba5Smbalmer.Pp 20532eeaba5SmbalmerToggle the error_led: 20632eeaba5Smbalmer.Pp 20732eeaba5Smbalmer.Dl # gpioctl gpio0 error_led 2 208d564a57eStnn.Pp 209d564a57eStnnEnumerate all pins and display their symbolic names: 210d564a57eStnn.Pp 211d564a57eStnn.Dl # gpioctl gpio0 list 212825ff184Sjmcneill.Sh SEE ALSO 213515e3b93Swiz.Xr gpio 4 , 214515e3b93Swiz.Xr drvctl 8 215825ff184Sjmcneill.Sh HISTORY 216825ff184SjmcneillThe 217825ff184Sjmcneill.Nm 218825ff184Sjmcneillcommand first appeared in 2193224a4d9Swiz.Ox 3.6 2203224a4d9Swizand 2213224a4d9Swiz.Nx 4.0 . 222825ff184Sjmcneill.Sh AUTHORS 2237d98adacSwiz.An -nosplit 224825ff184SjmcneillThe 225825ff184Sjmcneill.Nm 226825ff184Sjmcneillprogram was written by 227fb06f38bSwiz.An Alexander Yurchenko Aq Mt grange@openbsd.org . 228e680da6bSmbalmerDevice attachment was added by 229fb06f38bSwiz.An Marc Balmer Aq Mt marc@msys.ch . 230