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 must be zero when additional read commands will follow, or non-zero if this 108is the last command. 109The 110.Va buf 111element is a pointer to the data to write to the bus. 112.It Dv I2CREAD 113.Pq Vt "struct iiccmd" 114Reads data from the 115.Xr iicbus 4 . 116The bus must already be started by a previous 117.Dv I2CSTART 118on the file descriptor. 119The 120.Va slave 121element is ignored. 122The 123.Va count 124element is the number of bytes to read. 125The 126.Va last 127element is a boolean flag. 128It must be zero when additional read commands will follow, or non-zero if this 129is the last command. 130The 131.Va buf 132element is a pointer to where to store the data read from the bus. 133Short reads on the bus produce undefined results. 134.It Dv I2CRDWR 135.Pq Vt "struct iic_rdwr_data" 136Generic read/write interface. 137Allows for an arbitrary number of commands to be sent to 138an arbitrary number of devices on the bus. 139Any previous transaction started by 140.Dv I2CSTART 141must be terminated by 142.Dv I2CSTOP 143or 144.Dv I2CRSTCARD 145before 146.Dv I2CRDWR 147can be issued on the same file descriptor. 148A read transfer is specified if 149.Dv IIC_M_RD 150is set in 151.Va flags . 152Otherwise the transfer is a write transfer. 153The 154.Va slave 155element specifies the 7-bit address with the read/write bit for the transfer. 156The read/write bit will be handled by the iicbus stack based on the specified 157transfer operation. 158The 159.Va len 160element is the number of 161.Pq Vt "struct iic_msg" 162messages encoded on 163.Pq Vt "struct iic_rdwr_data" . 164The 165.Va buf 166element is a buffer for that data. 167This ioctl is intended to be 168.Tn Linux 169compatible. 170.It Dv I2CSADDR 171.Pq Vt "uint8_t" 172Associate the specified address with the file descriptor for use by 173subsequent 174.Xr read 2 175or 176.Xr write 2 177calls. 178The argument is an 8-bit address (that is, a 7-bit address << 1). 179The read/write bit in the least-significant position is ignored. 180Any subsequent read or write operation will set or clear that bit as needed. 181.El 182.Pp 183The following data structures are defined in 184.In dev/iicbus/iic.h 185and referenced above: 186.Bd -literal -offset indent 187struct iiccmd { 188 u_char slave; 189 int count; 190 int last; 191 char *buf; 192}; 193 194/* Designed to be compatible with linux's struct i2c_msg */ 195struct iic_msg 196{ 197 uint16_t slave; 198 uint16_t flags; 199#define IIC_M_WR 0 /* Fake flag for write */ 200#define IIC_M_RD 0x0001 /* read vs write */ 201#define IIC_M_NOSTOP 0x0002 /* do not send a I2C stop after message */ 202#define IIC_M_NOSTART 0x0004 /* do not send a I2C start before message */ 203 uint16_t len; /* msg length */ 204 uint8_t * buf; 205}; 206 207struct iic_rdwr_data { 208 struct iic_msg *msgs; 209 uint32_t nmsgs; 210}; 211.Ed 212.Pp 213It is also possible to use 214.Xr read 2 215or 216.Xr write 2 , 217in which case the I2C start/stop handshake is managed by 218.Xr iicbus 4 . 219The address used for the read/write operation is the one passed to the most 220recent 221.Dv I2CSTART 222.Xr ioctl 2 223or 224.Dv I2CSADDR 225.Xr ioctl 2 226on the open 227.Pa /dev/iic? 228file descriptor. 229Closing the file descriptor clears any addressing state established by a 230previous 231.Dv I2CSTART 232or 233.Dv I2CSADDR , 234stops any transaction established by a not-yet-terminated 235.Dv I2CSTART , 236and releases iicbus ownership. 237Because addressing state is stored on a per-file-descriptor basis, it is 238permissible for multiple file descriptors to be simultaneously open on the 239same 240.Pa /dev/iic? 241device. 242Concurrent transactions on those descriptors are synchronized by the 243exclusive-ownership requests issued to the underlying iicbus instance. 244.Sh SEE ALSO 245.Xr ioctl 2 , 246.Xr read 2 , 247.Xr write 2 , 248.Xr iicbus 4 249.Sh HISTORY 250The 251.Nm 252manual page first appeared in 253.Fx 3.0 . 254.Sh AUTHORS 255.An -nosplit 256This 257manual page was written by 258.An Nicolas Souchu 259and 260.An M. Warner Losh . 261