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