1.\" $OpenBSD: iic.9,v 1.10 2022/02/09 07:58:24 visa 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: February 9 2022 $ 37.Dt IIC_ACQUIRE_BUS 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.Nm iic_is_compatible 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 len" 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.Ft int 95.Fo iic_is_compatible 96.Fa "const struct i2c_attach_args *ia" 97.Fa "const char *name" 98.Fc 99.Sh DESCRIPTION 100I2C is a two-wire bus developed by Philips used for connecting 101integrated circuits. 102It is commonly used for connecting devices such as EEPROMs, 103temperature sensors, fan controllers, real-time clocks, tuners, 104and other types of integrated circuits. 105The 106.Nm iic 107interface provides a means of communicating with I2C-connected devices. 108The System Management Bus, or SMBus, is a variant of the I2C bus with 109a simplified command protocol and some electrical differences. 110.Sh DATA TYPES 111Drivers for devices attached to the I2C bus will make use of the 112following data types: 113.Bl -tag -width i2c_addr_t 114.It Fa i2c_tag_t 115Controller tag for the I2C bus. 116This is a pointer to a 117.Fa struct i2c_controller , 118consisting of function pointers filled in by the I2C 119controller driver. 120.It Fa i2c_op_t 121I2C bus operation. 122The following I2C bus operations are defined: 123.Bl -tag -width XXXX 124.It I2C_OP_READ 125Perform a read operation. 126.It I2C_OP_READ_WITH_STOP 127Perform a read operation and send a STOP condition on the I2C bus at 128the conclusion of the read. 129.It I2C_OP_WRITE 130Perform a write operation. 131.It I2C_OP_WRITE_WITH_STOP 132Perform a write operation and send a STOP condition on the I2C bus at 133the conclusion of the write. 134.El 135.It Fa i2c_addr_t 136I2C device address. 137.It Fa struct i2c_attach_args 138Devices are attached to an I2C bus using this structure. 139The structure is defined as follows: 140.Bd -literal 141struct i2c_attach_args { 142 i2c_tag_t ia_tag; /* controller */ 143 i2c_addr_t ia_addr; /* address of device */ 144 int ia_size; /* size (for EEPROMs) */ 145 char *ia_name; /* chip name */ 146 size_t ia_namelen /* length of name concatenation */ 147 void *ia_cookie; /* pass extra info from 148 bus to dev */ 149 void *ia_intr /* interrupt info */ 150 int ia_poll; /* to force polling */ 151}; 152.Ed 153.El 154.Sh FUNCTIONS 155The following functions comprise the API provided to drivers of 156I2C-connected devices: 157.Bl -tag -width iic_exec 158.It Fn iic_acquire_bus "ic" "flags" 159Acquire an exclusive lock on the I2C bus. 160This is required since only one device may communicate on the 161I2C bus at a time. 162Drivers should acquire the bus lock, perform the I2C bus operations 163necessary, and then release the bus lock. 164Passing the 165.Fa I2C_F_POLL 166flag indicates to 167.Fn iic_acquire_bus 168that sleeping is not permitted. 169.It Fn iic_release_bus "ic" "flags" 170Release an exclusive lock on the I2C bus. 171If the 172.Fa I2C_F_POLL 173flag was passed to 174.Fn iic_acquire_bus , 175it must also be passed to 176.Fn iic_release_bus . 177.It Xo 178.Fo iic_exec 179.Fa "ic" 180.Fa "op" 181.Fa "addr" 182.Fa "cmdbuf" 183.Fa "cmdlen" 184.Fa "buf" 185.Fa "len" 186.Fa "flags" 187.Fc 188.Xc 189Perform a series of I2C transactions on the bus. 190.Fn iic_exec 191initiates the operation by sending a START condition on the I2C 192bus and then transmitting the address of the target device along 193with the transaction type. 194If 195.Fa cmdlen 196is non-zero, the command pointed to by 197.Fa cmdbuf 198is then sent to the device. 199If 200.Fa buflen 201is non-zero, 202.Fn iic_exec 203will then transmit or receive the data, as indicated by 204.Fa op . 205If 206.Fa op 207indicates a read operation, 208.Fn iic_exec 209will send a REPEATED START before transferring the data. 210If 211.Fa op 212so indicates, a STOP condition will be sent on the I2C 213bus at the conclusion of the operation. 214Passing the 215.Fa I2C_F_POLL 216flag indicates to 217.Fn iic_exec 218that sleeping is not permitted. 219.It Fn iic_smbus_write_byte "ic" "addr" "cmd" "data" "flags" 220Perform an SMBus WRITE BYTE operation. 221This is equivalent to 222I2C_OP_WRITE_WITH_STOP with 223.Fa cmdlen 224of 1 and 225.Fa len 226of 1. 227.It Fn iic_smbus_read_byte "ic" "addr" "cmd" "datap" "flags" 228Perform an SMBus READ BYTE operation. 229This is equivalent to 230I2C_OP_READ_WITH_STOP with 231.Fa cmdlen 232of 1 and 233.Fa len 234of 1. 235.It Fn iic_smbus_receive_byte "ic" "addr" "datap" "flags" 236Perform an SMBus RECEIVE BYTE operation. 237This is equivalent to 238I2C_OP_READ_WITH_STOP with 239.Fa cmdlen 240of 0 and 241.Fa len 242of 1. 243.It Fn iic_is_compatible "ia" "name" 244Test if the device is compatible with 245.Fa name . 246.El 247.Sh CONTROLLER INTERFACE 248The I2C controller driver must fill in the function pointers of 249an 250.Fa i2c_controller 251structure, which is defined as follows: 252.Bd -literal 253struct i2c_controller { 254 void *ic_cookie; /* controller private */ 255 256 int (*ic_acquire_bus)(void *, int); 257 void (*ic_release_bus)(void *, int); 258 259 int (*ic_exec)(void *, i2c_op_t, i2c_addr_t, 260 const void *, size_t, void *, size_t, int); 261 262 int (*ic_send_start)(void *, int); 263 int (*ic_send_stop)(void *, int); 264 int (*ic_initiate_xfer)(void *, i2c_addr_t, int); 265 int (*ic_read_byte)(void *, uint8_t *, int); 266 int (*ic_write_byte)(void *, uint8_t, int); 267}; 268.Ed 269.Pp 270The 271.Fn (*ic_acquire_bus) 272and 273.Fn (*ic_release_bus) 274functions must always be provided. 275.Pp 276The controller driver may elect to provide an 277.Fn (*ic_exec) 278function. 279This function is intended for use by automated controllers 280that do not provide manual control over I2C bus conditions 281such as START and STOP. 282.Pp 283If the 284.Fn (*ic_exec) 285function is not provided, the following 5 functions will be 286used by 287.Fn iic_exec 288in order to execute the I2C bus operation: 289.Bl -tag -width XXXX 290.It Fn (*ic_send_start) "cookie" "flags" 291Send a START condition on the I2C bus. 292The 293.Fa I2C_F_POLL 294flag indicates that sleeping is not permitted. 295.It Fn (*ic_send_stop) "cookie" "flags" 296Send a STOP condition on the I2C bus. 297The 298.Fa I2C_F_POLL 299flag indicates that sleeping is not permitted. 300.It Fn (*ic_initiate_xfer) "cookie" "addr" "flags" 301Initiate a transfer on the I2C bus by sending a START condition and 302then transmitting the I2C device address and transfer type. 303The 304.Fa I2C_F_READ 305flag indicates a read transfer; the lack of this flag indicates a 306write transfer. 307The 308.Fa I2C_F_POLL 309flag indicates that sleeping is not permitted. 310The error code 311.Dv ETIMEDOUT 312should be returned if a timeout that would indicate that the 313device is not present occurs. 314.It Fn (*ic_read_byte) "cookie" "datap" "flags" 315Read a byte from the I2C bus into the memory location referenced by 316.Fa datap . 317The 318.Fa I2C_F_LAST 319flag indicates that this is the final byte of the transfer, and that 320a NACK condition should be sent on the I2C bus following the transfer 321of the byte. 322The 323.Fa I2C_F_STOP 324flag indicates that a STOP condition should be sent on the I2C bus following 325the transfer of the byte. 326The 327.Fa I2C_F_POLL 328flag indicates that sleeping is not permitted. 329.It Fn (*ic_write_byte) "cookie" "data" "flags" 330Write the byte contained in 331.Fa data 332to the I2C bus. 333The 334.Fa I2C_F_STOP 335flag indicates that a STOP condition should be sent on the I2C bus following 336the transfer of the byte. 337The 338.Fa I2C_F_POLL 339flag indicates that sleeping is not permitted. 340.El 341.Sh SEE ALSO 342.Xr iic 4 343.Sh HISTORY 344The 345.Nm iic 346API first appeared in 347.Nx 2.0 . 348.Ox 349support was added in 350.Ox 3.6 . 351.Sh AUTHORS 352The 353.Nm iic 354API was written by 355Steve C. Woodford and Jason R. Thorpe for 356.Nx 357and then ported to 358.Ox 359by 360.An Alexander Yurchenko Aq Mt grange@openbsd.org . 361