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.

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
+KernelVersion:  6.16
+Contact:        linux-iio@vger.kernel.org
+Description:
+		Hardware applied calbiration delay (assumed to fix errors that are
+		introduced from external circuitry).
+		For the ad7606 ADC series, this value is intended as a time delay,
+		as an integer plus nanoseconds.
+
+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

-- 
2.49.0

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
>

On 5/4/25 10:16 AM, Jonathan Cameron wrote:
> 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!)
> 
I'm totally on board with making this more general than just calibration, but
having worked on a couple of multiplexed simultaneous sampling ADCs like this,
I'm scratching my head a bit trying to figure out how we would be able to know
what the delay was between the conversions, at least in cases where we don't
have a hardware conversion trigger based on a clock/pwm. Generally, it is as
fast as the SPI bus can bang it out, but that isn't a fixed or predictable
amount of time.

On Sun, 4 May 2025 14:48:32 -0500
David Lechner <dlechner@baylibre.com> wrote:

> On 5/4/25 10:16 AM, Jonathan Cameron wrote:
> > 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!)
> >   
> I'm totally on board with making this more general than just calibration, but
> having worked on a couple of multiplexed simultaneous sampling ADCs like this,
> I'm scratching my head a bit trying to figure out how we would be able to know
> what the delay was between the conversions, at least in cases where we don't
> have a hardware conversion trigger based on a clock/pwm. Generally, it is as
> fast as the SPI bus can bang it out, but that isn't a fixed or predictable
> amount of time.

Yeah, this only applies to self clocking devices with a FIFO (possibly a very
short one with 1 register per channel in a scan).
The SPI hammering cases don't work for exactly the reason you mention.

For those we might be able to come up with a multi-baseline solution to
indicate that inputs 0 + 1 are together and 2 + 3 also together but it would
be fiddly.  So lets wait until we know we need that :)

Jonathan