January 12, 2006 IIC 9

### NAME

iic_acquire_bus, iic_release_bus, iic_exec, iic_smbus_write_byte, iic_smbus_read_byte, iic_smbus_receive_byte - Inter IC (I2C) bus

### SYNOPSIS

```int` iic_acquire_bus(`` ```i2c_tag_t ic` ```int flags` )
```int` iic_release_bus(`` ```i2c_tag_t ic` ```int flags` )
```int` iic_exec(`` ```i2c_tag_t ic` ```i2c_op_t op` ```i2c_addr_t addr` ```const void *cmdbuf` ```size_t cmdlen` ```void *buf` ```size_t len` ```int flags` )
```int` iic_smbus_write_byte(`` ```i2c_tag_t ic` ```i2c_addr_t addr` ```uint8_t cmd` ```uint8_t data` ```int flags` )
```int` iic_smbus_read_byte(`` ```i2c_tag_t ic` ```i2c_addr_t addr` ```uint8_t cmd` ```uint8_t *datap` ```int flags` )
```int` iic_smbus_receive_byte(`` ```i2c_tag_t ic` ```i2c_addr_t addr` ```uint8_t *datap` ```int flags` )

### DESCRIPTION

I2C is a two-wire bus developed by Philips used for connecting integrated circuits. It is commonly used for connecting devices such as EEPROMs, temperature sensors, fan controllers, real-time clocks, tuners, and other types of integrated circuits. The iic interface provides a means of communicating with I2C-connected devices. The System Management Bus, or SMBus, is a variant of the I2C bus with a simplified command protocol and some electrical differences.

### DATA TYPES

Drivers for devices attached to the I2C bus will make use of the following data types:

```i2c_tag_t`
  Controller tag for the I2C bus. This is a pointer to a ```struct` `i2c_controller`, consisting of function pointers filled in by the I2C controller driver.

```i2c_op_t`
  I2C bus operation. The following I2C bus operations are defined:

  I2C_OP_READ
    Perform a read operation.

  I2C_OP_READ_WITH_STOP
    Perform a read operation and send a STOP condition on the I2C bus at the conclusion of the read.

  I2C_OP_WRITE
    Perform a write operation.

  I2C_OP_WRITE_WITH_STOP
    Perform a write operation and send a STOP condition on the I2C bus at the conclusion of the write.

```i2c_addr_t`
  I2C device address.

```struct` `i2c_attach_args`
  Devices are attached to an I2C bus using this structure. The structure is defined as follows: `

      struct i2c_attach_args {
              i2c_tag_t ia_tag;       /* controller */
              i2c_addr_t ia_addr;     /* address of device */
              int ia_size;            /* size (for EEPROMs) */
      };

  `

### FUNCTIONS

The following functions comprise the API provided to drivers of I2C-connected devices:

iic_acquire_bus(```ic``, flags`)
  Acquire an exclusive lock on the I2C bus. This is required since only one device may communicate on the I2C bus at a time. Drivers should acquire the bus lock, perform the I2C bus operations necessary, and then release the bus lock. Passing the ```I2C_F_POLL` flag indicates to iic_acquire_bus(``) that sleeping is not permitted.

iic_release_bus(```ic``, flags`)
  Release an exclusive lock on the I2C bus. If the ```I2C_F_POLL` flag was passed to iic_acquire_bus(``), it must also be passed to iic_release_bus(``).

iic_exec(```ic``, op``, addr``, cmdbuf``, cmdlen``, buf``, len``, flags`)
  Perform a series of I2C transactions on the bus. iic_exec(``) initiates the operation by sending a START condition on the I2C bus and then transmitting the address of the target device along with the transaction type. If ```cmdlen` is non-zero, the command pointed to by ```cmdbuf` is then sent to the device. If ```buflen` is non-zero, iic_exec(``) will then transmit or receive the data, as indicated by ```op`. If ```op` indicates a read operation, iic_exec(``) will send a REPEATED START before transferring the data. If ```op` so indicates, a STOP condition will be sent on the I2C bus at the conclusion of the operation. Passing the ```I2C_F_POLL` flag indicates to iic_exec(``) that sleeping is not permitted.

