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 .Dd June 27, 2019
  26 .Dt GPIO 4
  27 .Os
  28 .Sh NAME
  29 .Nm gpiobus
  30 .Nd GPIO bus system
  31 .Sh SYNOPSIS
  32 To compile these devices into your kernel and use the device hints, place the
  33 following lines in your kernel configuration file:
  34 .Bd -ragged -offset indent
  35 .Cd "device gpio"
  36 .Cd "device gpioc"
  37 .Cd "device gpioiic"
  38 .Cd "device gpioled"
  39 .Ed
  40 .Pp
  41 Additional device entries for the
  42 .Li ARM
  43 architecture include:
  44 .Bd -ragged -offset indent
  45 .Cd "device a10_gpio"
  46 .Cd "device bcm_gpio"
  47 .Cd "device imx51_gpio"
  48 .Cd "device lpcgpio"
  49 .Cd "device mv_gpio"
  50 .Cd "device ti_gpio"
  51 .Cd "device gpio_avila"
  52 .Cd "device gpio_cambria"
  53 .Cd "device zy7_gpio"
  54 .Cd "device pxagpio"
  55 .Ed
  56 .Pp
  57 Additional device entries for the
  58 .Li MIPS
  59 architecture include:
  60 .Bd -ragged -offset indent
  61 .Cd "device ar71xxx_gpio"
  62 .Cd "device octeon_gpio"
  63 .Cd "device rt305_gpio"
  64 .Ed
  65 .Pp
  66 Additional device entries for the
  67 .Li POWERPC
  68 architecture include:
  69 .Bd -ragged -offset indent
  70 .Cd "device wiigpio"
  71 .Cd "device macgpio"
  72 .Ed
  73 .Pp
  74 Additional device entries for the
  75 .Li RISC-V
  76 architecture include:
  77 .Bd -ragged -offset indent
  78 .Cd "device sifive_gpio"
  79 .Ed
  80 .Sh DESCRIPTION
  81 The
  82 .Nm
  83 system provides a simple interface to the GPIO pins that are usually
  84 available on embedded architectures and can provide bit banging style
  85 devices to the system.
  86 .Pp
  87 The acronym
  88 .Li GPIO
  89 means
  90 .Dq General-Purpose Input/Output.
  91 .Pp
  92 The BUS physically consists of multiple pins that can be configured
  93 for input/output, IRQ delivery, SDA/SCL
  94 .Em iicbus
  95 use, etc.
  96 .Pp
  97 On some embedded architectures (like MIPS), discovery of the bus and
  98 configuration of the pins is done via
  99 .Xr device.hints 5
 100 in the platform's kernel
 101 .Xr config 5
 102 file.
 103 .Pp
 104 On some others (like ARM), where
 105 .Xr FDT 4
 106 is used to describe the device tree, the bus discovery is done via the DTS
 107 passed to the kernel, being either statically compiled in, or by a variety
 108 of ways where the boot loader (or Open Firmware enabled system) passes the
 109 DTS blob to the kernel at boot.
 110 .Pp
 111 On a
 112 .Xr device.hints 5
 113 based system these hints can be used to configure drivers for devices
 114 attached to
 115 .Nm
 116 pins:
 117 .Bl -tag -width ".Va hint.driver.unit.pin_list"
 118 .It Va hint.driver.unit.at
 119 The
 120 .Nm gpiobus
 121 where the device is attached.
 122 For example,
 123 .Qq gpiobus0 .
 124 .Ar driver
 125 and
 126 .Ar unit
 127 are the driver name and the unit number for the device driver.
 128 .It Va hint.driver.unit.pins
 129 This is a bitmask of the pins on the
 130 .Nm gpiobus
 131 that are connected to the device.
 132 The pins will be allocated to the specified driver instance.
 133 Only pins with numbers from 0 to 31 can be specified using this hint.
 134 .It Va hint.driver.unit.pin_list
 135 This is a list of pin numbers of pins on the
 136 .Nm gpiobus
 137 that are connected to the device.
 138 The pins will be allocated to the specified driver instance.
 139 This is a more user friendly alternative to the
 140 .Ar pins
 141 hint.
 142 Additionally, this hint allows specifying pin numbers greater than 31.
 143 The numbers can be decimal or hexadecimal with 0x prefix.
 144 Any non-digit character can be used as a separator.
 145 For example, it can be a comma, a slash or a space.
 146 The separator can be followed by any number of space characters.
 147 .El
 148 .Pp
 149 The following
 150 .Xr device.hints 5
 151 are only provided by the
 152 .Cd ar71xx_gpio
 153 driver:
 154 .Bl -tag -width ".Va hint.gpio.function_clear"
 155 .It Va hint.gpio.%d.pinmask
 156 This is a bitmask of pins on the GPIO board that we would like to expose
 157 for use to the host operating system.
 158 To expose pin 0, 4 and 7, use the bitmask of
 159 10010001 converted to the hexadecimal value 0x0091.
 160 .It Va hint.gpio.%d.pinon
 161 This is a bitmask of pins on the GPIO board that will be set to ON at host
 162 start.
 163 To set pin 2, 5 and 13 to be set ON at boot, use the bitmask of
 164 10000000010010 converted to the hexadecimal value 0x2012.
 165 .It Va hint.gpio.function_set
 166 .It Va hint.gpio.function_clear
 167 These are bitmasks of pins that will remap a pin to handle a specific
 168 function (USB, UART TX/RX, etc) in the Atheros function registers.
 169 This is mainly used to set/clear functions that we need when they are set up or
 170 not set up by uBoot.
 171 .El
 172 .Pp
 173 Simply put, each pin of the GPIO interface is connected to an input/output
 174 of some device in a system.
 175 .Sh SEE ALSO
 176 .Xr gpioiic 4 ,
 177 .Xr gpioled 4 ,
 178 .Xr iicbus 4 ,
 179 .Xr device.hints 5 ,
 180 .Xr gpioctl 8
 181 .Sh HISTORY
 182 The
 183 .Nm
 184 manual page first appeared in
 185 .Fx 10.0 .
 186 .Sh AUTHORS
 187 This
 188 manual page was written by
 189 .An Sean Bruno Aq Mt sbruno@FreeBSD.org .