diff mbox series

[v3,3/3] Documentation: ABI: IIO: Re-add sysfs-bus-iio-adc-ad4130

Message ID 0d73303f2bca3312ccf2abfeb2c654c228fa7f60.1738608986.git.marcelo.schmitt@analog.com (mailing list archive)
State New
Headers show
Series Re-add filter_type/filter_mode | expand

Commit Message

Marcelo Schmitt Feb. 3, 2025, 7:11 p.m. UTC 
The ad4130 driver exports in_voltageY-voltageZ_filter_mode and
in_voltage-voltage_filter_mode_available attributes to user space. A
previous patch merged the documentation for those attributes with the
documentation for filter_type/filter_type_available into sysfs-bus-iio.
Filter mode and filter type refer to the same feature which is the digital
filter applied over ADC samples. However, since datasheets use the term
`filter type` and ad4130 driver is the only one using filter_mode,
deprecate the filter_mode ABI in favor of filter_type and keep the docs
separate to avoid confusion and intricate attribute descriptions.

The digital filter helps shape the noise rejection bandwidth and is
supposed to be adjusted according to the signal of interest. Depending on
the particular ADC design, the digital filter configuration may have an
impact on the output data rate (ODR) (which is equivalent to the sampling
frequency for SAR ADCs - `sampling_frequency` ABI), 3dB cutoff frequency of
the filter (`_low_pass_3db_frequency` attributes), or settling time.

Digital filters are a common feature among sigma-delta ADCs and
IIO drivers set digital filters according to different attributes.
ad4130 and ad7779 filter options are supported through dedicated
filter_mode/filter_type attributes in sysfs.
ad7768-1 and ad7173 set the sinc filters according to the
sampling_frequency attribute. No filter_type attribute.
ad7124 sets the digital filter according to a filter_low_pass_3db_frequency
attribute so it doesn't export filter type attributes to user space.

Fixes: 01bb12922b60 ("Documentation: ABI: added filter mode doc in sysfs-bus-iio")
Signed-off-by: Marcelo Schmitt <marcelo.schmitt@analog.com>
---
 Documentation/ABI/testing/sysfs-bus-iio       |  1 -
 .../ABI/testing/sysfs-bus-iio-adc-ad4130      | 20 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 3 files changed, 21 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130

Comments

David Lechner Feb. 3, 2025, 7:41 p.m. UTC | #1 
On 2/3/25 1:11 PM, Marcelo Schmitt wrote:
> The ad4130 driver exports in_voltageY-voltageZ_filter_mode and
> in_voltage-voltage_filter_mode_available attributes to user space. A
> previous patch merged the documentation for those attributes with the
> documentation for filter_type/filter_type_available into sysfs-bus-iio.
> Filter mode and filter type refer to the same feature which is the digital
> filter applied over ADC samples. However, since datasheets use the term
> `filter type` and ad4130 driver is the only one using filter_mode,
> deprecate the filter_mode ABI in favor of filter_type and keep the docs
> separate to avoid confusion and intricate attribute descriptions.
> 


> The digital filter helps shape the noise rejection bandwidth and is
> supposed to be adjusted according to the signal of interest. Depending on
> the particular ADC design, the digital filter configuration may have an
> impact on the output data rate (ODR) (which is equivalent to the sampling
> frequency for SAR ADCs - `sampling_frequency` ABI), 3dB cutoff frequency of
> the filter (`_low_pass_3db_frequency` attributes), or settling time.
> 
> Digital filters are a common feature among sigma-delta ADCs and
> IIO drivers set digital filters according to different attributes.
> ad4130 and ad7779 filter options are supported through dedicated
> filter_mode/filter_type attributes in sysfs.
> ad7768-1 and ad7173 set the sinc filters according to the
> sampling_frequency attribute. No filter_type attribute.
> ad7124 sets the digital filter according to a filter_low_pass_3db_frequency
> attribute so it doesn't export filter type attributes to user space.

These last two paragraphs seems a bit excessive and could be dropped.

> 
> Fixes: 01bb12922b60 ("Documentation: ABI: added filter mode doc in sysfs-bus-iio")
> Signed-off-by: Marcelo Schmitt <marcelo.schmitt@analog.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-iio       |  1 -
>  .../ABI/testing/sysfs-bus-iio-adc-ad4130      | 20 +++++++++++++++++++
>  MAINTAINERS                                   |  1 +
>  3 files changed, 21 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index ff9cc09360dc..e4fd99c92d81 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -2277,7 +2277,6 @@ Description:
>  		representing the sensor unique ID number.
>  
>  What:		/sys/bus/iio/devices/iio:deviceX/filter_type_available
> -What:		/sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_mode_available

