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