1.\" $NetBSD: iic.9,v 1.6 2010/03/17 18:55:13 jruoho Exp $ 2.\" $OpenBSD: iic.9,v 1.3 2004/08/24 05:48:22 david Exp $ 3.\" 4.\" Copyright (c) 2003 Wasabi Systems, Inc. 5.\" All rights reserved. 6.\" 7.\" Written by Jason R. Thorpe for Wasabi Systems, Inc. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed for the NetBSD Project by 20.\" Wasabi Systems, Inc. 21.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse 22.\" or promote products derived from this software without specific prior 23.\" written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd March 17, 2010 38.Dt IIC 9 39.Os 40.Sh NAME 41.Nm iic_acquire_bus , 42.Nm iic_release_bus , 43.Nm iic_exec , 44.Nm iic_smbus_write_byte , 45.Nm iic_smbus_read_byte , 46.Nm iic_smbus_receive_byte 47.Nd Inter IC (I2C) bus 48.Sh SYNOPSIS 49.In dev/i2c/i2cvar.h 50.Ft int 51.Fo iic_acquire_bus 52.Fa "i2c_tag_t ic" 53.Fa "int flags" 54.Fc 55.Ft int 56.Fo iic_release_bus 57.Fa "i2c_tag_t ic" 58.Fa "int flags" 59.Fc 60.Ft int 61.Fo iic_exec 62.Fa "i2c_tag_t ic" 63.Fa "i2c_op_t op" 64.Fa "i2c_addr_t addr" 65.Fa "const void *cmdbuf" 66.Fa "size_t cmdlen" 67.Fa "void *buf" 68.Fa "size_t buflen" 69.Fa "int flags" 70.Fc 71.Ft int 72.Fo iic_smbus_write_byte 73.Fa "i2c_tag_t ic" 74.Fa "i2c_addr_t addr" 75.Fa "uint8_t cmd" 76.Fa "uint8_t data" 77.Fa "int flags" 78.Fc 79.Ft int 80.Fo iic_smbus_read_byte 81.Fa "i2c_tag_t ic" 82.Fa "i2c_addr_t addr" 83.Fa "uint8_t cmd" 84.Fa "uint8_t *datap" 85.Fa "int flags" 86.Fc 87.Ft int 88.Fo iic_smbus_receive_byte 89.Fa "i2c_tag_t ic" 90.Fa "i2c_addr_t addr" 91.Fa "uint8_t *datap" 92.Fa "int flags" 93.Fc 94.Sh DESCRIPTION 95I2C is a two-wire bus developed by Philips used for connecting 96integrated circuits. 97It is commonly used for connecting devices such as EEPROMs, 98temperature sensors, fan controllers, real-time clocks, tuners, 99and other types of integrated circuits. 100The 101.Nm iic 102interface provides a means of communicating with I2C-connected devices. 103The System Management Bus, or SMBus, is a variant of the I2C bus with 104a simplified command protocol and some electrical differences. 105.Sh DATA TYPES 106Drivers for devices attached to the I2C bus will make use of the 107following data types: 108.Bl -tag -width i2c_addr_t 109.It Fa i2c_tag_t 110Controller tag for the I2C bus. 111This is a pointer to a 112.Fa struct i2c_controller , 113consisting of function pointers filled in by the I2C 114controller driver. 115.It Fa i2c_op_t 116I2C bus operation. 117The following I2C bus operations are defined: 118.Bl -tag -width XXXX 119.It I2C_OP_READ 120Perform a read operation. 121.It I2C_OP_READ_WITH_STOP 122Perform a read operation and send a STOP condition on the I2C bus at 123the conclusion of the read. 124.It I2C_OP_WRITE 125Perform a write operation. 126.It I2C_OP_WRITE_WITH_STOP 127Perform a write operation and send a STOP condition on the I2C bus at 128the conclusion of the write. 129.El 130.It Fa i2c_addr_t 131I2C device address. 132.It Fa struct i2c_attach_args 133Devices are attached to an I2C bus using this structure. 134The structure is defined as follows: 135.Bd -literal 136struct i2c_attach_args { 137 i2c_tag_t ia_tag; /* controller */ 138 i2c_addr_t ia_addr; /* address of device */ 139 int ia_size; /* size (for EEPROMs) */ 140}; 141.Ed 142.El 143.Sh FUNCTIONS 144The following functions comprise the API provided to drivers of 145I2C-connected devices: 146.Bl -tag -width iic_exec 147.It Fn iic_acquire_bus "ic" "flags" 148Acquire an exclusive lock on the I2C bus. 149This is required since only one device may communicate on the 150I2C bus at a time. 151Drivers should acquire the bus lock, perform the I2C bus operations 152necessary, and then release the bus lock. 153Passing the 154.Dv I2C_F_POLL 155flag indicates to 156.Fn iic_acquire_bus 157that sleeping is not permitted. 158.It Fn iic_release_bus "ic" "flags" 159Release an exclusive lock on the I2C bus. 160If the 161.Dv I2C_F_POLL 162flag was passed to 163.Fn iic_acquire_bus , 164it must also be passed to 165.Fn iic_release_bus . 166.It Fn iic_exec "ic" "op" "addr" "cmdbuf" "cmdlen" "buf" "buflen" "flags" 167Perform a series of I2C transactions on the bus. 168.Fn iic_exec 169initiates the operation by sending a START condition on the I2C 170bus and then transmitting the address of the target device along 171with the transaction type. 172If 173.Fa cmdlen 174is non-zero, the command pointed to by 175.Fa cmdbuf 176is then sent to the device. 177If 178.Fa buflen 179is non-zero, 180.Fn iic_exec 181will then transmit or receive the data, as indicated by 182.Fa op . 183If 184.Fa op 185indicates a read operation, 186.Fn iic_exec 187will send a REPEATED START before transferring the data. 188If 189.Fa op 190so indicates, a STOP condition will be sent on the I2C 191bus at the conclusion of the operation. 192Passing the 193.Dv I2C_F_POLL 194flag indicates to 195.Fn iic_exec 196that sleeping is not permitted. 197.It Fn iic_smbus_write_byte "ic" "addr" "cmd" "data" "flags" 198Perform an SMBus WRITE BYTE operation. 199This is equivalent to 200I2C_OP_WRITE_WITH_STOP with 201.Fa cmdlen 202of 1 and 203.Fa buflen 204of 1. 205.It Fn iic_smbus_read_byte "ic" "addr" "cmd" "datap" "flags" 206Perform an SMBus READ BYTE operation. 207This is equivalent to 208I2C_OP_READ_WITH_STOP with 209.Fa cmdlen 210of 1 and 211.Fa buflen 212of 1. 213.It Fn iic_smbus_receive_byte "ic" "addr" "datap" "flags" 214Perform an SMBus RECEIVE BYTE operation. 215This is equivalent to 216I2C_OP_READ_WITH_STOP with 217.Fa cmdlen 218of 0 and 219.Fa buflen 220of 1. 221.El 222.Sh CONTROLLER INTERFACE 223The I2C controller driver must fill in the function pointers of 224an 225.Fa i2c_controller 226structure, which is defined as follows: 227.Bd -literal 228struct i2c_controller { 229 void *ic_cookie; /* controller private */ 230 231 int (*ic_acquire_bus)(void *, int); 232 void (*ic_release_bus)(void *, int); 233 234 int (*ic_exec)(void *, i2c_op_t, i2c_addr_t, 235 const void *, size_t, void *, size_t, int); 236 237 int (*ic_send_start)(void *, int); 238 int (*ic_send_stop)(void *, int); 239 int (*ic_initiate_xfer)(void *, i2c_addr_t, int); 240 int (*ic_read_byte)(void *, uint8_t *, int); 241 int (*ic_write_byte)(void *, uint8_t, int); 242}; 243.Ed 244.Pp 245The 246.Fn (*ic_acquire_bus) 247and 248.Fn (*ic_release_bus) 249functions must always be provided. 250.Pp 251The controller driver may elect to provide an 252.Fn (*ic_exec) 253function. 254This function is intended for use by automated controllers 255that do not provide manual control over I2C bus conditions 256such as START and STOP. 257.Pp 258If the 259.Fn (*ic_exec) 260function is not provided, the following 5 functions will be 261used by 262.Fn iic_exec 263in order to execute the I2C bus operation: 264.Bl -tag -width XXXX 265.It Fn (*ic_send_start) "cookie" "flags" 266Send a START condition on the I2C bus. 267The 268.Dv I2C_F_POLL 269flag indicates that sleeping is not permitted. 270.It Fn (*ic_send_stop) "cookie" "flags" 271Send a STOP condition on the I2C bus. 272The 273.Dv I2C_F_POLL 274flag indicates that sleeping is not permitted. 275.It Fn (*ic_initiate_xfer) "cookie" "addr" "flags" 276Initiate a transfer on the I2C bus by sending a START condition and 277then transmitting the I2C device address and transfer type. 278The 279.Dv I2C_F_READ 280flag indicates a read transfer; the lack of this flag indicates a 281write transfer. 282The 283.Dv I2C_F_POLL 284flag indicates that sleeping is not permitted. 285The error code 286.Dv ETIMEDOUT 287should be returned if a timeout that would indicate that the 288device is not present occurs. 289.It Fn (*ic_read_byte) "cookie" "datap" "flags" 290Read a byte from the I2C bus into the memory location referenced by 291.Fa datap . 292The 293.Dv I2C_F_LAST 294flag indicates that this is the final byte of the transfer, and that 295a NACK condition should be sent on the I2C bus following the transfer 296of the byte. 297The 298.Dv I2C_F_STOP 299flag indicates that a STOP condition should be sent on the I2C bus following 300the transfer of the byte. 301The 302.Dv I2C_F_POLL 303flag indicates that sleeping is not permitted. 304.It Fn (*ic_write_byte) "cookie" "data" "flags" 305Write the byte contained in 306.Fa data 307to the I2C bus. 308The 309.Dv I2C_F_STOP 310flag indicates that a STOP condition should be sent on the I2C bus following 311the transfer of the byte. 312The 313.Dv I2C_F_POLL 314flag indicates that sleeping is not permitted. 315.El 316.Sh SEE ALSO 317.Xr iic 4 318.Rs 319.%A NXP Semiconductors 320.%T I2C-bus Specification and User Manual 321.%N Revision 03 322.%D June 19, 2007 323.%U http://www.ics.nxp.com/support/documents/i2c/pdf/i2c.bus.specification.pdf 324.Re 325.Rs 326.%A Duracell Inc. et. al. 327.%T System Management Bus (SMBus) Specification 328.%N Version 2.0 329.%D August 3, 2000 330.%U http://smbus.org/specs/smbus20.pdf 331.Re 332.Sh HISTORY 333The 334.Nm iic 335API first appeared in 336.Nx 2.0 . 337.Ox 338support was added in 339.Ox 3.6 . 340.Sh AUTHORS 341The 342.Nm iic 343API was written by 344Steve C. Woodford and Jason R. Thorpe for 345.Nx 346and then ported to 347.Ox 348by 349.An Alexander Yurchenko Aq grange@openbsd.org . 350