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 architecture 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 architecture 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 architecture include:
  71 .Bd -ragged -offset indent
  72 .Cd "device wiigpio"
  73 .Cd "device macgpio"
  74 .Ed
  75 .Sh DESCRIPTION
  76 The
  77 .Nm
  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 architectures (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 the kernel at boot.
 105 .Pp
 106 The following
 107 .Xr device.hints 5
 108 are only provided by the
 109 .Cd ar71xx_gpio
 110 driver:
 111 .Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
 112 .It Va hint.gpio.%d.pinmask
 113 This is a bitmask of pins on the GPIO board that we would like to expose
 114 for use to the host operating system.
 115 To expose pin 0, 4 and 7, use the bitmask of
 116 10010001 converted to the hexadecimal value 0x0091.
 117 .It Va hint.gpio.%d.pinon
 118 This is a bitmask of pins on the GPIO board that will be set to ON at host
 119 start.
 120 To set pin 2, 5 and 13 to be set ON at boot, use the bitmask of
 121 10000000010010 converted to the hexadecimal value 0x2012.
 122 .It Va hint.gpio.function_set
 123 .It Va hint.gpio.function_clear
 124 These are bitmasks of pins that will remap a pin to handle a specific
 125 function (USB, UART TX/RX, etc) in the Atheros function registers.
 126 This is mainly used to set/clear functions that we need when they are set up or
 127 not set up by uBoot.
 128 .El
 129 .Pp
 130 Simply put, each pin of the GPIO interface is connected to an input/output
 131 of some device in a system.
 132 .Sh SEE ALSO
 133 .Xr gpioiic 4 ,
 134 .Xr gpioled 4 ,
 135 .Xr iicbus 4 ,
 136 .Xr gpioctl 8
 137 .Sh HISTORY
 138 The
 139 .Nm
 140 manual page first appeared in
 141 .Fx 10.0 .
 142 .Sh AUTHORS
 143 This
 144 manual page was written by
 145 .An Sean Bruno Aq sbruno@FreeBSD.org .