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