share/man/man4/gpioiic.4

   1 .\" Copyright (c) 2013, Luiz Otavio O Souza <loos@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 May 14, 2014
  28 .Dt GPIOIIC 4
  29 .Os
  30 .Sh NAME
  31 .Nm gpioiic
  32 .Nd GPIO I2C bit-banging device driver
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel,
  35 place the following lines in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device gpio"
  39 .Cd "device gpioiic"
  40 .Cd "device iic"
  41 .Cd "device iicbb"
  42 .Cd "device iicbus"
  43 .Ed
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 driver provides an IIC bit-banging interface using two GPIO pins for the
  48 SCL and SDA on the
  49 .Nm gpiobus .
  50 .Nm
  51 implements an open collector kind of output, as recommended by the standard,
  52 when driving the pins on the
  53 .Nm gpiobus ,
  54 i.e, they are never switched to the logical value of '1',
  55 or they are '0' or simply open (Hi-Z/tri-state).
  56 So the pullup resistors are required so
  57 .Nm
  58 can work.
  59 .Pp
  60 On a
  61 .Xr device.hints 5
  62 based system, like
  63 .Li MIPS ,
  64 these values are configurable for the
  65 .Nm :
  66 .Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
  67 .It Va hint.gpioiic.%d.at
  68 The
  69 .Nm gpiobus
  70 you are attaching to.
  71 Normally just gpiobus0.
  72 .It Va hint.gpioiic.%d.pins
  73 This is a bitmask of the pins on the
  74 .Nm gpiobus
  75 that are to be used for SCLOCK and SDATA from the GPIO IIC
  76 bit-banging bus.
  77 To configure pin 0 and 7, use the bitmask of
  78 0b10000001 and convert it to a hexadecimal value of 0x0081.
  79 Please note that this mask should only ever have two bits set
  80 (any other bits - i.e., pins - will be ignored).
  81 .It Va hint.gpioiic.%d.scl
  82 Indicates which bit in the
  83 .Va hint.gpioiic.%d.pins
  84 should be used as the SCLOCK
  85 source.
  86 Optional, defaults to 0.
  87 .It Va hint.gpioiic.%d.sda
  88 Indicates which bit in the
  89 .Va hint.gpioiic.%d.pins
  90 should be used as the SDATA
  91 source.
  92 Optional, defaults to 1.
  93 .El
  94 .Pp
  95 On a
  96 .Xr FDT 4
  97 based system, like
  98 .Li ARM ,
  99 the DTS part for a
 100 .Nm gpioiic
 101 device usually looks like:
 102 .Bd -literal
 103 gpio: gpio {
 104
 105         gpio-controller;
 106         ...
 107
 108         gpioiic0 {
 109                 compatible = "gpioiic";
 110                 /*
 111                  * Attach to GPIO pins 21 and 22.  Set them
 112                  * initially as inputs.
 113                  */
 114                 gpios = <&gpio 21 1 0
 115                          &gpio 22 1 0>;
 116                 scl = <0>;              /* GPIO pin 21 - optional */
 117                 sda = <1>;              /* GPIO pin 22 - optional */
 118
 119                 /* This is an example of a gpioiic child. */
 120                 gpioiic-child0 {
 121                         compatible = "lm75";
 122                         i2c-address = <0x4f>;
 123                 };
 124         };
 125 };
 126 .Ed
 127 .Pp
 128 Where:
 129 .Bl -tag -width ".Va compatible"
 130 .It Va compatible
 131 Should always be set to "gpioiic".
 132 .It Va gpios
 133 The
 134 .Va gpios
 135 property indicates which GPIO pins should be used for SCLOCK and SDATA
 136 on the GPIO IIC bit-banging bus.
 137 For more details about the
 138 .Va gpios
 139 property, please consult
 140 .Pa /usr/src/sys/dts/bindings-gpio.txt .
 141 .It Va scl
 142 The
 143 .Va scl
 144 option indicates which bit in the
 145 .Va gpios
 146 should be used as the SCLOCK source.
 147 Optional, defaults to 0.
 148 .It Va sda
 149 The
 150 .Va sda
 151 option indicates which bit in the
 152 .Va gpios
 153 should be used as the SDATA source.
 154 Optional, defaults to 1.
 155 .El
 156 .Sh SEE ALSO
 157 .Xr fdt 4 ,
 158 .Xr gpio 4 ,
 159 .Xr gpioled 4 ,
 160 .Xr iic 4 ,
 161 .Xr iicbb 4 ,
 162 .Xr iicbus 4
 163 .Sh HISTORY
 164 The
 165 .Nm
 166 manual page first appeared in
 167 .Fx 10.1 .
 168 .Sh AUTHORS
 169 This
 170 manual page was written by
 171 .An Luiz Otavio O Souza .