| Message ID | 20240610081023.8118-5-wsa+renesas@sang-engineering.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs: i2c: summary: update and use inclusive wording | expand |
On 6/10/2024 1:10 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 <snip> > + > +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. 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? Confused, Easwar
On 6/10/2024 1:29 PM, Wolfram Sang wrote: > Hi Easwar, > >> 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? > > I am not sure I understand the question properly? > > "controller/target" as in the specs, and "adapter/client" when it comes > to the Linux implementation (which has been like this forever). I'd > think it is too much churn to change this as well. > >> Confused, > > Heh, me too now... > > All the best, > > Wolfram I am wondering what the impact of this doc update is on my series[1]. I am looking for a straightforward recommendation for what terminology I, and hopefully others, should adopt *outside the i2c subsystem*, where Linux (typically) has a driver for the controller and is communicating with an unknown OS/firmware on the target. a) Spec-compliant "controller/target" b) Linux implementation/spec hybrid "controller/client", or c) Linux implementation "adapter/client" I prefer (a), FWIW, so do apparently reviewers on my series. Thanks, Easwar [1] https://lore.kernel.org/all/20240508234342.2927398-1-eahariha@linux.microsoft.com/
> I am wondering what the impact of this doc update is on my series[1]. I > am looking for a straightforward recommendation for what terminology I, > and hopefully others, should adopt *outside the i2c subsystem*, where > Linux (typically) has a driver for the controller and is communicating > with an unknown OS/firmware on the target. > > a) Spec-compliant "controller/target" > b) Linux implementation/spec hybrid "controller/client", or > c) Linux implementation "adapter/client" > > I prefer (a), FWIW, so do apparently reviewers on my series. I also prefer (a), but people should know what (c) means when they look around in the kernel source. I'll see how it goes with rewording this patch accordingly.
> > +Outdated terminology > > +-------------------- > > + > > +Historically, controller was named "master" and client was named "slave". These Ahhh, while reworking the series I finally saw that I wrote "client" in the line above. That was an oversight, it should have been "target", of course. Next time, please quote directly below the errornous line, that makes it easier for me to understand what we are talking about. Nonetheless, the rework is not in vain. I think the texts have gotten a tad better.
On 6/13/2024 12:52 PM, Wolfram Sang wrote: > >>> +Outdated terminology >>> +-------------------- >>> + >>> +Historically, controller was named "master" and client was named "slave". These > > Ahhh, while reworking the series I finally saw that I wrote "client" in > the line above. That was an oversight, it should have been "target", of > course. Next time, please quote directly below the errornous line, that > makes it easier for me to understand what we are talking about. > > Nonetheless, the rework is not in vain. I think the texts have gotten a > tad better. > Apologies, but that one word wasn't the cause of the confusion. It was: a) "In Linux it is called a **client**", combined with b) "The general attitude, however, is to use the inclusive terms: controller and target. Work to switch over the Linux Kernel is on-going." I'll try to quote better in the future. Hope that helps, Easwar
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.
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(-)