linux-kernel - [PATCH v2 1/3] Documentation: ABI: IIO: Re-add sysfs-bus-iio-adc-ad4130

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <d03c85e527ffa5f8d54da55b7562cf84b1fc68fd.1736261048.git.marcelo.schmitt@analog.com>
Date: Tue, 7 Jan 2025 12:12:02 -0300
From: Marcelo Schmitt <marcelo.schmitt@...log.com>
To: <linux-iio@...r.kernel.org>, <linux-kernel@...r.kernel.org>
CC: <cosmin.tanislav@...log.com>, <jic23@...nel.org>, <lars@...afoo.de>,
        <marcelo.schmitt@...log.com>, <dlechner@...libre.com>,
        <granquet@...libre.com>, <u.kleine-koenig@...libre.com>,
        <marcelo.schmitt1@...il.com>
Subject: [PATCH v2 1/3] Documentation: ABI: IIO: Re-add sysfs-bus-iio-adc-ad4130

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@...log.com>
---
Second and third paragraphs of the body could maybe go into device specific docs
as suggested in some previous thread but those drivers don't have docs in
Documentation/iio/ and I've been more interested in how filter_type is supported
accross IIO to be able to support it appropriatly in new drivers.

 Documentation/ABI/testing/sysfs-bus-iio       |  1 -
 .../ABI/testing/sysfs-bus-iio-adc-ad4130      | 55 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 3 files changed, 56 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 d97c35057a03..1faac5b2ad84 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@...r.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..bd827186ad1f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad4130
@@ -0,0 +1,55 @@
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_filter_mode_available
+KernelVersion:  6.2
+Contact:	linux-iio@...r.kernel.org
+Description:
+		Reading returns a list with the possible filter modes.
+
+		  * "sinc4"       - Sinc 4. Excellent noise performance. Long
+                    1st conversion time. No natural 50/60Hz rejection.
+
+		  * "sinc4+sinc1" - Sinc4 + averaging by 8. Low 1st conversion
+		    time.
+
+		  * "sinc3"	      - Sinc3. Moderate 1st conversion time.
+		    Good noise performance.
+
+		  * "sinc3+rej60" - Sinc3 + 60Hz rejection. At a sampling
+		    frequency of 50Hz, achieves simultaneous 50Hz and 60Hz
+		    rejection.
+
+		  * "sinc3+sinc1" - Sinc3 + averaging by 8. Low 1st conversion
+		    time. Best used with a sampling frequency of at least
+		    216.19Hz.
+
+		  * "sinc3+pf1"   - Sinc3 + Post Filter 1. 53dB rejection @
+		    50Hz, 58dB rejection @ 60Hz.
+
+		  * "sinc3+pf2"   - Sinc3 + Post Filter 2. 70dB rejection @
+		    50Hz, 70dB rejection @ 60Hz.
+
+		  * "sinc3+pf3"   - Sinc3 + Post Filter 3. 99dB rejection @
+		    50Hz, 103dB rejection @ 60Hz.
+
+		  * "sinc3+pf4"   - Sinc3 + Post Filter 4. 103dB rejection @
+		    50Hz, 109dB rejection @ 60Hz.
+
+		This interface is deprecated; please use filter_type_available
+		documented in Documentation/ABI/testing/sysfs-bus-iio 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@...r.kernel.org
+Description:
+		Set the filter mode of the differential channel. When the filter
+		mode changes, the in_voltageY-voltageZ_sampling_frequency and
+		in_voltageY-voltageZ_sampling_frequency_available attributes
+		might also change to accommodate the new filter mode.
+		If the current sampling frequency is out of range for the new
+		filter mode, the sampling frequency will be changed to the
+		closest valid one.
+
+		This interface is deprecated; please use
+		in_voltageY-voltageZ_filter_type documented in
+		Documentation/ABI/testing/sysfs-bus-iio to provide
+		filter options 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@...log.com>
 L:	linux-iio@...r.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
 
-- 
2.45.2