[PATCH v3 0/6] docs: i2c: summary: update and use inclusive wording

[PATCH v3 0/6] docs: i2c: summary: update and use inclusive wording

[Wolfram Sang]

The main motivation for this series is patch 4: switching to
"controller/master" when defining the I2C terminology. This sets the
base for further improvements to inclusive language within the Linux
Kernel. The other patches are improvements found on the way.

Changes since v2:
* improve patch 6 to be more clear wrt to the synonyms 'adapter/client'
* fix the faulty 'drivers/media/gpio' path
* slight rewording in patches 4 and 5

Wolfram Sang (6):
  docs: i2c: summary: start sentences consistently.
  docs: i2c: summary: update I2C specification link
  docs: i2c: summary: update speed mode description
  docs: i2c: summary: document use of inclusive language
  docs: i2c: summary: document 'local' and 'remote' targets
  docs: i2c: summary: be clearer with 'controller/target' and
    'adapter/client' pairs

 Documentation/i2c/i2c_bus.svg | 15 +++----
 Documentation/i2c/summary.rst | 79 ++++++++++++++++++++++-------------
 2 files changed, 58 insertions(+), 36 deletions(-)

-- 
2.43.0

[PATCH v3 1/6] docs: i2c: summary: start sentences consistently.

[Wolfram Sang]

Change the first paragraphs to contain only one space after the end of
the previous sentence like in the rest of the document.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Reviewed-by: Easwar Hariharan <eahariha@linux.microsoft.com>
---
 Documentation/i2c/summary.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index 786c618ba3be..28ff80a2302b 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -4,10 +4,10 @@ Introduction to I2C and SMBus
 
 I²C (pronounce: I squared C and written I2C in the kernel documentation) is
 a protocol developed by Philips. It is a slow two-wire protocol (variable
-speed, up to 400 kHz), with a high speed extension (3.4 MHz).  It provides
+speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides
 an inexpensive bus for connecting many types of devices with infrequent or
-low bandwidth communications needs.  I2C is widely used with embedded
-systems.  Some systems use variants that don't meet branding requirements,
+low bandwidth communications needs. I2C is widely used with embedded
+systems. Some systems use variants that don't meet branding requirements,
 and so are not advertised as being I2C but come under different names,
 e.g. TWI (Two Wire Interface), IIC.
 
@@ -18,14 +18,14 @@ access the PDF. An older version of the specification (revision 6) is archived
 `here <https://web.archive.org/web/20210813122132/https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
 
 SMBus (System Management Bus) is based on the I2C protocol, and is mostly
-a subset of I2C protocols and signaling.  Many I2C devices will work on an
+a subset of I2C protocols and signaling. Many I2C devices will work on an
 SMBus, but some SMBus protocols add semantics beyond what is required to
-achieve I2C branding.  Modern PC mainboards rely on SMBus.  The most common
+achieve I2C branding. Modern PC mainboards rely on SMBus. The most common
 devices connected through SMBus are RAM modules configured using I2C EEPROMs,
 and hardware monitoring chips.
 
 Because the SMBus is mostly a subset of the generalized I2C bus, we can
-use its protocols on many I2C systems.  However, there are systems that don't
+use its protocols on many I2C systems. However, there are systems that don't
 meet both SMBus and I2C electrical constraints; and others which can't
 implement all the common SMBus protocol semantics or messages.
 
-- 
2.43.0

Re: [PATCH v3 1/6] docs: i2c: summary: start sentences consistently.

[Andi Shyti]

Hi Wolfram,

On Fri, Jun 14, 2024 at 10:12:39AM GMT, Wolfram Sang wrote:
> Change the first paragraphs to contain only one space after the end of
> the previous sentence like in the rest of the document.
> 
> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
> Reviewed-by: Easwar Hariharan <eahariha@linux.microsoft.com>

Reviewed-by: Andi Shyti <andi.shyti@kernel.org>

Thanks,
Andi

[PATCH v3 2/6] docs: i2c: summary: update I2C specification link

[Wolfram Sang]

Luckily, the specs are directly downloadable again, so update the link.
Also update its title to the original name "I²C".

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Reviewed-by: Easwar Hariharan <eahariha@linux.microsoft.com>
---
 Documentation/i2c/summary.rst | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index 28ff80a2302b..e3ab1d414014 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -11,11 +11,9 @@ systems. Some systems use variants that don't meet branding requirements,
 and so are not advertised as being I2C but come under different names,
 e.g. TWI (Two Wire Interface), IIC.
 
-The latest official I2C specification is the `"I2C-bus specification and user
-manual" (UM10204) <https://www.nxp.com/webapp/Download?colCode=UM10204>`_
-published by NXP Semiconductors. However, you need to log-in to the site to
-access the PDF. An older version of the specification (revision 6) is archived
-`here <https://web.archive.org/web/20210813122132/https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
+The latest official I2C specification is the `"I²C-bus specification and user
+manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_
+published by NXP Semiconductors, version 7 as of this writing.
 
 SMBus (System Management Bus) is based on the I2C protocol, and is mostly
 a subset of I2C protocols and signaling. Many I2C devices will work on an
