1. Patchew
  2. linux
  3. View series

[PATCH v2] Documentation: ABI: add oversampling frequency in sysfs-bus-iio

Jorge Marques posted 1 patch 1 month ago 
Documentation/ABI/testing/sysfs-bus-iio | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
[PATCH v2] Documentation: ABI: add oversampling frequency in sysfs-bus-iio
Posted by Jorge Marques 1 month ago 
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.

Signed-off-by: Jorge Marques <jorge.marques@analog.com>
---
Some device families such as Analog Device's max1363, ad7606, ad799x, and
ad4052 contain internal clocks used by monitor modes and oversampling.
Devices' monitor modes are exposed as IIO events.
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.

The oversampling sampling frequency is a planned feature to be patched
onto the ad7606 driver.
In this particular device, it is called oversampling padding.
The upcoming ad4052 linux driver will utilize both entries,
it is worth noting, however, there is a single register for both
options. Since the device is never concurrently in both modes, the
values will be safely cached on the device state.
---
Changes in v2:
- Updated oversampling frequency description according to discussion 
- Don't include already applied
  commit 3a8fee68faf2 ("Documentation: ABI: add events sampling frequency in sysfs-bus-iio")
- Link to v1: https://lore.kernel.org/r/20250321-abi-oversampling-events-frequency-v1-0-794c1ab2f079@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 722aa989baac43f694076074b307d134867b4533..6f5c4060704742ae5f5672a861271b88084ac8f8 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -138,6 +138,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

---
base-commit: 9f36acefb2621d980734a5bb7d74e0e24e0af166
change-id: 20250321-abi-oversampling-events-frequency-436c64fcece0

Best regards,
-- 
Jorge Marques <jorge.marques@analog.com>
Re: [PATCH v2] Documentation: ABI: add oversampling frequency in sysfs-bus-iio
Posted by Jorge Marques 2 weeks, 2 days ago 
Hi Jonathan, David

Should this patch be submitted differently, such as under the AD4052 V2
series? Or are further modifications needed?

Regards,
Jorge

On Tue, Apr 08, 2025 at 10:20:29AM +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.
> 
> Signed-off-by: Jorge Marques <jorge.marques@analog.com>
> ---
> Some device families such as Analog Device's max1363, ad7606, ad799x, and
> ad4052 contain internal clocks used by monitor modes and oversampling.
> Devices' monitor modes are exposed as IIO events.
> 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.
> 
> The oversampling sampling frequency is a planned feature to be patched
> onto the ad7606 driver.
> In this particular device, it is called oversampling padding.
> The upcoming ad4052 linux driver will utilize both entries,
> it is worth noting, however, there is a single register for both
> options. Since the device is never concurrently in both modes, the
> values will be safely cached on the device state.
> ---
> Changes in v2:
> - Updated oversampling frequency description according to discussion 
> - Don't include already applied
>   commit 3a8fee68faf2 ("Documentation: ABI: add events sampling frequency in sysfs-bus-iio")
> - Link to v1: https://lore.kernel.org/r/20250321-abi-oversampling-events-frequency-v1-0-794c1ab2f079@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 722aa989baac43f694076074b307d134867b4533..6f5c4060704742ae5f5672a861271b88084ac8f8 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -138,6 +138,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
> 
> ---
> base-commit: 9f36acefb2621d980734a5bb7d74e0e24e0af166
> change-id: 20250321-abi-oversampling-events-frequency-436c64fcece0
> 
> Best regards,
> -- 
> Jorge Marques <jorge.marques@analog.com>
>
Re: [PATCH v2] Documentation: ABI: add oversampling frequency in sysfs-bus-iio
Posted by David Lechner 2 weeks, 1 day ago 
On 4/22/25 2:30 AM, Jorge Marques wrote:
> Hi Jonathan, David
> 
> Should this patch be submitted differently, such as under the AD4052 V2
> series? Or are further modifications needed?
> 
Jonathan already replied that this should be included in the series with the
first user, whatever that happens to be.

https://lore.kernel.org/linux-iio/20250413103110.572de81e@jic23-huawei/
Re: [PATCH v2] Documentation: ABI: add oversampling frequency in sysfs-bus-iio
Posted by Jonathan Cameron 3 weeks, 4 days ago 
On Tue, 8 Apr 2025 10:20:29 +0200
Jorge Marques <jorge.marques@analog.com> 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.
> 
> Signed-off-by: Jorge Marques <jorge.marques@analog.com>
> ---
> Some device families such as Analog Device's max1363, ad7606, ad799x, and
> ad4052 contain internal clocks used by monitor modes and oversampling.
> Devices' monitor modes are exposed as IIO events.
> 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.
> 
> The oversampling sampling frequency is a planned feature to be patched
> onto the ad7606 driver.
> In this particular device, it is called oversampling padding.
> The upcoming ad4052 linux driver will utilize both entries,
> it is worth noting, however, there is a single register for both
> options. Since the device is never concurrently in both modes, the
> values will be safely cached on the device state.

This patch looks fine but we will only merge it with first user so
please add it to that series.

Jonathan

> ---
> Changes in v2:
> - Updated oversampling frequency description according to discussion 
> - Don't include already applied
>   commit 3a8fee68faf2 ("Documentation: ABI: add events sampling frequency in sysfs-bus-iio")
> - Link to v1: https://lore.kernel.org/r/20250321-abi-oversampling-events-frequency-v1-0-794c1ab2f079@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 722aa989baac43f694076074b307d134867b4533..6f5c4060704742ae5f5672a861271b88084ac8f8 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -138,6 +138,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
> 
> ---
> base-commit: 9f36acefb2621d980734a5bb7d74e0e24e0af166
> change-id: 20250321-abi-oversampling-events-frequency-436c64fcece0
> 
> Best regards,

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.