share/man/man4/gpio.4

   1 .\" Copyright (c) 2013, Sean Bruno <sbruno@freebsd.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd September 13, 2013
  28 .Dt GPIO 4
  29 .Os
  30 .Sh NAME
  31 .Nm gpiobus
  32 .Nd GPIO bus system
  33 .Sh SYNOPSIS
  34 To compile these devices into your kernel and use the device hints, place the
  35 following lines in your kernel configuration file:
  36 .Bd -ragged -offset indent
  37 .Cd "device gpiobus"
  38 .Cd "device gpioiic"
  39 .Cd "device gpio"
  40 .Cd "device gpioc"
  41 .Cd "device gpioled"
  42 .Ed
  43 .Pp
  44 Additional device entries for the
  45 .Li ARM
  46 architecure include:
  47 .Bd -ragged -offset indent
  48 .Cd "device a10_gpio"
  49 .Cd "device bcm_gpio"
  50 .Cd "device imx51_gpio"
  51 .Cd "device lpcgpio"
  52 .Cd "device mv_gpio"
  53 .Cd "device ti_gpio"
  54 .Cd "device gpio_avila"
  55 .Cd "device gpio_cambria"
  56 .Cd "device zy7_gpio"
  57 .Cd "device pxagpio"
  58 .Ed
  59 .Pp
  60 Additional device entries for the
  61 .Li MIPS
  62 architecure include:
  63 .Bd -ragged -offset indent
  64 .Cd "device ar71xxx_gpio"
  65 .Cd "device octeon_gpio"
  66 .Cd "device rt305_gpio"
  67 .Ed
  68 .Pp
  69 Additional device entries for the
  70 .Li POWERPC
  71 architecure include:
  72 .Bd -ragged -offset indent
  73 .Cd "device wiigpio"
  74 .Cd "device macgpio"
  75 .Ed
  76 .Sh DESCRIPTION
  77 The
  78 .Em gpiobus
  79 system provides a simple interface to the bit banging style GPIO bus
  80 found on embedded architectures.
  81 .Pp
  82 The acronym
  83 .Li GPIO
  84 means
  85 .Dq General-Purpose Input/Output.
  86 .Pp
  87 The BUS physically consists of multiple pins that can be configured
  88 for input/output, IRQ delivery, SDA/SCL
  89 .Em iicbus
  90 use, etc.
  91 On most embedded architechtures (mips/arm), discovery of the bus and
  92 configuration of the pins is done via
  93 .Xr device.hints 5
  94 in the platform's kernel
  95 .Xr config 5
  96 file.
  97 .Pp
  98 Assignment of
  99 .Xr gpioiic 4
 100 bus variables is done via:
 101 .Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
 102 .It Va hint.gpioiic.%d.at
 103 Normally just gpiobus0.
 104 .It Va hint.gpioiic.%d.pins
 105 This is a bitmask of the pins on the gpio board that are to be used for
 106 SCLOCK and SDATA from the IIC bus.
 107 To configure pin 0 and 7, use the bitmask of
 108 10000001 and convert it to a hexadecimal value of 0x0081.
 109 Should only ever have two bits set in mask.
 110 .It Va hint.gpioiic.%d.scl
 111 Indicates which bit in the
 112 .Va hint.gpioiic.%d.pins
 113 should be used as the SCLOCK
 114 source.
 115 .It Va hint.gpioiic.%d.sda
 116 Indicates which bit in the
 117 .Va hint.gpioiic.%d.pins
 118 should be used as the SDATA
 119 source.
 120 .El
 121 .Pp
 122 The following are only provided by the
 123 .Cd ar71xx_gpio
 124 driver.
 125 .Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
 126 .It Va hint.gpio.%d.pinmask
 127 This is a bitmask of pins on the gpio board that we would like to expose
 128 for use to the host o/s.
 129 To expose pin 0, 4 and 7, use the bitmask of
 130 10010001 converted to the hexadecimal value 0x0091.
 131 .It Va hint.gpio.%d.pinon
 132 This is a bitmask of pins on the gpio board that will be set to ON at host
 133 start.
 134 To set pin 2, 5 and 13 to be set ON at boot, use the bitmask of
 135 10000000010010 converted to the hexadecimal value 0x2012.
 136 .It Va hint.gpio.function_set
 137 .It Va hint.gpio.function_clear
 138 These are a bitmask of pins that will remap a pin to handle a specific
 139 function (USB, UART TX/RX, etc) in the Atheros function registers.
 140 This is mainly used to set/clear functions that we need when they are setup or
 141 not setup by uBoot.
 142 .El
 143 .Pp
 144 These values are configureable from the
 145 .Xr gpioled 4
 146 interface and help create
 147 .Xr led 4
 148 compatible devices in
 149 .Pa /dev/led/<name> .
 150 .Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
 151 .It Va hint.gpioled.%d.at
 152 Normally assigned to gpiobus0.
 153 .It Va hint.gpioled.%d.name
 154 Arbitrary name of device in
 155 .Pa /dev/led/
 156 to create for
 157 .Xr led 4
 158 interfaces.
 159 .It Va hint.gpioled.%d.pins
 160 Which pin on the GPIO interface to map to this instance.
 161 .El
 162 .Pp
 163 Simply put, each pin of the GPIO interface is connected to an input/output
 164 of some device in a system.
 165 .Sh SEE ALSO
 166 .Xr iicbus 4 ,
 167 .Xr gpioctl 8
 168 .Sh HISTORY
 169 The
 170 .Nm
 171 manual page first appeared in
 172 .Fx 10.0 .
 173 .Sh AUTHORS
 174 This
 175 manual page was written by
 176 .An Sean Bruno Aq sbruno@FreeBSD.org .