-- 
2.43.0

Re: [PATCH v3 2/6] docs: i2c: summary: update I2C specification link

[Andi Shyti]

Hi Wolfram,

On Fri, Jun 14, 2024 at 10:12:40AM GMT, Wolfram Sang wrote:
> Luckily, the specs are directly downloadable again, so update the link.
> Also update its title to the original name "I²C".
> 
> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
> Reviewed-by: Easwar Hariharan <eahariha@linux.microsoft.com>

Reviewed-by: Andi Shyti <andi.shyti@kernel.org>

Thanks,
Andi

[PATCH v3 3/6] docs: i2c: summary: update speed mode description

[Wolfram Sang]

Fastest I2C mode is 5 MHz. Update the docs and reword the paragraph
slightly.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Reviewed-by: Easwar Hariharan <eahariha@linux.microsoft.com>
---
 Documentation/i2c/summary.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index e3ab1d414014..a1e5c0715f8b 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -3,8 +3,8 @@ Introduction to I2C and SMBus
 =============================
 
 I²C (pronounce: I squared C and written I2C in the kernel documentation) is
-a protocol developed by Philips. It is a slow two-wire protocol (variable
-speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides
+a protocol developed by Philips. It is a two-wire protocol with variable
+speed (typically up to 400 kHz, high speed modes up to 5 MHz). It provides
 an inexpensive bus for connecting many types of devices with infrequent or
 low bandwidth communications needs. I2C is widely used with embedded
 systems. Some systems use variants that don't meet branding requirements,
-- 
2.43.0

Re: [PATCH v3 3/6] docs: i2c: summary: update speed mode description

[Andi Shyti]

Hi Wolfram,

On Fri, Jun 14, 2024 at 10:12:41AM GMT, Wolfram Sang wrote:
> Fastest I2C mode is 5 MHz. Update the docs and reword the paragraph
> slightly.

> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
> Reviewed-by: Easwar Hariharan <eahariha@linux.microsoft.com>
> ---
>  Documentation/i2c/summary.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
> index e3ab1d414014..a1e5c0715f8b 100644
> --- a/Documentation/i2c/summary.rst
> +++ b/Documentation/i2c/summary.rst
> @@ -3,8 +3,8 @@ Introduction to I2C and SMBus
>  =============================
>  
>  I²C (pronounce: I squared C and written I2C in the kernel documentation) is
> -a protocol developed by Philips. It is a slow two-wire protocol (variable
> -speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides
> +a protocol developed by Philips. It is a two-wire protocol with variable
> +speed (typically up to 400 kHz, high speed modes up to 5 MHz). It provides

In a single sentence explanation this is correct :-)

Reviewed-by: Andi Shyti <andi.shyti@kernel.org>

Thanks,
Andi

>  an inexpensive bus for connecting many types of devices with infrequent or
>  low bandwidth communications needs. I2C is widely used with embedded
>  systems. Some systems use variants that don't meet branding requirements,
> -- 
> 2.43.0
> 

[PATCH v3 4/6] docs: i2c: summary: document use of inclusive language

[Wolfram Sang]

We now have the updated I2C specs and our own Code of Conduct, so we
have all we need to switch over to the inclusive terminology. Define
them here.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
---
 Documentation/i2c/i2c_bus.svg | 15 ++++++++-------
 Documentation/i2c/summary.rst | 23 +++++++++++++++++------
 2 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/Documentation/i2c/i2c_bus.svg b/Documentation/i2c/i2c_bus.svg
index 3170de976373..45801de4af7d 100644
--- a/Documentation/i2c/i2c_bus.svg
+++ b/Documentation/i2c/i2c_bus.svg
@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
+<!-- Updated to inclusive terminology by Wolfram Sang -->
 
 <svg
    xmlns:dc="http://purl.org/dc/elements/1.1/"
@@ -1120,7 +1121,7 @@
     <rect
        style="opacity:1;fill:#ffb9b9;fill-opacity:1;stroke:#f00000;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
        id="rect4424-3-2-9-7"
-       width="112.5"
+       width="134.5"
        height="113.75008"
        x="112.5"
        y="471.11221"
@@ -1133,15 +1134,15 @@
        y="521.46259"
        id="text4349"><tspan
          sodipodi:role="line"
-         x="167.5354"
+         x="178.5354"
          y="521.46259"
          style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle"
          id="tspan1273">I2C</tspan><tspan
          sodipodi:role="line"
-         x="167.5354"
+         x="178.5354"
          y="552.71259"
          style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle"
-         id="tspan1285">Master</tspan></text>
+         id="tspan1285">Controller</tspan></text>
     <rect
        style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
        id="rect4424-3-2-9-7-3-3-5-3"
@@ -1171,7 +1172,7 @@
          x="318.59131"
          y="552.08752"
          style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
-         id="tspan1287">Slave</tspan></text>
+         id="tspan1287">Target</tspan></text>
     <path
        style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968767;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
        d="m 112.49995,677.36223 c 712.50005,0 712.50005,0 712.50005,0"
@@ -1233,7 +1234,7 @@
          x="468.59131"
          y="552.08746"
          style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
-         id="tspan1287-6">Slave</tspan></text>
+         id="tspan1287-6">Target</tspan></text>
     <rect
        style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
        id="rect4424-3-2-9-7-3-3-5-3-1"
@@ -1258,7 +1259,7 @@
          x="618.59131"
          y="552.08746"
          style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
-         id="tspan1287-9">Slave</tspan></text>
+         id="tspan1287-9">Target</tspan></text>
     <path
        style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM)"
        d="m 150,583.61221 v 93.75"
diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index a1e5c0715f8b..a6da1032fa06 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -31,15 +31,16 @@ implement all the common SMBus protocol semantics or messages.
 Terminology
 ===========
 
-Using the terminology from the official documentation, the I2C bus connects
-one or more *master* chips and one or more *slave* chips.
+The I2C bus connects one or more *controller* chips and one or more *target*
+chips.
+
 
 .. kernel-figure::  i2c_bus.svg
-   :alt:    Simple I2C bus with one master and 3 slaves
+   :alt:    Simple I2C bus with one controller and 3 targets
 
    Simple I2C bus
 
-A **master** chip is a node that starts communications with slaves. 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
 drivers are in the ``drivers/i2c/busses/`` subdirectory.
 
@@ -48,8 +49,8 @@ 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
+A **target** chip is a node that responds to communications when addressed
+by the controller. 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.
@@ -57,3 +58,13 @@ 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).
+
+Outdated terminology
+--------------------
+
+In earlier I2C specifications, controller was named "master" and target was
+named "slave". These terms have been obsoleted with v7 of the specification and
+their use is also discouraged by the Linux Kernel Code of Conduct. You may
+still find them in references to documentation which has not been updated. The
+general attitude, however, is to use the inclusive terms: controller and
+target. Work to replace the old terminology in the Linux Kernel is on-going.
-- 
2.43.0

