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: Luca Ceresoli <luca@lucaceresoli.net>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>
This commit is contained in:
Luca Ceresoli 2020-01-29 16:19:28 +01:00 committed by Wolfram Sang
parent 096c22f88e
commit 020bc5b929
2 changed files with 1363 additions and 14 deletions

1341
Documentation/i2c/i2c.svg Normal file

File diff suppressed because it is too large Load Diff

After

Width:  |  Height:  |  Size: 55 KiB

View File

@ -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).