IIC(9)

IIC(9) | NetBSD Kernel Developer's Manual | 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

#include <dev/i2c/i2cvar.h>

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 buflen, 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, buflen, 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 buflen 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 buflen 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 buflen 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), i2cscan(8)

NXP Semiconductors, I2C-bus Specification and User Manual, Revision 03, June 19, 2007, http://www.ics.nxp.com/support/documents/i2c/pdf/i2c.bus.specification.pdf.

Duracell Inc. et. al., System Management Bus (SMBus) Specification, Version 2.0, August 3, 2000, http://smbus.org/specs/smbus20.pdf.

# HISTORY

The iic API first appeared in NetBSD 2.0. OpenBSD support was added in OpenBSD 3.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>.

October 15, 2011 | NetBSD 5.99