[RFC 0/2] ABI: IIO: proposal for AVERAGING_RATIO support

This is an attempt to document/define simple downsampling/averaging
features for some ADC devices.

As discussed in https://lkml.org/lkml/2015/11/16/566

As an illustration, Patch 2 is an instance of implementation
using ina226.

Marc Titinger (2):
  ABI: iio: support AVERAGING_RATIO setting
  iio: ina2xx: convert AVERGING ratio setting from generic sysfs attr to
    ABI

 Documentation/ABI/testing/sysfs-bus-iio | 13 +++++++++
 drivers/iio/adc/ina2xx-iio.c            | 47 +++++----------------------------
 drivers/iio/industrialio-core.c         |  1 +
 include/linux/iio/iio.h                 |  1 +
 include/linux/iio/sysfs.h               |  9 +++++++
 5 files changed, 30 insertions(+), 41 deletions(-)

-- 
1.9.1

using the proposed ABI addition for IIO_CHAN_INFO_AVERAGING_RATIO, convert
the sysfs attribute for averaging ratio to using in_averaging_ratio as a
directory-bound channel info.

Signed-off-by: Marc Titinger <redacted>
---
 drivers/iio/adc/ina2xx-iio.c | 47 ++++++--------------------------------------
 1 file changed, 6 insertions(+), 41 deletions(-)

diff --git a/drivers/iio/adc/ina2xx-iio.c b/drivers/iio/adc/ina2xx-iio.c
index d4dd908..f6daa5b 100644
--- a/drivers/iio/adc/ina2xx-iio.c
+++ b/drivers/iio/adc/ina2xx-iio.c

