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@SoMainline.org/
Suggested-by: Jonathan Cameron <jic23@kernel.org>
Signed-off-by: Marijn Suijten <marijn.suijten@somainline.org>
---
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.
* @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
--
2.39.0On Mon, 16 Jan 2023 23:09:05 +0100
Marijn Suijten <marijn.suijten@somainline.org> 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@SoMainline.org/
>
> Suggested-by: Jonathan Cameron <jic23@kernel.org>
> Signed-off-by: Marijn Suijten <marijn.suijten@somainline.org>
> ---
> 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.
?
> * @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
On 2023-01-18 16:19:20, Jonathan Cameron wrote:
> On Mon, 16 Jan 2023 23:09:05 +0100
> Marijn Suijten <marijn.suijten@somainline.org> 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@SoMainline.org/
> >
> > Suggested-by: Jonathan Cameron <jic23@kernel.org>
> > Signed-off-by: Marijn Suijten <marijn.suijten@somainline.org>
> > ---
> > 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
>
On Wed, 18 Jan 2023 17:35:25 +0100
Marijn Suijten <marijn.suijten@somainline.org> wrote:
> On 2023-01-18 16:19:20, Jonathan Cameron wrote:
> > On Mon, 16 Jan 2023 23:09:05 +0100
> > Marijn Suijten <marijn.suijten@somainline.org> 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@SoMainline.org/
> > >
> > > Suggested-by: Jonathan Cameron <jic23@kernel.org>
> > > Signed-off-by: Marijn Suijten <marijn.suijten@somainline.org>
> > > ---
> > > 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.
Sure that works.
>
> 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).
I haven't looked closely enough at the rest, but if this is all that
needs updating I'll change it whilst applying.
>
> 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
> >
>
On 2023-01-18 17:35:27, Marijn Suijten wrote:
> On 2023-01-18 16:19:20, Jonathan Cameron wrote:
> > On Mon, 16 Jan 2023 23:09:05 +0100
> > Marijn Suijten <marijn.suijten@somainline.org> 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@SoMainline.org/
> > >
> > > Suggested-by: Jonathan Cameron <jic23@kernel.org>
> > > Signed-off-by: Marijn Suijten <marijn.suijten@somainline.org>
> > > ---
> > > 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
Yes, if read_label is a function that exists (but it's a member)... and
@extend_name will indeed reference the member anywhere.
> 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 :)
Looks like that would be &iio_info->read_label() (not sure about the
trailing () though):
https://docs.kernel.org/doc-guide/kernel-doc.html#highlights-and-cross-references
- Marijn
© 2016 - 2026 Red Hat, Inc.