iic_smbus_write_byte(```ic``, addr``, cmd``, data``, flags`)
  Perform an SMBus WRITE BYTE operation. This is equivalent to I2C_OP_WRITE_WITH_STOP with ```cmdlen` of 1 and ```len` of 1.

iic_smbus_read_byte(```ic``, addr``, cmd``, datap``, flags`)
  Perform an SMBus READ BYTE operation. This is equivalent to I2C_OP_READ_WITH_STOP with ```cmdlen` of 1 and ```len` of 1.

iic_smbus_receive_byte(```ic``, addr``, datap``, flags`)
  Perform an SMBus RECEIVE BYTE operation. This is equivalent to I2C_OP_READ_WITH_STOP with ```cmdlen` of 0 and ```len` of 1.

### CONTROLLER INTERFACE

The I2C controller driver must fill in the function pointers of an ```i2c_controller` structure, which is defined as follows: `

    struct i2c_controller {
            void    *ic_cookie;     /* controller private */

            int     (*ic_acquire_bus)(void *, int);
            void    (*ic_release_bus)(void *, int);

            int     (*ic_exec)(void *, i2c_op_t, i2c_addr_t,
                       const void *, size_t, void *, size_t, int);

            int     (*ic_send_start)(void *, int);
            int     (*ic_send_stop)(void *, int);
            int     (*ic_initiate_xfer)(void *, i2c_addr_t, int);
            int     (*ic_read_byte)(void *, uint8_t *, int);
            int     (*ic_write_byte)(void *, uint8_t, int);
    };

`

The (*ic_acquire_bus)(``) and (*ic_release_bus)(``) functions must always be provided.

The controller driver may elect to provide an (*ic_exec)(``) function. This function is intended for use by automated controllers that do not provide manual control over I2C bus conditions such as START and STOP.

If the (*ic_exec)(``) function is not provided, the following 5 functions will be used by iic_exec(``) in order to execute the I2C bus operation:

(*ic_send_start)(```cookie``, flags`)
  Send a START condition on the I2C bus. The ```I2C_F_POLL` flag indicates that sleeping is not permitted.

(*ic_send_stop)(```cookie``, flags`)
  Send a STOP condition on the I2C bus. The ```I2C_F_POLL` flag indicates that sleeping is not permitted.

(*ic_initiate_xfer)(```cookie``, addr``, flags`)
  Initiate a transfer on the I2C bus by sending a START condition and then transmitting the I2C device address and transfer type. The ```I2C_F_READ` flag indicates a read transfer; the lack of this flag indicates a write transfer. The ```I2C_F_POLL` flag indicates that sleeping is not permitted. The error code ```ETIMEDOUT` should be returned if a timeout that would indicate that the device is not present occurs.

(*ic_read_byte)(```cookie``, datap``, flags`)
  Read a byte from the I2C bus into the memory location referenced by ```datap`. The ```I2C_F_LAST` flag indicates that this is the final byte of the transfer, and that a NACK condition should be sent on the I2C bus following the transfer of the byte. The ```I2C_F_STOP` flag indicates that a STOP condition should be sent on the I2C bus following the transfer of the byte. The ```I2C_F_POLL` flag indicates that sleeping is not permitted.

(*ic_write_byte)(```cookie``, data``, flags`)
  Write the byte contained in ```data` to the I2C bus. The ```I2C_F_STOP` flag indicates that a STOP condition should be sent on the I2C bus following the transfer of the byte. The ```I2C_F_POLL` flag indicates that sleeping is not permitted.

### SEE ALSO

iic(4)

### HISTORY

The iic API first appeared in NetBSD2.0. OpenBSD support was added in OpenBSD3.6.

### AUTHORS

The iic API was written by Steve C. Woodford and Jason R. Thorpe for NetBSD and then ported to OpenBSD by Alexander Yurchenko <grange@openbsd.org>
.