diff mbox series

[4/5] docs: i2c: summary: document use of inclusive language

Message ID 20240607111726.12678-5-wsa+renesas@sang-engineering.com
State New
Headers show
Series docs: i2c: summary: update and use inclusive wording | expand

Commit Message

Wolfram Sang June 7, 2024, 11:17 a.m. UTC 
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(-)

Comments

Easwar Hariharan June 7, 2024, 6:13 p.m. UTC | #1 
On 6/7/2024 4:17 AM, 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>
> ---
>  Documentation/i2c/i2c_bus.svg | 15 ++++++++-------
>  Documentation/i2c/summary.rst | 23 +++++++++++++++++------
>  2 files changed, 25 insertions(+), 13 deletions(-)
> 

<snip>

> diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst
> index a1e5c0715f8b..b10b6aaafcec 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

Are we continuing to use client instead of local target and remote target?

Thanks,
Easwar
Wolfram Sang June 7, 2024, 9:20 p.m. UTC | #2 
> > +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
> 
> Are we continuing to use client instead of local target and remote target?

Nope, "client" is just the Linux word for "target". Like "adapter" for
"controller". Historic legacy. So, in a way "local client" and "remote
client" would also work to emphasize the distinction.

This document so far only talks about "remote targets". I noticed this a
few hours ago and concluded that another paragraph needs to be added
explaining that Linux can be a target as well. And that this is called a
"local target" while the other ones are "remote targets".

Makes sense?
diff mbox series

Patch

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..b10b6aaafcec 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
+--------------------
+
+Historically, controller was named "master" and client 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 switch
+over the Linux Kernel is on-going.