Instead of removing the line, I think we need to replace it with:

/sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_type_available

(change mode to type)

This attribute is used in the previous patch.


>  KernelVersion:	6.1
>  Contact:	linux-iio@vger.kernel.org
>  Description:
With those changes...

Reviewed-by: David Lechner <dlechner@baylibre.com>
Marcelo Schmitt Feb. 4, 2025, 12:53 p.m. UTC | #2 
On 02/03, David Lechner wrote:
> On 2/3/25 1:11 PM, Marcelo Schmitt wrote:
> > The ad4130 driver exports in_voltageY-voltageZ_filter_mode and
> > in_voltage-voltage_filter_mode_available attributes to user space. A
> > previous patch merged the documentation for those attributes with the
> > documentation for filter_type/filter_type_available into sysfs-bus-iio.
> > Filter mode and filter type refer to the same feature which is the digital
> > filter applied over ADC samples. However, since datasheets use the term
> > `filter type` and ad4130 driver is the only one using filter_mode,
> > deprecate the filter_mode ABI in favor of filter_type and keep the docs
> > separate to avoid confusion and intricate attribute descriptions.
> > 
> 
> 
> > The digital filter helps shape the noise rejection bandwidth and is
> > supposed to be adjusted according to the signal of interest. Depending on
> > the particular ADC design, the digital filter configuration may have an
> > impact on the output data rate (ODR) (which is equivalent to the sampling
> > frequency for SAR ADCs - `sampling_frequency` ABI), 3dB cutoff frequency of
> > the filter (`_low_pass_3db_frequency` attributes), or settling time.
> > 
> > Digital filters are a common feature among sigma-delta ADCs and
> > IIO drivers set digital filters according to different attributes.
> > ad4130 and ad7779 filter options are supported through dedicated
> > filter_mode/filter_type attributes in sysfs.
> > ad7768-1 and ad7173 set the sinc filters according to the
> > sampling_frequency attribute. No filter_type attribute.
> > ad7124 sets the digital filter according to a filter_low_pass_3db_frequency
> > attribute so it doesn't export filter type attributes to user space.
> 
> These last two paragraphs seems a bit excessive and could be dropped.

Yes, the patch is justified without those paragraphs.
I wanted to understand how digital filtering works and how it was supported
across IIO ADC drivers to implement something reasonable for AD4170.
Those are my conclusions after looking at few ADC drivers.
I thought those could be useful but didn't have a good place to write to.
Oh well, that is not covering all ADCs so also a bit far-fetched to propose it
as some doc. Will drop the extra text on v4.