Re: [PATCH v3 4/6] docs: i2c: summary: document use of inclusive language

[Andi Shyti]

Hi Wolfram,

On Fri, Jun 14, 2024 at 10:12:42AM GMT, Wolfram Sang wrote:
> We now have the updated I2C specs and our own Code of Conduct, so we
> have all we need to switch over to the inclusive terminology. Define
> them here.
> 
> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>

Reviewed-by: Andi Shyti <andi.shyti@kernel.org>

Thanks,
Andi

[PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Wolfram Sang]

Because Linux can be a target as well, add terminology to differentiate
between Linux being the target and Linux accessing targets.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
---
 Documentation/i2c/summary.rst | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index a6da1032fa06..ff8bda32b9c3 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -49,10 +49,15 @@ 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 **target** chip is a node that responds to communications when addressed
-by the controller. 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
+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
+targets are usually separate external chips, Linux can also act as a target
+(needs hardware support) and respond to another controller on the bus. This is
+then called a **local target**. In contrast, an external chip is called a
+**remote target**.
+
+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
 video-related chips.
 
 For the example configuration in figure, you will need a driver for your
-- 
2.43.0

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Andi Shyti]

Hi Wolfram,

...

> -A **target** chip is a node that responds to communications when addressed
> -by the controller. 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
> +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

I am not a big fan of the use of the word client. It's not used
anywhere in the documentation and it's too generic as a name for
giving it a specific meaning.

I've seen already some confusion amongst reviewers and
maintainers when Easwar sent the patch in drm.

If it depends on me, I would stick to the only controller/target
and render obsolet the use of the word "client" in the i2c
context.

Andi

> +targets are usually separate external chips, Linux can also act as a target
> +(needs hardware support) and respond to another controller on the bus. This is
> +then called a **local target**. In contrast, an external chip is called a
> +**remote target**.
> +
> +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
>  video-related chips.
>  
>  For the example configuration in figure, you will need a driver for your
> -- 
> 2.43.0
> 

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 631 bytes --]

Hi Andi,

> I am not a big fan of the use of the word client. It's not used
> anywhere in the documentation and it's too generic as a name for
> giving it a specific meaning.
> 
> I've seen already some confusion amongst reviewers and
> maintainers when Easwar sent the patch in drm.
> 
> If it depends on me, I would stick to the only controller/target
> and render obsolet the use of the word "client" in the i2c
> context.

Have you read the paragraph "Synonyms" from patch 6? I don't think we
can obsolete client because:

$ git grep 'struct i2c_client \*client' | wc -l
6100

All the best,

   Wolfram


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Andi Shyti]

Hi Wolfram,

On Sun, Jun 16, 2024 at 09:14:40PM GMT, Wolfram Sang wrote:
> > I am not a big fan of the use of the word client. It's not used
> > anywhere in the documentation and it's too generic as a name for
> > giving it a specific meaning.
> > 
> > I've seen already some confusion amongst reviewers and
> > maintainers when Easwar sent the patch in drm.
> > 
> > If it depends on me, I would stick to the only controller/target
> > and render obsolet the use of the word "client" in the i2c
> > context.
> 
> Have you read the paragraph "Synonyms" from patch 6? I don't think we
> can obsolete client because:
> 
> $ git grep 'struct i2c_client \*client' | wc -l
> 6100

yes, I know, but I would be happy if we start changing i2c_client
with i2c_target and at least saying that "target" is the
preferred name for what was called "client" until now.

I think we should start somewhere from using the new naming
provided by the documentation.

Other than that, I'm not blocking the patch, it's a great
improvement! I'm just trying use this chance to discuss and bring
up new opinions.

Thanks,
Andi

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 1943 bytes --]

Hi Andi

> > Have you read the paragraph "Synonyms" from patch 6? I don't think we
> > can obsolete client because:
> > 
> > $ git grep 'struct i2c_client \*client' | wc -l
> > 6100
> 
> yes, I know, but I would be happy if we start changing i2c_client
> with i2c_target and at least saying that "target" is the
> preferred name for what was called "client" until now.