@@ -179,7 +179,7 @@ static int ina2xx_read_raw(struct iio_dev *indio_dev,
 
 		return ina2xx_get_value(chip, chan->address, regval, val, val2);
 
-	case IIO_CHAN_INFO_AVERAGE_RAW:
+	case IIO_CHAN_INFO_AVERAGING_RATIO:
 		*val = chip->avg;
 		return IIO_VAL_INT;
 

@@ -219,6 +219,8 @@ static int ina2xx_calibrate(struct ina2xx_chip_info *chip)
  */
 static const int ina226_avg_tab[] = { 1, 4, 16, 64, 128, 256, 512, 1024 };
 
+static IIO_CONST_ATTR_AVERAGING_RATIO_AVAIL("1, 4, 16, 64, 128, 256, 512, 1024");
+
 static unsigned int ina226_set_average(struct ina2xx_chip_info *chip,
 				       unsigned int val,
 				       unsigned int *config)

@@ -286,7 +288,7 @@ static int ina2xx_write_raw(struct iio_dev *indio_dev,
 	tmp = config;
 
 	switch (mask) {
-	case IIO_CHAN_INFO_AVERAGE_RAW:
+	case IIO_CHAN_INFO_AVERAGING_RATIO:
 
 		ret = ina226_set_average(chip, val, &tmp);
 		break;

@@ -308,40 +310,6 @@ _err:
 	return ret;
 }
 
-
-static ssize_t ina2xx_averaging_steps_show(struct device *dev,
-					   struct device_attribute *attr,
-					   char *buf)
-{
-	struct ina2xx_chip_info *chip = iio_priv(dev_to_iio_dev(dev));
-
-	return sprintf(buf, "%d\n", chip->avg);
-}
-
-
-static ssize_t ina2xx_averaging_steps_store(struct device *dev,
-				struct device_attribute *attr,
-				const char *buf, size_t len)
-{
-	unsigned long val;
-	int ret;
-
-	ret = kstrtoul((const char *) buf, 10, &val);
-	if (ret)
-		return -EINVAL;
-
-	/* unexposed missuse of INFO_AVERAGE_RAW, until a proper ABI for the
-	 * averaging steps setting is specified.
-	 */
-	ret  = ina2xx_write_raw(dev_to_iio_dev(dev), NULL, val, 0,
-				IIO_CHAN_INFO_AVERAGE_RAW);
-	if (ret < 0)
-		return ret;
-
-	return len;
-}
-
-
 #define INA2XX_CHAN(_type, _index, _address) { \
 	.type = _type, \
 	.address = _address, \

@@ -349,6 +317,7 @@ static ssize_t ina2xx_averaging_steps_store(struct device *dev,
 	.channel = (_index), \
 	.info_mask_separate = BIT(IIO_CHAN_INFO_RAW), \
 	.info_mask_shared_by_dir = BIT(IIO_CHAN_INFO_SAMP_FREQ) | \
+				   BIT(IIO_CHAN_INFO_AVERAGING_RATIO) | \
 				   BIT(IIO_CHAN_INFO_CALIBSCALE), \
 	.scan_index = (_index), \
 	.scan_type = { \

@@ -382,13 +351,9 @@ static int ina2xx_debug_reg(struct iio_dev *indio_dev,
 /* frequencies matching the cummulated integration times for vshunt and vbus */
 static IIO_CONST_ATTR_SAMP_FREQ_AVAIL("61 120 236 455 850 1506 2450 3571");
 
-static IIO_DEVICE_ATTR(in_averaging_steps, S_IRUGO | S_IWUSR,
-		       ina2xx_averaging_steps_show,
-		       ina2xx_averaging_steps_store, 0);
-
 static struct attribute *ina2xx_attributes[] = {
-	&iio_dev_attr_in_averaging_steps.dev_attr.attr,
 	&iio_const_attr_sampling_frequency_available.dev_attr.attr,
+	&iio_const_attr_averaging_ratio_available.dev_attr.attr,
 	NULL,
 };
 

-- 
1.9.1

Some ADC devices allow averaging/downsampling. The minimal parameter
set for this will be the number of taps used for computing a mean value.

In some cases the ratio will hold discrete values for instance "1, 4, 16"
hence an averaging_ratio_available property is useful. The possible ratio
values are less likely to changing with the device settings, so this patch
only provides a CONST version of the definition helper.

Tested with ina226:

# ls /sys/bus/iio/devices/iio\:device0/
averaging_ratio_available     in_voltage0_raw
dev                           in_voltage1_raw
in_averaging_ratio            name
in_calibscale                 power
in_current2_raw               sampling_frequency_available
in_power3_raw                 subsystem
in_sampling_frequency         uevent

# cat averaging_ratio_available
1, 4, 16, 64, 128, 256, 512, 1024

Signed-off-by: Marc Titinger <redacted>
---
 Documentation/ABI/testing/sysfs-bus-iio | 13 +++++++++++++
 drivers/iio/industrialio-core.c         |  1 +
 include/linux/iio/iio.h                 |  1 +
 include/linux/iio/sysfs.h               |  9 +++++++++
 4 files changed, 24 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 42d360f..a208dfe 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio

@@ -56,6 +56,19 @@ Description:
 		When the internal sampling clock can only take a small
 		discrete set of values, this file lists those available.
 
+What:		/sys/bus/iio/devices/iio:deviceX/averaging_ratio
+KernelVersion:	4.x.x
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Hardware dependent ADC averaging. Controls the averaging ratio
+		of the digital filter if available.
+
+What:		/sys/bus/iio/devices/iio:deviceX/averaging_ratio_available
+KernelVersion:	4.x.x
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Hardware dependent values supported by the averaging filter.
+
 What:		/sys/bus/iio/devices/iio:deviceX/oversampling_ratio
 KernelVersion:	2.6.38
 Contact:	linux-iio@vger.kernel.org

diff --git a/drivers/iio/industrialio-core.c b/drivers/iio/industrialio-core.c
index b3fcc2c..e4745f0 100644
--- a/drivers/iio/industrialio-core.c
+++ b/drivers/iio/industrialio-core.c

@@ -142,6 +142,7 @@ static const char * const iio_chan_info_postfix[] = {
 	[IIO_CHAN_INFO_DEBOUNCE_TIME] = "debounce_time",
 	[IIO_CHAN_INFO_CALIBEMISSIVITY] = "calibemissivity",
 	[IIO_CHAN_INFO_OVERSAMPLING_RATIO] = "oversampling_ratio",
+	[IIO_CHAN_INFO_AVERAGING_RATIO] = "averaging_ratio",
 };
 
 /**

diff --git a/include/linux/iio/iio.h b/include/linux/iio/iio.h
index 7bb7f67..4c84de5 100644
--- a/include/linux/iio/iio.h
+++ b/include/linux/iio/iio.h

@@ -46,6 +46,7 @@ enum iio_chan_info_enum {
 	IIO_CHAN_INFO_DEBOUNCE_TIME,
 	IIO_CHAN_INFO_CALIBEMISSIVITY,
 	IIO_CHAN_INFO_OVERSAMPLING_RATIO,
+	IIO_CHAN_INFO_AVERAGING_RATIO,
 };
 
 enum iio_shared_by {

diff --git a/include/linux/iio/sysfs.h b/include/linux/iio/sysfs.h
index 9cd8f74..4478ba1 100644
--- a/include/linux/iio/sysfs.h
+++ b/include/linux/iio/sysfs.h

@@ -76,6 +76,15 @@ struct iio_const_attr {
 /* Generic attributes of onetype or another */
 
 /**
+ * IIO_CONST_ATTR_AVERAGING_RATIO_AVAIL - list available averaging ratios
+ * @_string: ratio string for the attribute
+ *
+ * Constant version
+ **/
+#define IIO_CONST_ATTR_AVERAGING_RATIO_AVAIL(_string)                 \
+	IIO_CONST_ATTR(averaging_ratio_available, _string)
+
+/**
  * IIO_DEV_ATTR_SAMP_FREQ - sets any internal clock frequency
  * @_mode: sysfs file mode/permissions
  * @_show: output method for the attribute

-- 
1.9.1

On 17.11.2015 10:44, Marc Titinger wrote:

Some ADC devices allow averaging/downsampling. The minimal parameter
set for this will be the number of taps used for computing a mean value.

In some cases the ratio will hold discrete values for instance "1, 4, 16"
hence an averaging_ratio_available property is useful. The possible ratio
values are less likely to changing with the device settings, so this patch
only provides a CONST version of the definition helper.

Tested with ina226:

# ls /sys/bus/iio/devices/iio\:device0/
averaging_ratio_available     in_voltage0_raw
dev                           in_voltage1_raw
in_averaging_ratio            name
in_calibscale                 power
in_current2_raw               sampling_frequency_available
in_power3_raw                 subsystem
in_sampling_frequency         uevent

# cat averaging_ratio_available
1, 4, 16, 64, 128, 256, 512, 1024

Signed-off-by: Marc Titinger <redacted>

Having just noted the previous element we added was oversampling_ratio,
in a sense they are somewhat similar.

To play Devil's advocate...
Could we in theory just use that as it is existing ABI?

oversampling_ratio was introduced for the bmc150.
That particular part doesn't have the worlds clearest datasheet
but it seems like it's effectively specifying how many repeat measurements
to average.

I'm afraid I'd completely forgotten about this or
I would have mentioned it earlier!

Jonathan

36 more quoted lines

On 17/11/2015 14:39, jic23@jic23.retrosnub.co.uk wrote:

On 17.11.2015 10:44, Marc Titinger wrote:

quoted

Some ADC devices allow averaging/downsampling. The minimal parameter
set for this will be the number of taps used for computing a mean value.

In some cases the ratio will hold discrete values for instance "1, 4, 16"
hence an averaging_ratio_available property is useful. The possible ratio
values are less likely to changing with the device settings, so this
patch
only provides a CONST version of the definition helper.

Tested with ina226:

# ls /sys/bus/iio/devices/iio\:device0/
averaging_ratio_available     in_voltage0_raw
dev                           in_voltage1_raw
in_averaging_ratio            name
in_calibscale                 power
in_current2_raw               sampling_frequency_available
in_power3_raw                 subsystem
in_sampling_frequency         uevent

# cat averaging_ratio_available
1, 4, 16, 64, 128, 256, 512, 1024

Signed-off-by: Marc Titinger <redacted>

Having just noted the previous element we added was oversampling_ratio,
in a sense they are somewhat similar.

To play Devil's advocate...
Could we in theory just use that as it is existing ABI?

oversampling_ratio was introduced for the bmc150.
That particular part doesn't have the worlds clearest datasheet
but it seems like it's effectively specifying how many repeat measurements
to average.

I'm afraid I'd completely forgotten about this or
I would have mentioned it earlier!

I saw that oversampling setting, but I my memories, oversampling was sometimes related to increasing the samplerate, i.e creating more samples possibly through interpolation, in order to allow for filtering.

If there is a consensus about this being ok to mean 'averaging' I'm happy to use this ABI!

M.

Jonathan

quoted

---
 Documentation/ABI/testing/sysfs-bus-iio | 13 +++++++++++++
 drivers/iio/industrialio-core.c         |  1 +
 include/linux/iio/iio.h                 |  1 +
 include/linux/iio/sysfs.h               |  9 +++++++++
 4 files changed, 24 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio

b/Documentation/ABI/testing/sysfs-bus-iio
index 42d360f..a208dfe 100644

--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio

@@ -56,6 +56,19 @@ Description:
         When the internal sampling clock can only take a small
         discrete set of values, this file lists those available.

+What:        /sys/bus/iio/devices/iio:deviceX/averaging_ratio
+KernelVersion:    4.x.x
+Contact:    linux-iio@vger.kernel.org
+Description:
+        Hardware dependent ADC averaging. Controls the averaging ratio
+        of the digital filter if available.
+
+What:        /sys/bus/iio/devices/iio:deviceX/averaging_ratio_available
+KernelVersion:    4.x.x
+Contact:    linux-iio@vger.kernel.org
+Description:
+        Hardware dependent values supported by the averaging filter.
+
 What:        /sys/bus/iio/devices/iio:deviceX/oversampling_ratio
 KernelVersion:    2.6.38
 Contact:    linux-iio@vger.kernel.org

diff --git a/drivers/iio/industrialio-core.c

b/drivers/iio/industrialio-core.c
index b3fcc2c..e4745f0 100644

--- a/drivers/iio/industrialio-core.c
+++ b/drivers/iio/industrialio-core.c

42 more quoted lines