share/man/man4/iic.4

   1 .\" Copyright (c) 2006, M. Warner Losh
   2 .\" Copyright (c) 1998, Nicolas Souchu
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 6, 2006
  29 .Dt IIC 4
  30 .Os
  31 .Sh NAME
  32 .Nm iic
  33 .Nd I2C generic I/O device driver
  34 .Sh SYNOPSIS
  35 .Cd "device iic"
  36 .Pp
  37 .In dev/iicbus/iic.h
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 device driver provides generic I/O to any
  42 .Xr iicbus 4
  43 instance.
  44 In order to control I2C devices, use
  45 .Pa /dev/iic?
  46 with the
  47 following ioctls:
  48 .Bl -tag -width ".Dv I2CRPTSTART"
  49 .It Dv I2CSTART
  50 .Pq Vt "struct iiccmd"
  51 Sends the start condition to the slave specified by the
  52 .Va slave
  53 element to the bus.
  54 All other elements are ignored.
  55 .It Dv I2CRPTSTART
  56 .Pq Vt "struct iiccmd"
  57 Sends the repeated start condition to the slave specified by the
  58 .Va slave
  59 element to the bus.
  60 All other elements are ignored.
  61 .It Dv I2CSTOP
  62 No argument is passed.
  63 Sends the stop condition to the bus.
  64 This terminates the current transaction.
  65 .It Dv I2CRSTCARD
  66 .Pq Vt "struct iiccmd"
  67 Resets the bus.
  68 The argument is completely ignored.
  69 .It Dv I2CWRITE
  70 .Pq Vt "struct iiccmd"
  71 Writes data to the
  72 .Xr iicbus 4 .
  73 The bus should already be started.
  74 The
  75 .Va slave
  76 element is ignored.
  77 The
  78 .Va count
  79 element is the number of bytes to write.
  80 The
  81 .Va last
  82 element is a boolean flag.
  83 It is non-zero when additional write commands will follow.
  84 The
  85 .Va buf
  86 element is a pointer to the data to write to the bus.
  87 .It Dv I2CREAD
  88 .Pq Vt "struct iiccmd"
  89 Reads data from the
  90 .Xr iicbus 4 .
  91 The bus should already be started.
  92 The
  93 .Va slave
  94 element is ignored.
  95 The
  96 .Va count
  97 element is the number of bytes to write.
  98 The
  99 .Va last
 100 element is a boolean flag.
 101 It is non-zero when additional write commands will follow.
 102 The
 103 .Va buf
 104 element is a pointer to where to store the data read from the bus.
 105 Short reads on the bus produce undefined results.
 106 .It Dv I2CRDWR
 107 .Pq Vt "struct iic_rdwr_data"
 108 Generic read/write interface.
 109 Allows for an arbitrary number of commands to be sent to
 110 an arbitrary number of devices on the bus.
 111 A read transfer is specified if
 112 .Dv IIC_M_RD
 113 is set in
 114 .Va flags .
 115 Otherwise the transfer is a write transfer.
 116 The
 117 .Va slave
 118 element specifies the 7-bit address for the transfer.
 119 The
 120 .Va len
 121 element is the length of the data.
 122 The
 123 .Va buf
 124 element is a buffer for that data.
 125 This ioctl is intended to be
 126 .Tn Linux
 127 compatible.
 128 .El
 129 .Pp
 130 The following data structures are defined in
 131 .In dev/iicbus/iic.h
 132 and referenced above:
 133 .Bd -literal -offset indent
 134 struct iiccmd {
 135         u_char slave;
 136         int count;
 137         int last;
 138         char *buf;
 139 };
 140
 141 /* Designed to be compatible with linux's struct i2c_msg */
 142 struct iic_msg
 143 {
 144         uint16_t        slave;
 145         uint16_t        flags;
 146 #define IIC_M_RD        0x0001  /* read vs write */
 147         uint16_t        len;    /* msg length */
 148         uint8_t *       buf;
 149 };
 150
 151 struct iic_rdwr_data {
 152         struct iic_msg *msgs;
 153         uint32_t nmsgs;
 154 };
 155 .Ed
 156 .Pp
 157 It is also possible to use read/write routines, then I2C start/stop handshake is
 158 managed by the
 159 .Xr iicbus 4
 160 system.
 161 However, the address used for the read/write routines is the one
 162 passed to last
 163 .Dv I2CSTART
 164 .Xr ioctl 2
 165 to this device.
 166 .Sh SEE ALSO
 167 .Xr ioctl 2 ,
 168 .Xr read 2 ,
 169 .Xr write 2 ,
 170 .Xr iicbus 4
 171 .Sh HISTORY
 172 The
 173 .Nm
 174 manual page first appeared in
 175 .Fx 3.0 .
 176 .Sh AUTHORS
 177 .An -nosplit
 178 This
 179 manual page was written by
 180 .An Nicolas Souchu
 181 and
 182 .An M. Warner Losh .
 183 .Sh BUGS
 184 Only the
 185 .Dv I2CRDWR
 186 .Xr ioctl 2
 187 is thread safe.
 188 All other interfaces suffer from some kind of race.