This is largely what patch 6 does? Let me quote:

+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, to discuss implementation details, it                                                                                                                     │
+might be easier to use these terms. If speaking about I2C in general, the                                                                                                                        │
+official terminology is preferred.                                                                                                                                                               │

> I think we should start somewhere from using the new naming
> provided by the documentation.

I think I can justify replacing "master/slave" and create quite some
churn because that terminology is unwanted language.

I think I cannot justify replacing "adapter/client" just because it
doesn't match the spec. Plus, the churn would be a lot bigger.

If everyone (especially affected subsystem maintainers) is like "Yeah,
do it!" I can do it. But I have my doubts...

Happy hacking,

   Wolfram


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Easwar Hariharan]

On 6/17/2024 4:58 AM, Andi Shyti wrote:
> Hi Wolfram,
> 
> On Sun, Jun 16, 2024 at 09:14:40PM GMT, Wolfram Sang wrote:
>>> I am not a big fan of the use of the word client. It's not used
>>> anywhere in the documentation and it's too generic as a name for
>>> giving it a specific meaning.
>>>
>>> I've seen already some confusion amongst reviewers and
>>> maintainers when Easwar sent the patch in drm.
>>>
>>> If it depends on me, I would stick to the only controller/target
>>> and render obsolet the use of the word "client" in the i2c
>>> context.
>>
>> Have you read the paragraph "Synonyms" from patch 6? I don't think we
>> can obsolete client because:
>>
>> $ git grep 'struct i2c_client \*client' | wc -l
>> 6100

> at least saying that "target" is the
> preferred name for what was called "client" until now.

I'm in agreement on obsoleting "client" as well. On the pace of change,
I'll defer to you. I was trying to elicit a recommendation on future use
of "client" when I asked:

===
What's the combined effect of this documentation update in terms of the
recommendation for switching over the Linux kernel? Are we to use
controller/client or controller/target?
===

"Synonyms" from patch 6 does say that controller/target is preferred but
couched it in the caveat "If speaking about I2C in general" and
adapter/client when "discuss[ing] implementation details." I was trying
to give space for an unambiguous recommendation.

I think we are on the same page here if we just remove the caveats.

Thanks,
Easwar

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Andi Shyti]

Hi,

On Mon, Jun 17, 2024 at 09:57:12AM GMT, Easwar Hariharan wrote:
> On 6/17/2024 4:58 AM, Andi Shyti wrote:
> > On Sun, Jun 16, 2024 at 09:14:40PM GMT, Wolfram Sang wrote:
> >>> I am not a big fan of the use of the word client. It's not used
> >>> anywhere in the documentation and it's too generic as a name for
> >>> giving it a specific meaning.
> >>>
> >>> I've seen already some confusion amongst reviewers and
> >>> maintainers when Easwar sent the patch in drm.
> >>>
> >>> If it depends on me, I would stick to the only controller/target
> >>> and render obsolet the use of the word "client" in the i2c
> >>> context.
> >>
> >> Have you read the paragraph "Synonyms" from patch 6? I don't think we
> >> can obsolete client because:
> >>
> >> $ git grep 'struct i2c_client \*client' | wc -l
> >> 6100
> 
> > at least saying that "target" is the
> > preferred name for what was called "client" until now.
> 
> I'm in agreement on obsoleting "client" as well. On the pace of change,
> I'll defer to you. I was trying to elicit a recommendation on future use
> of "client" when I asked:
> 
> ===
> What's the combined effect of this documentation update in terms of the
> recommendation for switching over the Linux kernel? Are we to use
> controller/client or controller/target?
> ===
> 
> "Synonyms" from patch 6 does say that controller/target is preferred but
> couched it in the caveat "If speaking about I2C in general" and
> adapter/client when "discuss[ing] implementation details." I was trying
> to give space for an unambiguous recommendation.

Exactly, this is what I referred to in my previous e-mails.
These two statements sound a bit ambiguous to me, as well.

Maybe we are wasting time at discussing minor details, but I
consider this part important in order to give way to the major
refactoring that Wolfram started at the beginning.

