Re: [RFC PATCH v2 1/5] iio: core: Point users of extend_name field to read_label callback

[Marijn Suijten]

On 2023-01-18 16:19:20, Jonathan Cameron wrote:
> On Mon, 16 Jan 2023 23:09:05 +0100
> Marijn Suijten <marijn.suijten@xxxxxxxxxxxxxx> wrote:
> 
> > As mentioned and discussed in [1] extend_name should not be used for
> > full channel labels (and most drivers seem to only use it to express a
> > short type of a channel) as this affects sysfs filenames, while the
> > label name is supposed to be extracted from the *_label sysfs file
> > instead.  This appears to have been unclear to some drivers as
> > extend_name is also used when read_label is unset, achieving an initial
> > goal of providing sensible names in *_label sysfs files without noticing
> > that sysfs filenames are (negatively and likely unintentionally)
> > affected as well.
> > 
> > Point readers of iio_chan_spec::extend_name to iio_info::read_label by
> > mentioning deprecation and side-effects of this field.
> > 
> > [1]: https://lore.kernel.org/linux-arm-msm/20221221223432.si2aasbleiicayfl@xxxxxxxxxxxxxx/
> > 
> > Suggested-by: Jonathan Cameron <jic23@xxxxxxxxxx>
> > Signed-off-by: Marijn Suijten <marijn.suijten@xxxxxxxxxxxxxx>
> > ---
> >  include/linux/iio/iio.h | 3 +++
> >  1 file changed, 3 insertions(+)
> > 
> > diff --git a/include/linux/iio/iio.h b/include/linux/iio/iio.h
> > index 81413cd3a3e7..36c89f238fb9 100644
> > --- a/include/linux/iio/iio.h
> > +++ b/include/linux/iio/iio.h
> > @@ -221,6 +221,9 @@ struct iio_event_spec {
> >   * @extend_name:	Allows labeling of channel attributes with an
> >   *			informative name. Note this has no effect codes etc,
> >   *			unlike modifiers.
> > + *			This field is deprecated in favour of overriding read_label
> > + *			in iio_info, which unlike @extend_name does not affect sysfs
> > + *			filenames.
> Perhaps reword as
> 
> This field is deprecated in favour of overriding the default label
> by providing a read_label() callback in iio_info, which unlike
> @extend_name does not affect sysfs filenames.
> ?

Agreed, explicitly stating "the default label by" makes this much more
clear.  Though, maybe swap that around into "in favour of providing
read_label() in iio_info to override the label"?  Otherwise this could
be interpreted as "overriding the default label" is preferred to setting
extend_name... which one would do to override the default label.

I can queue this up for v3 unless you'll fix it up while applying,
presuming no other changes have to be made (aside from dropping patch
3/5).

Will read_label() turn into a link?  And is the @extend_name reference
proper?  Is there something to link to iio_info, perhaps a hashtag - or
maybe fully qualify `#iio_info::read_label()` for linking purposes?
/me jumps over to kerneldoc documentation :)

- Marijn

> >   * @datasheet_name:	A name used in in-kernel mapping of channels. It should
> >   *			correspond to the first name that the channel is referred
> >   *			to by in the datasheet (e.g. IND), or the nearest
>