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 June 24, 2014
  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 The
  55 .Va slave
  56 element consists of a 7-bit address and a read/write bit
  57 (i.e., 7-bit address << 1 | r/w).
  58 If the read/write bit is set a read operation is initiated, if the read/write
  59 bit is cleared a write operation is initiated.
  60 All other elements are ignored.
  61 .It Dv I2CRPTSTART
  62 .Pq Vt "struct iiccmd"
  63 Sends the repeated start condition to the slave specified by the
  64 .Va slave
  65 element to the bus.
  66 The slave address should be specified as in
  67 .Dv I2CSTART .
  68 All other elements are ignored.
  69 .It Dv I2CSTOP
  70 No argument is passed.
  71 Sends the stop condition to the bus.
  72 This terminates the current transaction.
  73 .It Dv I2CRSTCARD
  74 .Pq Vt "struct iiccmd"
  75 Resets the bus.
  76 The argument is completely ignored.
  77 .It Dv I2CWRITE
  78 .Pq Vt "struct iiccmd"
  79 Writes data to the
  80 .Xr iicbus 4 .
  81 The bus should already be started.
  82 The
  83 .Va slave
  84 element is ignored.
  85 The
  86 .Va count
  87 element is the number of bytes to write.
  88 The
  89 .Va last
  90 element is a boolean flag.
  91 It is non-zero when additional write commands will follow.
  92 The
  93 .Va buf
  94 element is a pointer to the data to write to the bus.
  95 .It Dv I2CREAD
  96 .Pq Vt "struct iiccmd"
  97 Reads data from the
  98 .Xr iicbus 4 .
  99 The bus should already be started.
 100 The
 101 .Va slave
 102 element is ignored.
 103 The
 104 .Va count
 105 element is the number of bytes to write.
 106 The
 107 .Va last
 108 element is a boolean flag.
 109 It is non-zero when additional write commands will follow.
 110 The
 111 .Va buf
 112 element is a pointer to where to store the data read from the bus.
 113 Short reads on the bus produce undefined results.
 114 .It Dv I2CRDWR
 115 .Pq Vt "struct iic_rdwr_data"
 116 Generic read/write interface.
 117 Allows for an arbitrary number of commands to be sent to
 118 an arbitrary number of devices on the bus.
 119 A read transfer is specified if
 120 .Dv IIC_M_RD
 121 is set in
 122 .Va flags .
 123 Otherwise the transfer is a write transfer.
 124 The
 125 .Va slave
 126 element specifies the 7-bit address with the read/write bit for the transfer.
 127 The read/write bit will be handled by the iicbus stack based on the specified
 128 transfer operation.
 129 The
 130 .Va len
 131 element is the number of
 132 .Pq Vt "struct iic_msg"
 133 messages encoded on
 134 .Pq Vt "struct iic_rdwr_data" .
 135 The
 136 .Va buf
 137 element is a buffer for that data.
 138 This ioctl is intended to be
 139 .Tn Linux
 140 compatible.
 141 .El
 142 .Pp
 143 The following data structures are defined in
 144 .In dev/iicbus/iic.h
 145 and referenced above:
 146 .Bd -literal -offset indent
 147 struct iiccmd {
 148         u_char slave;
 149         int count;
 150         int last;
 151         char *buf;
 152 };
 153
 154 /* Designed to be compatible with linux's struct i2c_msg */
 155 struct iic_msg
 156 {
 157         uint16_t        slave;
 158         uint16_t        flags;
 159 #define IIC_M_RD        0x0001  /* read vs write */
 160         uint16_t        len;    /* msg length */
 161         uint8_t *       buf;
 162 };
 163
 164 struct iic_rdwr_data {
 165         struct iic_msg *msgs;
 166         uint32_t nmsgs;
 167 };
 168 .Ed
 169 .Pp
 170 It is also possible to use read/write routines, then I2C start/stop handshake is
 171 managed by the
 172 .Xr iicbus 4
 173 system.
 174 However, the address used for the read/write routines is the one
 175 passed to last
 176 .Dv I2CSTART
 177 .Xr ioctl 2
 178 to this device.
 179 .Sh SEE ALSO
 180 .Xr ioctl 2 ,
 181 .Xr read 2 ,
 182 .Xr write 2 ,
 183 .Xr iicbus 4
 184 .Sh HISTORY
 185 The
 186 .Nm
 187 manual page first appeared in
 188 .Fx 3.0 .
 189 .Sh AUTHORS
 190 .An -nosplit
 191 This
 192 manual page was written by
 193 .An Nicolas Souchu
 194 and
 195 .An M. Warner Losh .
 196 .Sh BUGS
 197 Only the
 198 .Dv I2CRDWR
 199 .Xr ioctl 2
 200 is thread safe.
 201 All other interfaces suffer from some kind of race.