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 May 15, 2015 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 39The 40.Nm 41device driver provides generic I/O to any 42.Xr iicbus 4 43instance. 44In order to control I2C devices, use 45.Pa /dev/iic? 46with the 47following ioctls: 48.Bl -tag -width ".Dv I2CRPTSTART" 49.It Dv I2CSTART 50.Pq Vt "struct iiccmd" 51Sends the start condition to the slave specified by the 52.Va slave 53element to the bus. 54The 55.Va slave 56element consists of a 7-bit address and a read/write bit 57(that is, a 7-bit address << 1 | r/w). 58A read operation is initiated when the read/write bit is set, or a write 59operation when it is cleared. 60All other elements are ignored. 61If successful, the file descriptor receives exclusive 62ownership of the underlying iicbus instance. 63.It Dv I2CRPTSTART 64.Pq Vt "struct iiccmd" 65Sends the repeated start condition to the slave specified by the 66.Va slave 67element to the bus. 68The slave address should be specified as in 69.Dv I2CSTART . 70All other elements are ignored. 71.Dv I2CSTART 72must have previously been issued on the same file descriptor. 73.It Dv I2CSTOP 74No argument is passed. 75Sends the stop condition to the bus. 76If 77.Dv I2CSTART 78was previously issued on the file descriptor, the current transaction is 79terminated and exclusive ownership of the underlying iicbus instance is 80released. 81Otherwise, no action is performed. 82.It Dv I2CRSTCARD 83.Pq Vt "struct iiccmd" 84Resets the bus. 85The argument is completely ignored. 86This command does not require 87.Dv I2CSTART 88to have been previously issued on the file descriptor. 89If it was previously issued, exclusive ownership of the underlying iicbus 90instance is released. 91.It Dv I2CWRITE 92.Pq Vt "struct iiccmd" 93Writes data to the 94.Xr iicbus 4 . 95The bus must already be started by a previous 96.Dv I2CSTART 97on the file descriptor. 98The 99.Va slave 100element is ignored. 101The 102.Va count 103element is the number of bytes to write. 104The 105.Va last 106element is a boolean flag. 107It is non-zero when additional write commands will follow. 108The 109.Va buf 110element is a pointer to the data to write to the bus. 111.It Dv I2CREAD 112.Pq Vt "struct iiccmd" 113Reads data from the 114.Xr iicbus 4 . 115The bus must already be started by a previous 116.Dv I2CSTART 117on the file descriptor. 118The 119.Va slave 120element is ignored. 121The 122.Va count 123element is the number of bytes to write. 124The 125.Va last 126element is a boolean flag. 127It is non-zero when additional write commands will follow. 128The 129.Va buf 130element is a pointer to where to store the data read from the bus. 131Short reads on the bus produce undefined results. 132.It Dv I2CRDWR 133.Pq Vt "struct iic_rdwr_data" 134Generic read/write interface. 135Allows for an arbitrary number of commands to be sent to 136an arbitrary number of devices on the bus. 137Any previous transaction started by 138.Dv I2CSTART 139must be terminated by 140.Dv I2CSTOP 141or 142.Dv I2CRSTCARD 143before 144.Dv I2CRDWR 145can be issued on the same file descriptor. 146A read transfer is specified if 147.Dv IIC_M_RD 148is set in 149.Va flags . 150Otherwise the transfer is a write transfer. 151The 152.Va slave 153element specifies the 7-bit address with the read/write bit for the transfer. 154The read/write bit will be handled by the iicbus stack based on the specified 155transfer operation. 156The 157.Va len 158element is the number of 159.Pq Vt "struct iic_msg" 160messages encoded on 161.Pq Vt "struct iic_rdwr_data" . 162The 163.Va buf 164element is a buffer for that data. 165This ioctl is intended to be 166.Tn Linux 167compatible. 168.It Dv I2CSADDR 169.Pq Vt "uint8_t" 170Associate the specified address with the file descriptor for use by 171subsequent 172.Xr read 2 173or 174.Xr write 2 175calls. 176The argument is an 8-bit address (that is, a 7-bit address << 1). 177The read/write bit in the least-significant position is ignored. 178Any subsequent read or write operation will set or clear that bit as needed. 179.El 180.Pp 181The following data structures are defined in 182.In dev/iicbus/iic.h 183and referenced above: 184.Bd -literal -offset indent 185struct iiccmd { 186 u_char slave; 187 int count; 188 int last; 189 char *buf; 190}; 191 192/* Designed to be compatible with linux's struct i2c_msg */ 193struct iic_msg 194{ 195 uint16_t slave; 196 uint16_t flags; 197#define IIC_M_WR 0 /* Fake flag for write */ 198#define IIC_M_RD 0x0001 /* read vs write */ 199#define IIC_M_NOSTOP 0x0002 /* do not send a I2C stop after message */ 200#define IIC_M_NOSTART 0x0004 /* do not send a I2C start before message */ 201 uint16_t len; /* msg length */ 202 uint8_t * buf; 203}; 204 205struct iic_rdwr_data { 206 struct iic_msg *msgs; 207 uint32_t nmsgs; 208}; 209.Ed 210.Pp 211It is also possible to use 212.Xr read 2 213or 214.Xr write 2 , 215in which case the I2C start/stop handshake is managed by 216.Xr iicbus 4 . 217The address used for the read/write operation is the one passed to the most 218recent 219.Dv I2CSTART 220.Xr ioctl 2 221or 222.Dv I2CSADDR 223.Xr ioctl 2 224on the open 225.Pa /dev/iic? 226file descriptor. 227Closing the file descriptor clears any addressing state established by a 228previous 229.Dv I2CSTART 230or 231.Dv I2CSADDR , 232stops any transaction established by a not-yet-terminated 233.Dv I2CSTART , 234and releases iicbus ownership. 235Because addressing state is stored on a per-file-descriptor basis, it is 236permissible for multiple file descriptors to be simultaneously open on the 237same 238.Pa /dev/iic? 239device. 240Concurrent transactions on those descriptors are synchronized by the 241exclusive-ownership requests issued to the underlying iicbus instance. 242.Sh SEE ALSO 243.Xr ioctl 2 , 244.Xr read 2 , 245.Xr write 2 , 246.Xr iicbus 4 247.Sh HISTORY 248The 249.Nm 250manual page first appeared in 251.Fx 3.0 . 252.Sh AUTHORS 253.An -nosplit 254This 255manual page was written by 256.An Nicolas Souchu 257and 258.An M. Warner Losh . 259