| Message ID | 20240614081239.7128-13-wsa+renesas@sang-engineering.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v3,1/6] docs: i2c: summary: start sentences consistently. | expand |
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 >
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
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
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 >
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
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
> > 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!
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
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(-)