Commit 020bc5b9 authored by Luca Ceresoli's avatar Luca Ceresoli Committed by Wolfram Sang
Browse files

docs: i2c: summary: rewrite the "terminology" section 



This section, partly dating back to the pre-git era, is somewhat
unclear and partly incorrect. Rewrite it almost completely including a
reference figure, concise but precise definition of each term and the
paths where drivers are found. Particular care has been put in clarifying
the relation between adapter and algorithm, which has no correspondence
in the I2C spec terminology.

Signed-off-by: default avatarLuca Ceresoli <luca@lucaceresoli.net>
Reviewed-by: default avatarJean Delvare <jdelvare@suse.de>
Signed-off-by: default avatarWolfram Sang <wsa@the-dreams.de>
parent 096c22f8

Documentation/i2c/i2c.svg

0 → 100644
+1341 −0

File added.

Preview size limit exceeded, changes collapsed.

Documentation/i2c/summary.rst

+22 −14
Original line number Diff line number Diff line
@@ -31,21 +31,29 @@ implement all the common SMBus protocol semantics or messages. 
Terminology

===========



When we talk about I2C, we use the following terms::

Using the terminology from the official documentation, the I2C bus connects

one or more *master* chips and one or more *slave* chips.



  Bus    -> Algorithm

            Adapter

  Device -> Driver

            Client

.. kernel-figure::  i2c.svg

   :alt:    Simple I2C bus with one master and 3 slaves



An Algorithm driver contains general code that can be used for a whole class

of I2C adapters. Each specific adapter driver either depends on one algorithm

driver, or includes its own implementation.

   Simple I2C bus



A Driver driver (yes, this sounds ridiculous, sorry) contains the general

code to access some type of device. Each detected device gets its own

data in the Client structure. Usually, Driver and Client are more closely

integrated than Algorithm and Adapter.

A **master** chip is a node that starts communications with slaves. In the

Linux kernel implementation it is called an **adapter** or bus. Adapter

drivers are in the ``drivers/i2c/busses/`` subdirectory.



For a given configuration, you will need a driver for your I2C bus, and

drivers for your I2C devices (usually one driver for each device).
 
An **algorithm** contains general code that can be used to implement a

whole class of I2C adapters. Each specific adapter driver either depends on

an algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes

its own implementation.



A **slave** chip is a node that responds to communications when addressed

by the master. In Linux it is called a **client**. Client drivers are kept

in a directory specific to the feature they provide, for example

``drivers/media/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for

video-related chips.



For the example configuration in figure, you will need a driver for your

I2C adapter, and drivers for your I2C devices (usually one driver for each

device).

CRA Git | Maintained and supported by SUSTech CRA and CCSE