kevin/linux
1
Fork 0
Code

docs: i2c: summary: be clearer with 'controller/target' and 'adapter/client' pairs

Browse Source 
This not only includes rewording, but also where to put which emphasis
on terms in this document.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Reviewed-by: Easwar Hariharan <eahariha@linux.microsoft.com>
Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
This commit is contained in:
Wolfram Sang 2024-06-21 09:30:13 +02:00
parent 1e926ea190
commit 20738cb9fa
1 changed files with 24 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
Documentation/i2c/summary.rst
View File

@ -31,9 +31,7 @@ implement all the common SMBus protocol semantics or messages.
Terminology Terminology
=========== ===========
The I2C bus connects one or more *controller* chips and one or more *target* The I2C bus connects one or more controller chips and one or more target chips.
chips.
.. kernel-figure:: i2c_bus.svg .. kernel-figure:: i2c_bus.svg
:alt: Simple I2C bus with one controller and 3 targets :alt: Simple I2C bus with one controller and 3 targets
@ -41,28 +39,37 @@ chips.
Simple I2C bus Simple I2C bus
A **controller** chip is a node that starts communications with targets. In the A **controller** chip is a node that starts communications with targets. In the
Linux kernel implementation it is called an **adapter** or bus. Adapter Linux kernel implementation it is also called an "adapter" or "bus". Controller
drivers are in the ``drivers/i2c/busses/`` subdirectory. drivers are usually in the ``drivers/i2c/busses/`` subdirectory.
An **algorithm** contains general code that can be used to implement a An **algorithm** contains general code that can be used to implement a whole
whole class of I2C adapters. Each specific adapter driver either depends on class of I2C controllers. Each specific controller driver either depends on an
an algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes its
its own implementation. own implementation.
A **target** chip is a node that responds to communications when addressed by a A **target** chip is a node that responds to communications when addressed by a
controller. In the Linux kernel implementation it is called a **client**. While controller. In the Linux kernel implementation it is also called a "client".
targets are usually separate external chips, Linux can also act as a target While targets are usually separate external chips, Linux can also act as a
(needs hardware support) and respond to another controller on the bus. This is target (needs hardware support) and respond to another controller on the bus.
then called a **local target**. In contrast, an external chip is called a This is then called a **local target**. In contrast, an external chip is called
**remote target**. a **remote target**.
Target drivers are kept in a directory specific to the feature they provide, Target drivers are kept in a directory specific to the feature they provide,
for example ``drivers/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for for example ``drivers/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for
video-related chips. video-related chips.
For the example configuration in figure, you will need a driver for your For the example configuration in the figure above, you will need one driver for
I2C adapter, and drivers for your I2C devices (usually one driver for each the I2C controller, and drivers for your I2C targets. Usually one driver for
device). each target.
Synonyms
--------
As mentioned above, the Linux I2C implementation historically uses the terms
"adapter" for controller and "client" for target. A number of data structures
have these synonyms in their name. So, when discussing implementation details,
you should be aware of these terms as well. The official wording is preferred,
though.
Outdated terminology Outdated terminology
-------------------- --------------------