Chapter 11. I2C and SMBus Subsystem

Table of Contents

struct i2c_driver — represent an I2C device driver
struct i2c_client — represent an I2C slave device
struct i2c_board_info — template for device creation
I2C_BOARD_INFO — macro used to list an i2c device and its address
struct i2c_algorithm — represent I2C transfer method
struct i2c_timings — I2C timing information
struct i2c_bus_recovery_info — I2C bus recovery information
struct i2c_adapter_quirks — describe flaws of an i2c adapter
i2c_check_quirks — Function for checking the quirk flags in an i2c adapter
module_i2c_driver — Helper macro for registering a modular I2C driver
builtin_i2c_driver — Helper macro for registering a builtin I2C driver
i2c_register_board_info — statically declare I2C devices
i2c_verify_client — return parameter as i2c_client, or NULL
i2c_lock_adapter — Get exclusive access to an I2C bus segment
i2c_unlock_adapter — Release exclusive access to an I2C bus segment
i2c_new_device — instantiate an i2c device
i2c_unregister_device — reverse effect of i2c_new_device
i2c_new_dummy — return a new i2c device bound to a dummy driver
i2c_verify_adapter — return parameter as i2c_adapter or NULL
i2c_add_adapter — declare i2c adapter, use dynamic bus number
i2c_add_numbered_adapter — declare i2c adapter, use static bus number
i2c_del_adapter — unregister I2C adapter
i2c_parse_fw_timings — get I2C related timing parameters from firmware
i2c_del_driver — unregister I2C driver
i2c_use_client — increments the reference count of the i2c client structure
i2c_release_client — release a use of the i2c client structure
__i2c_transfer — unlocked flavor of i2c_transfer
i2c_transfer — execute a single or combined I2C message
i2c_master_send — issue a single I2C message in master transmit mode
i2c_master_recv — issue a single I2C message in master receive mode
i2c_smbus_read_byte — SMBus receive byte protocol
i2c_smbus_write_byte — SMBus send byte protocol
i2c_smbus_read_byte_data — SMBus read byte protocol
i2c_smbus_write_byte_data — SMBus write byte protocol
i2c_smbus_read_word_data — SMBus read word protocol
i2c_smbus_write_word_data — SMBus write word protocol
i2c_smbus_read_block_data — SMBus block read protocol
i2c_smbus_write_block_data — SMBus block write protocol
i2c_smbus_xfer — execute SMBus protocol operations
i2c_smbus_read_i2c_block_data_or_emulated — read block or emulate

I2C (or without fancy typography, "I2C") is an acronym for the "Inter-IC" bus, a simple bus protocol which is widely used where low data rate communications suffice. Since it's also a licensed trademark, some vendors use another name (such as "Two-Wire Interface", TWI) for the same bus. I2C only needs two signals (SCL for clock, SDA for data), conserving board real estate and minimizing signal quality issues. Most I2C devices use seven bit addresses, and bus speeds of up to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet found wide use. I2C is a multi-master bus; open drain signaling is used to arbitrate between masters, as well as to handshake and to synchronize clocks from slower clients.

The Linux I2C programming interfaces support only the master side of bus interactions, not the slave side. The programming interface is structured around two kinds of driver, and two kinds of device. An I2C "Adapter Driver" abstracts the controller hardware; it binds to a physical device (perhaps a PCI device or platform_device) and exposes a struct i2c_adapter representing each I2C bus segment it manages. On each I2C bus segment will be I2C devices represented by a struct i2c_client. Those devices will be bound to a struct i2c_driver, which should follow the standard Linux driver model. (At this writing, a legacy model is more widely used.) There are functions to perform various I2C protocol operations; at this writing all such functions are usable only from task context.

The System Management Bus (SMBus) is a sibling protocol. Most SMBus systems are also I2C conformant. The electrical constraints are tighter for SMBus, and it standardizes particular protocol messages and idioms. Controllers that support I2C can also support most SMBus operations, but SMBus controllers don't support all the protocol options that an I2C controller will. There are functions to perform various SMBus protocol operations, either using I2C primitives or by issuing SMBus commands to i2c_adapter devices which don't support those I2C operations.