Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) I\ :sup:`2`\ C and SMBus Subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) I\ :sup:`2`\ C (or without fancy typography, "I2C") is an acronym for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) the "Inter-IC" bus, a simple bus protocol which is widely used where low
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) data rate communications suffice. Since it's also a licensed trademark,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) some vendors use another name (such as "Two-Wire Interface", TWI) for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) the same bus. I2C only needs two signals (SCL for clock, SDA for data),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) conserving board real estate and minimizing signal quality issues. Most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) I2C devices use seven bit addresses, and bus speeds of up to 400 kHz;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) there's a high speed extension (3.4 MHz) that's not yet found wide use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) I2C is a multi-master bus; open drain signaling is used to arbitrate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) between masters, as well as to handshake and to synchronize clocks from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) slower clients.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) The Linux I2C programming interfaces support the master side of bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) interactions and the slave side. The programming interface is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) structured around two kinds of driver, and two kinds of device. An I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) "Adapter Driver" abstracts the controller hardware; it binds to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) physical device (perhaps a PCI device or platform_device) and exposes a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) :c:type:`struct i2c_adapter <i2c_adapter>` representing each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) I2C bus segment it manages. On each I2C bus segment will be I2C devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) represented by a :c:type:`struct i2c_client <i2c_client>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) Those devices will be bound to a :c:type:`struct i2c_driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) <i2c_driver>`, which should follow the standard Linux driver model. There
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) are functions to perform various I2C protocol operations; at this writing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) all such functions are usable only from task context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) The System Management Bus (SMBus) is a sibling protocol. Most SMBus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) systems are also I2C conformant. The electrical constraints are tighter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) for SMBus, and it standardizes particular protocol messages and idioms.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Controllers that support I2C can also support most SMBus operations, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) SMBus controllers don't support all the protocol options that an I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) controller will. There are functions to perform various SMBus protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) operations, either using I2C primitives or by issuing SMBus commands to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) i2c_adapter devices which don't support those I2C operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) .. kernel-doc:: include/linux/i2c.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)    :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) .. kernel-doc:: drivers/i2c/i2c-boardinfo.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)    :functions: i2c_register_board_info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) .. kernel-doc:: drivers/i2c/i2c-core-base.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)    :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) .. kernel-doc:: drivers/i2c/i2c-core-smbus.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)    :export: