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 November 5, 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 gpio"
  38 .Cd "device gpioc"
  39 .Cd "device gpioiic"
  40 .Cd "device gpioled"
  41 .Ed
  42 .Pp
  43 Additional device entries for the
  44 .Li ARM
  45 architecure include:
  46 .Bd -ragged -offset indent
  47 .Cd "device a10_gpio"
  48 .Cd "device bcm_gpio"
  49 .Cd "device imx51_gpio"
  50 .Cd "device lpcgpio"
  51 .Cd "device mv_gpio"
  52 .Cd "device ti_gpio"
  53 .Cd "device gpio_avila"
  54 .Cd "device gpio_cambria"
  55 .Cd "device zy7_gpio"
  56 .Cd "device pxagpio"
  57 .Ed
  58 .Pp
  59 Additional device entries for the
  60 .Li MIPS
  61 architecure include:
  62 .Bd -ragged -offset indent
  63 .Cd "device ar71xxx_gpio"
  64 .Cd "device octeon_gpio"
  65 .Cd "device rt305_gpio"
  66 .Ed
  67 .Pp
  68 Additional device entries for the
  69 .Li POWERPC
  70 architecure include:
  71 .Bd -ragged -offset indent
  72 .Cd "device wiigpio"
  73 .Cd "device macgpio"
  74 .Ed
  75 .Sh DESCRIPTION
  76 The
  77 .Em gpiobus
  78 system provides a simple interface to the GPIO pins that are usually
  79 available on embedded architectures and can provide bit banging style
  80 devices to the system.
  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 .Pp
  92 On some embedded architechtures (like MIPS), discovery of the bus and
  93 configuration of the pins is done via
  94 .Xr device.hints 5
  95 in the platform's kernel
  96 .Xr config 5
  97 file.
  98 .Pp
  99 On some others (like ARM), where
 100 .Xr FDT 4
 101 is used to describe the device tree, the bus discovery is done via the DTS
 102 passed to the kernel, being either statically compiled in, or by a variety
 103 of ways where the boot loader (or Open Firmware enabled system) passes the
 104 DTS blob to kernel at boot.
 105 .Pp
 106 The following are only provided by the
 107 .Cd ar71xx_gpio
 108 driver.
 109 .Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
 110 .It Va hint.gpio.%d.pinmask
 111 This is a bitmask of pins on the gpio board that we would like to expose
 112 for use to the host o/s.
 113 To expose pin 0, 4 and 7, use the bitmask of
 114 10010001 converted to the hexadecimal value 0x0091.
 115 .It Va hint.gpio.%d.pinon
 116 This is a bitmask of pins on the gpio board that will be set to ON at host
 117 start.
 118 To set pin 2, 5 and 13 to be set ON at boot, use the bitmask of
 119 10000000010010 converted to the hexadecimal value 0x2012.
 120 .It Va hint.gpio.function_set
 121 .It Va hint.gpio.function_clear
 122 These are a bitmask of pins that will remap a pin to handle a specific
 123 function (USB, UART TX/RX, etc) in the Atheros function registers.
 124 This is mainly used to set/clear functions that we need when they are setup or
 125 not setup by uBoot.
 126 .El
 127 .Pp
 128 Simply put, each pin of the GPIO interface is connected to an input/output
 129 of some device in a system.
 130 .Sh SEE ALSO
 131 .Xr gpioiic 4 ,
 132 .Xr gpioled 4 ,
 133 .Xr iicbus 4 ,
 134 .Xr gpioctl 8
 135 .Sh HISTORY
 136 The
 137 .Nm
 138 manual page first appeared in
 139 .Fx 10.0 .
 140 .Sh AUTHORS
 141 This
 142 manual page was written by
 143 .An Sean Bruno Aq sbruno@FreeBSD.org .