| Message ID | 20230116220909.196926-2-marijn.suijten@somainline.org (mailing list archive) |
|---|---|
| State | Changes Requested |
| Headers | show |
| Series | iio: adc: qcom-spmi-vadc: Propagate fw node label to userspace | expand |
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. ? > * @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 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
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 > > >
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
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(+)