Documentation/i2c/summary.rst

   1 =============================
   2 Introduction to I2C and SMBus
   3 =============================
   4
   5 I²C (pronounce: I squared C and written I2C in the kernel documentation) is
   6 a protocol developed by Philips. It is a two-wire protocol with variable
   7 speed (typically up to 400 kHz, high speed modes up to 5 MHz). It provides
   8 an inexpensive bus for connecting many types of devices with infrequent or
   9 low bandwidth communications needs. I2C is widely used with embedded
  10 systems. Some systems use variants that don't meet branding requirements,
  11 and so are not advertised as being I2C but come under different names,
  12 e.g. TWI (Two Wire Interface), IIC.
  13
  14 The latest official I2C specification is the `"I²C-bus specification and user
  15 manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_
  16 published by NXP Semiconductors, version 7 as of this writing.
  17
  18 SMBus (System Management Bus) is based on the I2C protocol, and is mostly
  19 a subset of I2C protocols and signaling. Many I2C devices will work on an
  20 SMBus, but some SMBus protocols add semantics beyond what is required to
  21 achieve I2C branding. Modern PC mainboards rely on SMBus. The most common
  22 devices connected through SMBus are RAM modules configured using I2C EEPROMs,
  23 and hardware monitoring chips.
  24
  25 Because the SMBus is mostly a subset of the generalized I2C bus, we can
  26 use its protocols on many I2C systems. However, there are systems that don't
  27 meet both SMBus and I2C electrical constraints; and others which can't
  28 implement all the common SMBus protocol semantics or messages.
  29
  30
  31 Terminology
  32 ===========
  33
  34 The I2C bus connects one or more controller chips and one or more target chips.
  35
  36 .. kernel-figure::  i2c_bus.svg
  37    :alt:    Simple I2C bus with one controller and 3 targets
  38
  39    Simple I2C bus
  40
  41 A **controller** chip is a node that starts communications with targets. In the
  42 Linux kernel implementation it is also called an "adapter" or "bus". Controller
  43 drivers are usually in the ``drivers/i2c/busses/`` subdirectory.
  44
  45 An **algorithm** contains general code that can be used to implement a whole
  46 class of I2C controllers. Each specific controller driver either depends on an
  47 algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes its
  48 own implementation.
  49
  50 A **target** chip is a node that responds to communications when addressed by a
  51 controller. In the Linux kernel implementation it is also called a "client".
  52 While targets are usually separate external chips, Linux can also act as a
  53 target (needs hardware support) and respond to another controller on the bus.
  54 This is then called a **local target**. In contrast, an external chip is called
  55 a **remote target**.
  56
  57 Target drivers are kept in a directory specific to the feature they provide,
  58 for example ``drivers/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for
  59 video-related chips.
  60
  61 For the example configuration in the figure above, you will need one driver for
  62 the I2C controller, and drivers for your I2C targets. Usually one driver for
  63 each target.
  64
  65 Synonyms
  66 --------
  67
  68 As mentioned above, the Linux I2C implementation historically uses the terms
  69 "adapter" for controller and "client" for target. A number of data structures
  70 have these synonyms in their name. So, when discussing implementation details,
  71 you should be aware of these terms as well. The official wording is preferred,
  72 though.
  73
  74 Outdated terminology
  75 --------------------
  76
  77 In earlier I2C specifications, controller was named "master" and target was
  78 named "slave". These terms have been obsoleted with v7 of the specification and
  79 their use is also discouraged by the Linux Kernel Code of Conduct. You may
  80 still find them in references to documentation which has not been updated. The
  81 general attitude, however, is to use the inclusive terms: controller and
  82 target. Work to replace the old terminology in the Linux Kernel is on-going.