Re: [PATCH v7 3/3] Documentation: ABI: testing: rtq6056: Update ABI docs

[ChiYuan Huang]

Jonathan Cameron <jic23@xxxxxxxxxx> 於 2022年7月19日 週二 凌晨12:54寫道：
>
> On Mon, 18 Jul 2022 13:46:03 +0800
> cy_huang <u0084500@xxxxxxxxx> wrote:
>
> > From: ChiYuan Huang <cy_huang@xxxxxxxxxxx>
> >
> > Add documentation for the usage of voltage channel integration time.
> >
> > Signed-off-by: ChiYuan Huang <cy_huang@xxxxxxxxxxx>
> > ---
> >  Documentation/ABI/testing/sysfs-bus-iio | 10 ++++++++++
> >  1 file changed, 10 insertions(+)
> >
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > index d4ccc68..1f7d327 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -2030,3 +2030,13 @@ Description:
> >               Available range for the forced calibration value, expressed as:
> >
> >               - a range specified as "[min step max]"
> > +
> > +What:                /sys/bus/iio/devices/iio:deviceX/in_voltageY_integration_time
> > +KernelVersion:       5.20
> > +Contact:     linux-iio@xxxxxxxxxxxxxxx
> > +Description:
> > +             For voltage sensing hardware, there may be different time between
> > +             channel conversion and sample update. 'Integration time' is used to
> > +             specify the channel internal conversion time. And sample update
> > +             interval is equal to average sample count multiple integration time.
> > +             Unit as microsecond.
>
> Whilst I did suggest moving this to this file, I also suggested that it was the
> wrong interface to use.  For similar cases we've used in_voltageY_sampling_frequency
> in the past because this isn't really an integration time, but rather a reflection of
> a bunch of other stuff that makes up the conversion time.  In IIO we chose a long
> time ago to use 1/conversion_time as the exposed interface == sampling_frequency
>
> So, unless there is a strong reason to do otherwise, drop the overall sampling_frequency
> attribute and use per channel ones instead.  Then update the main documentation
> to make this usecase clear. Something in the block
> https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/testing/sysfs-bus-iio#L89
> like adding the in_voltageY_sampling_frequency entry to the What: list and a
> sentence at the end that says something like:
>
> "Some devices have separate controls of sampling frequency for individual channels.
> If multiple channels are enabled in a scan, then the sampling_frequency of the the
> scan may be computed from the per channel sampling_frequencies."
>
>From my case, I need to specify
in_voltageX_sampling_frequency/in_powerY_sampling_frequency/
in_currentZ_sampling_frequency.

And describe all in the same sentence.
Can I directly copy the sentence that you described above?
I read the comment. The sentence that you wrote seems more generic.

If any misunderstanding, please correct me.
> Not something to put in the documentation, but for devices which do simultaneous sampling
> it is very unlikely we'll have per channel sampling frequencies so there isn't an
> ambiguity. The alternative we 'could' consider is to allow both overall sampling_frequency
> and per channel in_voltageY_sampling_frequency but that is a bad idea because the
> ABI (and most userspace software) assumes that more specific attributes override the
> values of more generic ones (rather than them having different meanings as would be
> the case here).
>
> Jonathan