Of course, as of now, I agree that replacing every "client" to
"target" might not make much sense.

Thanks,
Andi

> I think we are on the same page here if we just remove the caveats.
> 
> Thanks,
> Easwar
> 

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 1665 bytes --]

Hi,

> > "Synonyms" from patch 6 does say that controller/target is preferred but
> > couched it in the caveat "If speaking about I2C in general" and
> > adapter/client when "discuss[ing] implementation details." I was trying
> > to give space for an unambiguous recommendation.
> 
> Exactly, this is what I referred to in my previous e-mails.
> These two statements sound a bit ambiguous to me, as well.

Okay, here is my proposed update:

===

diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index 90f46f1504fe..579a1c7df200 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -67,9 +67,9 @@ 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, to discuss implementation details, it
-might be easier to use these terms. If speaking about I2C in general, the
-official terminology is preferred.
+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.

===

I don't want to be stricter than "preferred". If someone still wants to
use 'struct i2c_client *client' this is fine with me.

> Maybe we are wasting time at discussing minor details, but I
> consider this part important in order to give way to the major
> refactoring that Wolfram started at the beginning.

The refactoring only affects "master/slave" not "adapter/client". We are

aligned here, aren't we?

All the best,

   Wolfram


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Easwar Hariharan]

On 6/19/2024 12:10 AM, Wolfram Sang wrote:
> Hi,
> 
>>> "Synonyms" from patch 6 does say that controller/target is preferred but
>>> couched it in the caveat "If speaking about I2C in general" and
>>> adapter/client when "discuss[ing] implementation details." I was trying
>>> to give space for an unambiguous recommendation.
>>
>> Exactly, this is what I referred to in my previous e-mails.
>> These two statements sound a bit ambiguous to me, as well.
> 
> Okay, here is my proposed update:
> 
> ===
> 
> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
> index 90f46f1504fe..579a1c7df200 100644
> --- a/Documentation/i2c/summary.rst
> +++ b/Documentation/i2c/summary.rst
> @@ -67,9 +67,9 @@ 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, to discuss implementation details, it
> -might be easier to use these terms. If speaking about I2C in general, the
> -official terminology is preferred.
> +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.
> 
> ===
> 
> I don't want to be stricter than "preferred". If someone still wants to
> use 'struct i2c_client *client' this is fine with me.

I'm ok with this. I'll let Andi decide if he wants to have
adapter/client refactoring now or in the future or at all.

Thanks,
Easwar

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Andi Shyti]

On Thu, Jun 20, 2024 at 09:05:43AM GMT, Easwar Hariharan wrote:
> On 6/19/2024 12:10 AM, Wolfram Sang wrote:
> >>> "Synonyms" from patch 6 does say that controller/target is preferred but
> >>> couched it in the caveat "If speaking about I2C in general" and
> >>> adapter/client when "discuss[ing] implementation details." I was trying
> >>> to give space for an unambiguous recommendation.
> >>
> >> Exactly, this is what I referred to in my previous e-mails.
> >> These two statements sound a bit ambiguous to me, as well.
> > 
> > Okay, here is my proposed update:
> > 
> > ===
> > 
> > diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
> > index 90f46f1504fe..579a1c7df200 100644
> > --- a/Documentation/i2c/summary.rst
> > +++ b/Documentation/i2c/summary.rst
> > @@ -67,9 +67,9 @@ 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, to discuss implementation details, it
> > -might be easier to use these terms. If speaking about I2C in general, the
> > -official terminology is preferred.
> > +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.
> > 
> > ===
> > 
> > I don't want to be stricter than "preferred". If someone still wants to
> > use 'struct i2c_client *client' this is fine with me.
> 
> I'm ok with this. I'll let Andi decide if he wants to have
> adapter/client refactoring now or in the future or at all.

yes, let's see how it goes.

Thanks, Easwar!

Andi

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Andi Shyti]

Hi Wolfram,

