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