share/man/man4/gpio.4

   1 .\" $NetBSD: gpio.4,v 1.16 2009/09/27 17:55:32 jakllsch Exp $
   2 .\"     $OpenBSD: gpio.4,v 1.5 2004/11/23 09:39:29 reyk Exp $
   3 .\"
   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 27, 2009
  19 .Dt GPIO 4
  20 .Os
  21 .Sh NAME
  22 .Nm gpio
  23 .Nd General Purpose Input/Output
  24 .Sh SYNOPSIS
  25 .Cd "gpio* at elansc?"
  26 .Cd "gpio* at epgpio?"
  27 .Cd "gpio* at gcscpcib?"
  28 .Cd "gpio* at gpiosim?"
  29 .Cd "gpio* at gscpcib?"
  30 .Cd "gpio* at ichlpcib?"
  31 .Cd "gpio* at nsclpcsio?"
  32 .Cd "gpio* at ppbus?"
  33 .Pp
  34 .In sys/types.h
  35 .In sys/gpio.h
  36 .In sys/ioctl.h
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 device attaches to the
  41 .Tn GPIO
  42 controller and provides a uniform programming interface to its pins.
  43 .Pp
  44 Each
  45 .Tn GPIO
  46 controller with an attached
  47 .Nm
  48 device has an associated device file under the
  49 .Pa /dev
  50 directory, e.g.\&
  51 .Pa /dev/gpio0 .
  52 Access from userland is performed through
  53 .Xr ioctl 2
  54 calls on these devices.
  55 .Pp
  56 Whether the layout of the GPIO device can be configured is subject to
  57 authorization by the
  58 .Xr kauth 9
  59 framework.
  60 .Pp
  61 If for example
  62 .Xr secmodel_securelevel 9
  63 is active, the layout of the GPIO device is defined at a securelevel
  64 less than 1, i.e. typically during system boot, and cannot be changed later.
  65 GPIO pins can be configured and given a symbolic name and device drivers
  66 that use GPIO pins can be attached to the
  67 .Nm
  68 device at a securelevel less than 1.
  69 All other pins will not be accessible once the runlevel has been raised.
  70 .Sh IOCTL INTERFACE
  71 The following structures and constants are defined in the
  72 .Aq Pa sys/gpio.h
  73 header file:
  74 .Pp
  75 .Bl -tag -width XXXX -compact
  76 .It Dv GPIOINFO (struct gpio_info)
  77 Returns information about the
  78 .Tn GPIO
  79 controller in the
  80 .Fa gpio_info
  81 structure:
  82 .Bd -literal
  83 struct gpio_info {
  84         int gpio_npins;         /* total number of pins available */
  85 };
  86 .Ed
  87 .Pp
  88 .It Dv GPIOREAD (struct gpio_req)
  89 Returns the input pin value in the
  90 .Fa gpio_pin_op
  91 structure:
  92 .Bd -literal
  93 #define GPIOMAXNAME             64
  94
  95 struct gpio_req {
  96         char gp_name[GPIOMAXNAME];      /* pin name */
  97         int gp_pin;                     /* pin number */
  98         int gp_value;                   /* value */
  99 };
 100 .Ed
 101 .Pp
 102 The
 103 .Fa gp_name
 104 or
 105 .Fa gp_pin
 106 field must be set before calling.
 107 .Pp
 108 .It Dv GPIOWRITE (struct gpio_req)
 109 Writes the output value to the pin.
 110 The value set in the
 111 .Fa gp_value
 112 field must be either
 113 .Dv GPIO_PIN_LOW
 114 (logical 0) or
 115 .Dv GPIO_PIN_HIGH
 116 (logical 1).
 117 On return, the
 118 .Fa gp_value
 119 field contains the old pin state.
 120 .Pp
 121 .It Dv GPIOTOGGLE (struct gpio_req)
 122 Toggles the pin output value, i.e. changes it to the opposite.
 123 .Fa gp_value
 124 field is ignored and on return contains the old pin state.
 125 .Pp
 126 .It Dv GPIOSET (struct gpio_set)
 127 Changes pin configuration flags with the new ones provided in the
 128 .Fa gpio_set
 129 structure:
 130 .Bd -literal
 131 #define GPIOMAXNAME          64
 132
 133 struct gpio_set {
 134         char gp_name[GPIOMAXNAME];   /* pin name */
 135         int gp_pin;                     /* pin number */
 136         int gp_caps;                    /* pin capabilities (ro) */
 137         int gp_flags;                   /* pin configuration flags */
 138         char gp_name2[GPIOMAXNAME];  /* new name */
 139 };
 140 .Ed
 141 .Pp
 142 The
 143 .Fa gp_flags
 144 field is a combination of the following flags:
 145 .Pp
 146 .Bl -tag -width GPIO_PIN_OPENDRAIN -compact
 147 .It Dv GPIO_PIN_INPUT
 148 input direction
 149 .It Dv GPIO_PIN_OUTPUT
 150 output direction
 151 .It Dv GPIO_PIN_INOUT
 152 bi-directional
 153 .It Dv GPIO_PIN_OPENDRAIN
 154 open-drain output
 155 .It Dv GPIO_PIN_PUSHPULL
 156 push-pull output
 157 .It Dv GPIO_PIN_TRISTATE
 158 output disabled
 159 .It Dv GPIO_PIN_PULLUP
 160 internal pull-up enabled
 161 .It Dv GPIO_PIN_PULLDOWN
 162 internal pull-down enabled
 163 .It Dv GPIO_PIN_INVIN
 164 invert input
 165 .It Dv GPIO_PIN_INVOUT
 166 invert output
 167 .It Dv GPIO_PIN_PULSE
 168 pulse output
 169 .El
 170 .Pp
 171 Note that the GPIO controller
 172 may not support all of these flags.
 173 On return the
 174 .Fa gp_caps
 175 field contains flags that are supported.
 176 If no flags are specified, the pin configuration stays unchanged.
 177 .Pp
 178 Only GPIO pins that have been set using
 179 .Ar GPIOSET
 180 will be accessible at securelevels greater than 0.
 181 .Pp
 182 .It Dv GPIOUNSET (struct gpio_set)
 183 Unset the specified pin, i.e. clear its name and make it unaccessible
 184 at securelevels greater than 0.
 185 .Pp
 186 .It Dv GPIOATTACH (struct gpio_attach)
 187 Attach the device described in the
 188 .Fa gpio_attach
 189 structure on this gpio device.
 190 .Bd -literal
 191 struct gpio_attach {
 192         char ga_dvname[16];     /* device name */
 193         int ga_offset;          /* pin number */
 194         u_int32_t ga_mask;      /* binary mask */
 195 };
 196 .Ed
 197 .Pp
 198 .It Dv GPIODETACH (struct gpio_attach)
 199 Detach a device from this gpio device that was previously attached using the
 200 .Dv GPIOATTACH
 201 .Xr ioctl 2 .
 202 The
 203 .Fa ga_offset
 204 and
 205 .Fa ga_mask
 206 fields of the
 207 .Fa gpio_attach
 208 structure are ignored.
 209 .El
 210 .Sh FILES
 211 .Bl -tag -width "/dev/gpiou" -compact
 212 .It /dev/gpio Ns Ar u
 213 GPIO device unit
 214 .Ar u
 215 file.
 216 .El
 217 .Sh SEE ALSO
 218 .Xr ioctl 2 ,
 219 .Xr gpioctl 8
 220 .Sh HISTORY
 221 The
 222 .Nm
 223 device first appeared in
 224 .Ox 3.6
 225 and
 226 .Nx 4.0 .
 227 .Sh AUTHORS
 228 .An -nosplit
 229 The
 230 .Nm
 231 driver was written by
 232 .An Alexander Yurchenko Aq grange@openbsd.org .
 233 .Nm
 234 and was ported to
 235 .Nx
 236 by
 237 .An Jared D. McNeill Aq jmcneill@NetBSD.org .
 238 Runtime device attachment was added by
 239 .An Marc Balmer Aq marc@msys.ch .
 240 .Sh BUGS
 241 Event capabilities are not supported.