usr.sbin/gpioctl/gpioctl.8

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