Re: [PATCH v2 1/5] Documentation: ABI: IIO: add calibconv_delay documentation

[Jonathan Cameron <jic23@kernel.org>]

On Fri, 02 May 2025 15:26:58 +0200
Angelo Dureghello <adureghello@baylibre.com> wrote:

> From: Angelo Dureghello <adureghello@baylibre.com>
> 
> Add new IIO calibconv_delay documentation.
> 
> The ad7606 implements a phase calibation feature, in nanoseconds.
> Being this a time delay, using the conv_delay suffix.
I made a late reply to v1...

Key point being that, in the general sense this is only a calibration
thing if it is both writeable and we are using it for filter phase correction.
In more general terms it's just a conversion sampling time offset (and as you have
it here in seconds).  I'm keen we define this to incorporate more general
cases including extra read only info on sequencer timing - that can be useful
if we have something like 
                 _____________
Input 0 --------|             |
Input 1 --------| 4 in, 2 out |-----  ADC0
Input 2 --------|  MUX        |
Input 3 --------|_____________|-----  ADC1

That is the ability to schedule more channels across a small number of
simultaneous sampling ADCs.  In these cases we've never had a way to
express what was done together.  Mostly there have been obvious
combinations (i.e. voltage and current at same time on a given wire for
power measurement), but it would still be nice to use your new interface
to allow us to describe what is running here (though probably not control
it as that would be hard to do!)

> 
> Signed-off-by: Angelo Dureghello <adureghello@baylibre.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-iio | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index 33c09c4ac60a4feec82308461643134f5ba84b66..56eb42f88999660b5f93f2311b7d57e0303b0647 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -559,6 +559,26 @@ Description:
>  		- a small discrete set of values like "0 2 4 6 8"
>  		- a range specified as "[min step max]"
>  
> +What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibconv_delay

I wonder if simply in_voltageY_delay is enough?  I don't mind
in_voltageY_convdelay  but don't like the calib bit.

I have had requests to stop using underscores in middle of modifiers as they are a pain
to parse - hence convdelay rather than conv_delay

> +KernelVersion:  6.16
> +Contact:        linux-iio@vger.kernel.org
> +Description:
> +		Hardware applied calbiration delay (assumed to fix errors that are
> +		introduced from external circuitry).

Use this a an example of why this might be controllable.  It might be read only
if all it is doing is giving us a richer description of a sequencer.
Something like

		Delay of start of conversion in seconds from common reference point
		shared by all channels.  When used to compensate for delay variation
		in external filters feeding a simultaneous sampling ADC this may
		be referred to as a ...

> +		For the ad7606 ADC series, this value is intended as a time delay,
> +		as an integer plus nanoseconds.
Just call it seconds. Once it reaches userspace it might have different scaling but we 
fix that up with the right number of zeros.
No part specific units...  They all need to be seconds.

> +
> +What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibconv_delay_available
> +KernelVersion:	6.16
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Available values of calibconv_delay. Maybe expressed as:
> +
> +		- a range specified as "[min step max]"
> +
> +		If shared across all channels, <type>_calibconv_delay_available
> +		is used.
> +
>  What:		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibscale
>  What:		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibscale
>  What:		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale
>