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

[Jonathan Cameron <jic23@kernel.org>]

On Mon, 18 Jul 2022 13:46:03 +0800
cy_huang <u0084500@gmail.com> wrote:

> From: ChiYuan Huang <cy_huang@richtek.com>
> 
> Add documentation for the usage of voltage channel integration time.
> 
> Signed-off-by: ChiYuan Huang <cy_huang@richtek.com>
> ---
>  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@vger.kernel.org
> +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."

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