> 
> > 
> > Fixes: 01bb12922b60 ("Documentation: ABI: added filter mode doc in sysfs-bus-iio")
> > Signed-off-by: Marcelo Schmitt <marcelo.schmitt@analog.com>
> > ---
> >  Documentation/ABI/testing/sysfs-bus-iio       |  1 -
> >  .../ABI/testing/sysfs-bus-iio-adc-ad4130      | 20 +++++++++++++++++++
> >  MAINTAINERS                                   |  1 +
> >  3 files changed, 21 insertions(+), 1 deletion(-)
> >  create mode 100644 Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > index ff9cc09360dc..e4fd99c92d81 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -2277,7 +2277,6 @@ Description:
> >  		representing the sensor unique ID number.
> >  
> >  What:		/sys/bus/iio/devices/iio:deviceX/filter_type_available
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_mode_available
> 
> Instead of removing the line, I think we need to replace it with:
> 
> /sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_type_available
> 
> (change mode to type)
> 
> This attribute is used in the previous patch.
> 
> 
> >  KernelVersion:	6.1
> >  Contact:	linux-iio@vger.kernel.org
> >  Description:
> With those changes...
> 
> Reviewed-by: David Lechner <dlechner@baylibre.com>
Marcelo Schmitt Feb. 4, 2025, 1 p.m. UTC | #3 
On 02/03, David Lechner wrote:
> On 2/3/25 1:11 PM, Marcelo Schmitt wrote:
> > The ad4130 driver exports in_voltageY-voltageZ_filter_mode and
> > in_voltage-voltage_filter_mode_available attributes to user space. A
> > previous patch merged the documentation for those attributes with the
> > documentation for filter_type/filter_type_available into sysfs-bus-iio.
> > Filter mode and filter type refer to the same feature which is the digital
> > filter applied over ADC samples. However, since datasheets use the term
> > `filter type` and ad4130 driver is the only one using filter_mode,
> > deprecate the filter_mode ABI in favor of filter_type and keep the docs
> > separate to avoid confusion and intricate attribute descriptions.
> > 
> 
> 
> > The digital filter helps shape the noise rejection bandwidth and is
> > supposed to be adjusted according to the signal of interest. Depending on
> > the particular ADC design, the digital filter configuration may have an
> > impact on the output data rate (ODR) (which is equivalent to the sampling
> > frequency for SAR ADCs - `sampling_frequency` ABI), 3dB cutoff frequency of
> > the filter (`_low_pass_3db_frequency` attributes), or settling time.
> > 
> > Digital filters are a common feature among sigma-delta ADCs and
> > IIO drivers set digital filters according to different attributes.
> > ad4130 and ad7779 filter options are supported through dedicated
> > filter_mode/filter_type attributes in sysfs.
> > ad7768-1 and ad7173 set the sinc filters according to the
> > sampling_frequency attribute. No filter_type attribute.
> > ad7124 sets the digital filter according to a filter_low_pass_3db_frequency
> > attribute so it doesn't export filter type attributes to user space.
> 
> These last two paragraphs seems a bit excessive and could be dropped.
> 
> > 
> > Fixes: 01bb12922b60 ("Documentation: ABI: added filter mode doc in sysfs-bus-iio")
> > Signed-off-by: Marcelo Schmitt <marcelo.schmitt@analog.com>
> > ---
> >  Documentation/ABI/testing/sysfs-bus-iio       |  1 -
> >  .../ABI/testing/sysfs-bus-iio-adc-ad4130      | 20 +++++++++++++++++++
> >  MAINTAINERS                                   |  1 +
> >  3 files changed, 21 insertions(+), 1 deletion(-)
> >  create mode 100644 Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > index ff9cc09360dc..e4fd99c92d81 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -2277,7 +2277,6 @@ Description:
> >  		representing the sensor unique ID number.
> >  
> >  What:		/sys/bus/iio/devices/iio:deviceX/filter_type_available
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_mode_available
> 
> Instead of removing the line, I think we need to replace it with:
> 
> /sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_type_available
> 
> (change mode to type)
> 
> This attribute is used in the previous patch.

Ah yes, good catch.
Will do. And will also reorder the patches so it gets documented before being used.

Thanks,
Marcelo

> 
> 
> >  KernelVersion:	6.1
> >  Contact:	linux-iio@vger.kernel.org
> >  Description:
> With those changes...
> 
> Reviewed-by: David Lechner <dlechner@baylibre.com>
diff mbox series

Patch

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index ff9cc09360dc..e4fd99c92d81 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -2277,7 +2277,6 @@  Description:
 		representing the sensor unique ID number.
 
 What:		/sys/bus/iio/devices/iio:deviceX/filter_type_available
-What:		/sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_mode_available
 KernelVersion:	6.1
 Contact:	linux-iio@vger.kernel.org
 Description:
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130 b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130
new file mode 100644
index 000000000000..9c0698ad27f9
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130
@@ -0,0 +1,20 @@ 
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_mode_available
+KernelVersion:  6.2
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Reading returns a list with the possible filter modes.
+
+		This ABI is only kept for backwards compatibility and the values
+		returned are identical to filter_type_available attribute
+		documented in Documentation/ABI/testing/sysfs-bus-iio. Please,
+		use filter_type_available to provide filter options for new
+		drivers.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY-voltageZ_filter_mode
+KernelVersion:  6.2
+Contact:	linux-iio@vger.kernel.org
+Description:
+		This ABI is only kept for backwards compatibility and the values
+		returned are identical to in_voltageY-voltageZ_filter_type
+		attribute documented in Documentation/ABI/testing/sysfs-bus-iio.
+		Please, use in_voltageY-voltageZ_filter_type for new drivers.
diff --git a/MAINTAINERS b/MAINTAINERS
index 98a3c1e46311..28dbbf6d6efa 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1279,6 +1279,7 @@  M:	Cosmin Tanislav <cosmin.tanislav@analog.com>
 L:	linux-iio@vger.kernel.org
 S:	Supported
 W:	https://ez.analog.com/linux-software-drivers
+F:	Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130
 F:	Documentation/devicetree/bindings/iio/adc/adi,ad4130.yaml
 F:	drivers/iio/adc/ad4130.c