On Wed, Jun 19, 2024 at 09:10:26AM GMT, Wolfram Sang wrote:
> > > "Synonyms" from patch 6 does say that controller/target is preferred but
> > > couched it in the caveat "If speaking about I2C in general" and
> > > adapter/client when "discuss[ing] implementation details." I was trying
> > > to give space for an unambiguous recommendation.
> > 
> > Exactly, this is what I referred to in my previous e-mails.
> > These two statements sound a bit ambiguous to me, as well.
> 
> Okay, here is my proposed update:
> 
> ===
> 
> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
> index 90f46f1504fe..579a1c7df200 100644
> --- a/Documentation/i2c/summary.rst
> +++ b/Documentation/i2c/summary.rst
> @@ -67,9 +67,9 @@ 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, to discuss implementation details, it
> -might be easier to use these terms. If speaking about I2C in general, the
> -official terminology is preferred.
> +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.

ACK!

> ===
> 
> I don't want to be stricter than "preferred". If someone still wants to
> use 'struct i2c_client *client' this is fine with me.

Sure, let's see how it goes.

> > Maybe we are wasting time at discussing minor details, but I
> > consider this part important in order to give way to the major
> > refactoring that Wolfram started at the beginning.
> 
> The refactoring only affects "master/slave" not "adapter/client". We are
> 
> aligned here, aren't we?

Yes, of course. And I'm not really asking for the totality of the
"client"'s to be replaced, rather than, when replacing slave, to
choose "target" over "client" whenever possible(*).

Thanks, Wolfram,

Andi

(*) E.g. if in a file "client" is used a lot, doesn't make sense
    to go against the trend and use "target".

Re: [PATCH v3 5/6] docs: i2c: summary: document 'local' and 'remote' targets

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 555 bytes --]


> > The refactoring only affects "master/slave" not "adapter/client". We are
> > 
> > aligned here, aren't we?
> 
> Yes, of course. And I'm not really asking for the totality of the
> "client"'s to be replaced, rather than, when replacing slave, to
> choose "target" over "client" whenever possible(*).

Okay, phew, seems we got it now :) I'll send out v4 today and probably
send it to Linus this week. I want this base work to be upstream ASAP,
so we can base further work on it.

Thanks for your input and cooperation, Easwar and Andi!


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v3 6/6] docs: i2c: summary: be clearer with 'controller/target' and 'adapter/client' pairs

[Wolfram Sang]

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>
---
 Documentation/i2c/summary.rst | 33 ++++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
index ff8bda32b9c3..90f46f1504fe 100644
--- a/Documentation/i2c/summary.rst
+++ b/Documentation/i2c/summary.rst
@@ -31,9 +31,7 @@ implement all the common SMBus protocol semantics or messages.
 Terminology
 ===========
 
-The I2C bus connects one or more *controller* chips and one or more *target*
-chips.
-
+The I2C bus connects one or more controller chips and one or more target chips.
 
 .. kernel-figure::  i2c_bus.svg
    :alt:    Simple I2C bus with one controller and 3 targets
@@ -41,16 +39,16 @@ chips.
    Simple I2C bus
 
 A **controller** chip is a node that starts communications with targets. In the
-Linux kernel implementation it is called an **adapter** or bus. Adapter
-drivers are in the ``drivers/i2c/busses/`` subdirectory.
+Linux kernel implementation it is called an "adapter" or "bus". Controller
+drivers are usually in the ``drivers/i2c/busses/`` subdirectory.
 
-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.
+An **algorithm** contains general code that can be used to implement a whole
+class of I2C controllers. Each specific controller driver either depends on an
+algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes its
+own implementation.
 
 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 called a "client". While
 targets are usually separate external chips, Linux can also act as a target
 (needs hardware support) and respond to another controller on the bus. This is
 then called a **local target**. In contrast, an external chip is called a
@@ -60,9 +58,18 @@ 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
 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).
+For the example configuration in the figure above, you will need one driver for
+the I2C controller, and drivers for your I2C targets. Usually one driver for
+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, to discuss implementation details, it
+might be easier to use these terms. If speaking about I2C in general, the
+official terminology is preferred.
 
 Outdated terminology
 --------------------
-- 
2.43.0