Received-SPF: pass (google.com: domain of linux-kernel+bounces-208646-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1;
Message-ID: <8e051ecf-a355-4aef-bc40-007f9b709ba6@linux.microsoft.com>
Date: Mon, 10 Jun 2024 10:25:20 -0700
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Cc: eahariha@linux.microsoft.com, Andi Shyti <andi.shyti@kernel.org>,
 linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 4/6] docs: i2c: summary: document use of inclusive
 language
To: Wolfram Sang <wsa+renesas@sang-engineering.com>, linux-i2c@vger.kernel.org
References: <20240610081023.8118-1-wsa+renesas@sang-engineering.com>
 <20240610081023.8118-5-wsa+renesas@sang-engineering.com>
Content-Language: en-US
From: Easwar Hariharan <eahariha@linux.microsoft.com>
In-Reply-To: <20240610081023.8118-5-wsa+renesas@sang-engineering.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

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