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