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

[Jorge Marques]

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@xxxxxxxxxx>
---
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@xxxxxxxxxx
---
 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@xxxxxxxxxxxxxxx
 Description:
 		Hardware dependent values supported by the oversampling filter.
 
+What:		/sys/bus/iio/devices/iio:deviceX/oversampling_frequency
+KernelVersion:	6.15
+Contact:	linux-iio@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxx>