diff mbox series

[v2,1/5] Documentation: ABI: add oversampling frequency in sysfs-bus-iio

Message ID 20250422-iio-driver-ad4052-v2-1-638af47e9eb3@analog.com
State Handled Elsewhere
Headers show
Series Add support for AD4052 device family | expand

Commit Message

Jorge Marques April 22, 2025, 11:34 a.m. UTC
Some devices have an internal clock used to space out the conversion
trigger for the oversampling filter,
Consider an ADC with conversion and data ready pins topology:

  Sampling trigger |       |       |       |       |
  ADC conversion   ++++    ++++    ++++    ++++    ++++
  ADC data ready      *       *       *       *       *

With the oversampling frequency, conversions are spaced:

  Sampling trigger |       |       |       |       |
  ADC conversion   + + + + + + + + + + + + + + + + + + + +
  ADC data ready         *       *       *       *       *

In some devices and ranges, this internal clock can be used to evenly
space the conversions between the sampling edge.
In other devices the oversampling frequency is fixed or is computed
based on the sampling frequency parameter, and the parameter is
read only.

Devices with this feature are max1363, ad7606, ad799x, and ad4052.
The max1363 driver included the events/sampling_frequency in
commit 168c9d95a940 ("iio:adc:max1363 move from staging.")
and ad799x in
commit ba1d79613df3 ("staging:iio:ad799x: Use event spec for threshold
hysteresis")
but went undocumented so far.

Signed-off-by: Jorge Marques <jorge.marques@analog.com>
---
 Documentation/ABI/testing/sysfs-bus-iio | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Comments

Andy Shevchenko April 22, 2025, 3:50 p.m. UTC | #1
On Tue, Apr 22, 2025 at 01:34:46PM +0200, Jorge Marques wrote:
> Some devices have an internal clock used to space out the conversion
> trigger for the oversampling filter,
> Consider an ADC with conversion and data ready pins topology:
> 
>   Sampling trigger |       |       |       |       |
>   ADC conversion   ++++    ++++    ++++    ++++    ++++
>   ADC data ready      *       *       *       *       *
> 
> With the oversampling frequency, conversions are spaced:
> 
>   Sampling trigger |       |       |       |       |
>   ADC conversion   + + + + + + + + + + + + + + + + + + + +
>   ADC data ready         *       *       *       *       *
> 
> In some devices and ranges, this internal clock can be used to evenly
> space the conversions between the sampling edge.
> In other devices the oversampling frequency is fixed or is computed
> based on the sampling frequency parameter, and the parameter is
> read only.
> 
> Devices with this feature are max1363, ad7606, ad799x, and ad4052.
> The max1363 driver included the events/sampling_frequency in
> commit 168c9d95a940 ("iio:adc:max1363 move from staging.")
> and ad799x in
> commit ba1d79613df3 ("staging:iio:ad799x: Use event spec for threshold
> hysteresis")
> but went undocumented so far.

So, it was no documentation for the nodes this change describes, right?

...

> +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency
> +KernelVersion:	6.15

Then why don't you put the real version of the first release that has it?

> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Some devices have internal clocks for oversampling.
> +		Sets the resulting frequency in Hz to trigger a conversion used by
> +		the oversampling filter.
> +		If the device has a fixed internal clock or is computed based on
> +		the sampling frequency parameter, the parameter is read only.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency_available
> +KernelVersion:	6.15

Ditto.

> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Hardware dependent values supported by the oversampling
> +		frequency.
David Lechner April 25, 2025, 9:16 p.m. UTC | #2
On 4/22/25 6:34 AM, Jorge Marques wrote:

...

> Devices with this feature are max1363, ad7606, ad799x, and ad4052.
> The max1363 driver included the events/sampling_frequency in
> commit 168c9d95a940 ("iio:adc:max1363 move from staging.")
> and ad799x in
> commit ba1d79613df3 ("staging:iio:ad799x: Use event spec for threshold
> hysteresis")
> but went undocumented so far.

It looks like this part was copied from a different commit and isn't related
to this one.

> 
> Signed-off-by: Jorge Marques <jorge.marques@analog.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-iio | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index 33c09c4ac60a4feec82308461643134f5ba84b66..129061befb21b82a51142a01a94d96fcf1b60072 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -139,6 +139,23 @@ Contact:	linux-iio@vger.kernel.org
>  Description:
>  		Hardware dependent values supported by the oversampling filter.
>  
> +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency
> +KernelVersion:	6.15
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Some devices have internal clocks for oversampling.
> +		Sets the resulting frequency in Hz to trigger a conversion used by
> +		the oversampling filter.
> +		If the device has a fixed internal clock or is computed based on
> +		the sampling frequency parameter, the parameter is read only.

Don't need a newline after every period.

> +
> +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency_available
> +KernelVersion:	6.15
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Hardware dependent values supported by the oversampling
> +		frequency.

		oversampling_frequency attribute.

> +
>  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_raw
>  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_raw
>  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_i_raw
>
Jorge Marques April 29, 2025, 1:47 p.m. UTC | #3
Hi Andy,

I agree with your suggestion, and in this case the appropriate kernel
version is 3.10.

On Tue, Apr 22, 2025 at 06:50:19PM +0300, Andy Shevchenko wrote:
> On Tue, Apr 22, 2025 at 01:34:46PM +0200, Jorge Marques wrote:
> > Some devices have an internal clock used to space out the conversion
> > trigger for the oversampling filter,
> > Consider an ADC with conversion and data ready pins topology:
> > 
> >   Sampling trigger |       |       |       |       |
> >   ADC conversion   ++++    ++++    ++++    ++++    ++++
> >   ADC data ready      *       *       *       *       *
> > 
> > With the oversampling frequency, conversions are spaced:
> > 
> >   Sampling trigger |       |       |       |       |
> >   ADC conversion   + + + + + + + + + + + + + + + + + + + +
> >   ADC data ready         *       *       *       *       *
> > 
> > In some devices and ranges, this internal clock can be used to evenly
> > space the conversions between the sampling edge.
> > In other devices the oversampling frequency is fixed or is computed
> > based on the sampling frequency parameter, and the parameter is
> > read only.
> > 
> > Devices with this feature are max1363, ad7606, ad799x, and ad4052.
> > The max1363 driver included the events/sampling_frequency in
> > commit 168c9d95a940 ("iio:adc:max1363 move from staging.")
> > and ad799x in
> > commit ba1d79613df3 ("staging:iio:ad799x: Use event spec for threshold
> > hysteresis")
> > but went undocumented so far.
> 
> So, it was no documentation for the nodes this change describes, right?
> 
> ...
> 
> > +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency
> > +KernelVersion:	6.15
> 
> Then why don't you put the real version of the first release that has it?
> 
> > +Contact:	linux-iio@vger.kernel.org
> > +Description:
> > +		Some devices have internal clocks for oversampling.
> > +		Sets the resulting frequency in Hz to trigger a conversion used by
> > +		the oversampling filter.
> > +		If the device has a fixed internal clock or is computed based on
> > +		the sampling frequency parameter, the parameter is read only.
> > +
> > +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency_available
> > +KernelVersion:	6.15
> 
> Ditto.
> 
> > +Contact:	linux-iio@vger.kernel.org
> > +Description:
> > +		Hardware dependent values supported by the oversampling
> > +		frequency.
> 
> -- 
> With Best Regards,
> Andy Shevchenko
> 

Best regards,
Jorge
Jorge Marques April 29, 2025, 1:47 p.m. UTC | #4
Hi David,

On Fri, Apr 25, 2025 at 04:16:20PM -0500, David Lechner wrote:
> On 4/22/25 6:34 AM, Jorge Marques wrote:
> 
> ...
> 
> > Devices with this feature are max1363, ad7606, ad799x, and ad4052.
> > The max1363 driver included the events/sampling_frequency in
> > commit 168c9d95a940 ("iio:adc:max1363 move from staging.")
> > and ad799x in
> > commit ba1d79613df3 ("staging:iio:ad799x: Use event spec for threshold
> > hysteresis")
> > but went undocumented so far.
> 
> It looks like this part was copied from a different commit and isn't related
> to this one.
> 

You are right, this is from the other already applied patch, I will remove.

> > 
> > Signed-off-by: Jorge Marques <jorge.marques@analog.com>
> > ---
> >  Documentation/ABI/testing/sysfs-bus-iio | 17 +++++++++++++++++
> >  1 file changed, 17 insertions(+)
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > index 33c09c4ac60a4feec82308461643134f5ba84b66..129061befb21b82a51142a01a94d96fcf1b60072 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -139,6 +139,23 @@ Contact:	linux-iio@vger.kernel.org
> >  Description:
> >  		Hardware dependent values supported by the oversampling filter.
> >  
> > +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency
> > +KernelVersion:	6.15
> > +Contact:	linux-iio@vger.kernel.org
> > +Description:
> > +		Some devices have internal clocks for oversampling.
> > +		Sets the resulting frequency in Hz to trigger a conversion used by
> > +		the oversampling filter.
> > +		If the device has a fixed internal clock or is computed based on
> > +		the sampling frequency parameter, the parameter is read only.
> 
> Don't need a newline after every period.

Ack.

> 
> > +
> > +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency_available
> > +KernelVersion:	6.15
> > +Contact:	linux-iio@vger.kernel.org
> > +Description:
> > +		Hardware dependent values supported by the oversampling
> > +		frequency.
> 
> 		oversampling_frequency attribute.
> 

Ack.

> > +
> >  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_raw
> >  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_raw
> >  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_i_raw
> > 
> 

Regards,
Jorge
David Lechner April 29, 2025, 3:40 p.m. UTC | #5
On 4/29/25 8:47 AM, Jorge Marques wrote:
> 
> Hi Andy,
> 
> I agree with your suggestion, and in this case the appropriate kernel
> version is 3.10.
> 
>>
>>> +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency
>>> +KernelVersion:	6.15
>>
>> Then why don't you put the real version of the first release that has it?
>>
>>> +Contact:	linux-iio@vger.kernel.org
>>> +Description:
>>> +		Some devices have internal clocks for oversampling.
>>> +		Sets the resulting frequency in Hz to trigger a conversion used by
>>> +		the oversampling filter.
>>> +		If the device has a fixed internal clock or is computed based on
>>> +		the sampling frequency parameter, the parameter is read only.
>>> +
>>> +What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency_available
>>> +KernelVersion:	6.15
>>
>> Ditto.
>>
>>> +Contact:	linux-iio@vger.kernel.org
>>> +Description:
>>> +		Hardware dependent values supported by the oversampling
>>> +		frequency.


I don't see oversampling_frequency used in any existing driver, so how could
it be introduced in kernel 3.10? I think you confuse it with
events/sampling_frequency.

oversampling_frequency is new and so 6.16 should be correct if Jonathan picks
this up in the next few weeks, otherwise it will be 6.17.
Andy Shevchenko April 29, 2025, 10:03 p.m. UTC | #6
On Tue, Apr 29, 2025 at 6:40 PM David Lechner <dlechner@baylibre.com> wrote:
>
> On 4/29/25 8:47 AM, Jorge Marques wrote:
> >
> > Hi Andy,
> >
> > I agree with your suggestion, and in this case the appropriate kernel
> > version is 3.10.
> >
> >>
> >>> +What:              /sys/bus/iio/devices/iio:deviceX/oversampling_frequency
> >>> +KernelVersion:     6.15
> >>
> >> Then why don't you put the real version of the first release that has it?
> >>
> >>> +Contact:   linux-iio@vger.kernel.org
> >>> +Description:
> >>> +           Some devices have internal clocks for oversampling.
> >>> +           Sets the resulting frequency in Hz to trigger a conversion used by
> >>> +           the oversampling filter.
> >>> +           If the device has a fixed internal clock or is computed based on
> >>> +           the sampling frequency parameter, the parameter is read only.
> >>> +
> >>> +What:              /sys/bus/iio/devices/iio:deviceX/oversampling_frequency_available
> >>> +KernelVersion:     6.15
> >>
> >> Ditto.
> >>
> >>> +Contact:   linux-iio@vger.kernel.org
> >>> +Description:
> >>> +           Hardware dependent values supported by the oversampling
> >>> +           frequency.
>
>
> I don't see oversampling_frequency used in any existing driver, so how could
> it be introduced in kernel 3.10? I think you confuse it with
> events/sampling_frequency.
>
> oversampling_frequency is new and so 6.16 should be correct if Jonathan picks
> this up in the next few weeks, otherwise it will be 6.17.

If this is the case, the whole commit message should be revisited.
Jonathan Cameron May 5, 2025, 12:39 p.m. UTC | #7
On Wed, 30 Apr 2025 01:03:07 +0300
Andy Shevchenko <andy.shevchenko@gmail.com> wrote:

> On Tue, Apr 29, 2025 at 6:40 PM David Lechner <dlechner@baylibre.com> wrote:
> >
> > On 4/29/25 8:47 AM, Jorge Marques wrote:  
> > >
> > > Hi Andy,
> > >
> > > I agree with your suggestion, and in this case the appropriate kernel
> > > version is 3.10.
> > >  
> > >>  
> > >>> +What:              /sys/bus/iio/devices/iio:deviceX/oversampling_frequency
> > >>> +KernelVersion:     6.15  
> > >>
> > >> Then why don't you put the real version of the first release that has it?
> > >>  
> > >>> +Contact:   linux-iio@vger.kernel.org
> > >>> +Description:
> > >>> +           Some devices have internal clocks for oversampling.
> > >>> +           Sets the resulting frequency in Hz to trigger a conversion used by
> > >>> +           the oversampling filter.
> > >>> +           If the device has a fixed internal clock or is computed based on
> > >>> +           the sampling frequency parameter, the parameter is read only.
> > >>> +
> > >>> +What:              /sys/bus/iio/devices/iio:deviceX/oversampling_frequency_available
> > >>> +KernelVersion:     6.15  
> > >>
> > >> Ditto.
> > >>  
> > >>> +Contact:   linux-iio@vger.kernel.org
> > >>> +Description:
> > >>> +           Hardware dependent values supported by the oversampling
> > >>> +           frequency.  
> >
> >
> > I don't see oversampling_frequency used in any existing driver, so how could
> > it be introduced in kernel 3.10? I think you confuse it with
> > events/sampling_frequency.
> >
> > oversampling_frequency is new and so 6.16 should be correct if Jonathan picks
> > this up in the next few weeks, otherwise it will be 6.17.  
> 
> If this is the case, the whole commit message should be revisited.
> 
Yeah. That last bit about the existing drivers is talking about unrelated
ABI.

Jonathan
diff mbox series

Patch

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 33c09c4ac60a4feec82308461643134f5ba84b66..129061befb21b82a51142a01a94d96fcf1b60072 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -139,6 +139,23 @@  Contact:	linux-iio@vger.kernel.org
 Description:
 		Hardware dependent values supported by the oversampling filter.
 
+What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency
+KernelVersion:	6.15
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Some devices have internal clocks for oversampling.
+		Sets the resulting frequency in Hz to trigger a conversion used by
+		the oversampling filter.
+		If the device has a fixed internal clock or is computed based on
+		the sampling frequency parameter, the parameter is read only.
+
+What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency_available
+KernelVersion:	6.15
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Hardware dependent values supported by the oversampling
+		frequency.
+
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_raw
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_raw
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_i_raw