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