[RFC PATCH 0/7] IIO ABI documentation duplication fixes

[RFC PATCH 0/7] IIO ABI documentation duplication fixes

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

The nature of IIO devices is that they are highly varied and occaisonly
ABI is used in somewhat of a 'best fit' fashion.  This has lead to a
situation where we had additional more specific ABI docs for some sysfs
parameters in certain drivers.  Unfortunately the automated documentation
building doesn't work well with this both issuing warnings and building
a less than ideal output.

So this series attempts to fix that up, mostly by moving the application
specific parts, of properties that are documented in more than one place,
into a higher level documentation file, sometimes with a device specific
note. In a few cases this the result is a bit non-obvious hence the RFC.
Roughly speaking I've put the more 'interesting' cases towards the end
of the series.

It's worth noting that a general reorganzation, audit of missing docs
etc is needed for the IIO ABI docs, but as that's a big job it may well
take sometime to get it done. In the meantime let's deal with these
issues.  Some of the drivers have complex enough ABI that we should probably
have detailed docs for them in addition to Documentation/ABI.

Note I haven't yet touched the remaining case of
Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_preset is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:100  ./Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  ./Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8

This is mainly because I don't really know enough about these devices
to conclude exactly what a fused bit of docs should look like.
Also worth noting that those are probably deprecated ABI anyway given
the move of counters into their own subsystem.

Jonathan Cameron (7):
  iio:ABI docs: Fix up duplicate *_calibbias_* documentation for
    icm42600
  iio:ABI docs: Avoid repitition of triggerX/sampling_frequency
  iio:ABI docs: Drop device specific docs for _powerdown for the adf4371
  iio:ABI docs: Fix issue around repeated definition of out_currentY_raw
  iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one
    file
  iio:ABI docs: Combine the two instances of docs for sensor_sensitivity
  iio:ABI docs: Move specific description of out_altvoltageX_frequency
    to main docs.

 Documentation/ABI/testing/sysfs-bus-iio       | 45 +++++++++++++++++++
 .../ABI/testing/sysfs-bus-iio-distance-srf08  |  8 ----
 .../testing/sysfs-bus-iio-frequency-adf4371   | 33 --------------
 .../ABI/testing/sysfs-bus-iio-health-afe440x  | 10 +----
 ...umidity-hdc2010 => sysfs-bus-iio-humidity} |  3 +-
 .../testing/sysfs-bus-iio-humidity-hdc100x    |  9 ----
 .../ABI/testing/sysfs-bus-iio-icm42600        | 20 ---------
 .../testing/sysfs-bus-iio-light-lm3533-als    | 11 ++---
 .../ABI/testing/sysfs-bus-iio-proximity       | 14 ++++++
 .../testing/sysfs-bus-iio-proximity-as3935    |  9 ----
 .../ABI/testing/sysfs-bus-iio-timer-stm32     |  8 ----
 11 files changed, 66 insertions(+), 104 deletions(-)
 rename Documentation/ABI/testing/{sysfs-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} (79%)
 delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
 delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-icm42600

-- 
2.30.0

[RFC PATCH 1/7] iio:ABI docs: Fix up duplicate *_calibbias_* documentation for icm42600

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

This device has the unusual characteristic that the calibbias values
have well defined units (more commonly they are tweaks to a DAC)
Unfortunately the previous approach of having more specific documentation
in sysfs-bus-iio-icm42600 results in warnings during the documentation
build and random ordering in the resulting documentation.

To avoid this, add a note to the main documentation on this special
characteristic for the icm42600.   The _available for calibbias was
missing from the main sysfs-bus-iio docs so also add that, allowing
us to drop the icm42600 specific file.

Fixes
$ scripts/get_abi.pl validate warning:
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  ./Documentation/ABI/testing/sysfs-bus-iio:394
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  ./Documentation/ABI/testing/sysfs-bus-iio:395
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  ./Documentation/ABI/testing/sysfs-bus-iio:396
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  ./Documentation/ABI/testing/sysfs-bus-iio:397
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  ./Documentation/ABI/testing/sysfs-bus-iio:398
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  ./Documentation/ABI/testing/sysfs-bus-iio:399

Cc: Jean-Baptiste Maneyrol <jmaneyrol@invensense.com>
Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 Documentation/ABI/testing/sysfs-bus-iio       | 13 ++++++++++++
 .../ABI/testing/sysfs-bus-iio-icm42600        | 20 -------------------
 2 files changed, 13 insertions(+), 20 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index d957f5da5c04..d2dd9cc280f9 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -408,6 +408,19 @@ Contact:	linux-iio@vger.kernel.org
 Description:
 		Hardware applied calibration offset (assumed to fix production
 		inaccuracies).
+		icm42600: For this device values are real physical offsets
+		expressed in SI units (m/s^2 for accelerometers and rad/s
+		for gyroscope)/
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
+KernelVersion:  5.8
+Contact:        linux-iio@vger.kernel.org
+Description:
+		Available values of calibbias. Maybe expressed as either of:
+
+		- a small discrete set of values like "0 2 4 6 8"
+		- a range specified as "[min step max]"
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-icm42600 b/Documentation/ABI/testing/sysfs-bus-iio-icm42600
deleted file mode 100644
index 0bf1fd4f5bf1..000000000000
--- a/Documentation/ABI/testing/sysfs-bus-iio-icm42600
+++ /dev/null
@@ -1,20 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias
-KernelVersion:  5.8
-Contact:        linux-iio@vger.kernel.org
-Description:
-		Hardware applied calibration offset (assumed to fix production
-		inaccuracies). Values represent a real physical offset expressed
-		in SI units (m/s^2 for accelerometer and rad/s for gyroscope).
-
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
-KernelVersion:  5.8
-Contact:        linux-iio@vger.kernel.org
-Description:
-		Range of available values for hardware offset. Values in SI
-		units (m/s^2 for accelerometer and rad/s for gyroscope).
-- 
2.30.0

Re: [RFC PATCH 1/7] iio:ABI docs: Fix up duplicate *_calibbias_* documentation for icm42600

[Jonathan Cameron]

On Sun, 17 Jan 2021 15:38:10 +0000
Jonathan Cameron <jic23@kernel.org> wrote:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
@Jean-Baptiste.

Whilst this is 'fairly obviously' fine, could you take a quick glance at it.
I'm never keen to take my own patches without someone having agreed
I haven't done anything particularly silly ;)

Jonathan

> 
> This device has the unusual characteristic that the calibbias values
> have well defined units (more commonly they are tweaks to a DAC)
> Unfortunately the previous approach of having more specific documentation
> in sysfs-bus-iio-icm42600 results in warnings during the documentation
> build and random ordering in the resulting documentation.
> 
> To avoid this, add a note to the main documentation on this special
> characteristic for the icm42600.   The _available for calibbias was
> missing from the main sysfs-bus-iio docs so also add that, allowing
> us to drop the icm42600 specific file.
> 
> Fixes
> $ scripts/get_abi.pl validate warning:
> Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  ./Documentation/ABI/testing/sysfs-bus-iio:394
> Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  ./Documentation/ABI/testing/sysfs-bus-iio:395
> Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  ./Documentation/ABI/testing/sysfs-bus-iio:396
> Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  ./Documentation/ABI/testing/sysfs-bus-iio:397
> Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  ./Documentation/ABI/testing/sysfs-bus-iio:398
> Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  ./Documentation/ABI/testing/sysfs-bus-iio:399
> 
> Cc: Jean-Baptiste Maneyrol <jmaneyrol@invensense.com>
> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-iio       | 13 ++++++++++++
>  .../ABI/testing/sysfs-bus-iio-icm42600        | 20 -------------------
>  2 files changed, 13 insertions(+), 20 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index d957f5da5c04..d2dd9cc280f9 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -408,6 +408,19 @@ Contact:	linux-iio@vger.kernel.org
>  Description:
>  		Hardware applied calibration offset (assumed to fix production
>  		inaccuracies).
> +		icm42600: For this device values are real physical offsets
> +		expressed in SI units (m/s^2 for accelerometers and rad/s
> +		for gyroscope)/
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
> +What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
> +KernelVersion:  5.8
> +Contact:        linux-iio@vger.kernel.org
> +Description:
> +		Available values of calibbias. Maybe expressed as either of:
> +
> +		- a small discrete set of values like "0 2 4 6 8"
> +		- a range specified as "[min step max]"
>  
>  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
>  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-icm42600 b/Documentation/ABI/testing/sysfs-bus-iio-icm42600
> deleted file mode 100644
> index 0bf1fd4f5bf1..000000000000
> --- a/Documentation/ABI/testing/sysfs-bus-iio-icm42600
> +++ /dev/null
> @@ -1,20 +0,0 @@
> -What:		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias
> -What:		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias
> -What:		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias
> -What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias
> -What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias
> -What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias
> -KernelVersion:  5.8
> -Contact:        linux-iio@vger.kernel.org
> -Description:
> -		Hardware applied calibration offset (assumed to fix production
> -		inaccuracies). Values represent a real physical offset expressed
> -		in SI units (m/s^2 for accelerometer and rad/s for gyroscope).
> -
> -What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
> -What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
> -KernelVersion:  5.8
> -Contact:        linux-iio@vger.kernel.org
> -Description:
> -		Range of available values for hardware offset. Values in SI
> -		units (m/s^2 for accelerometer and rad/s for gyroscope).

Re: [RFC PATCH 1/7] iio:ABI docs: Fix up duplicate *_calibbias_* documentation for icm42600

[Jonathan Cameron]

On Sun, 21 Feb 2021 16:05:29 +0000
Jonathan Cameron <jic23@kernel.org> wrote:

> On Sun, 17 Jan 2021 15:38:10 +0000
> Jonathan Cameron <jic23@kernel.org> wrote:
> 
> > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>  
> @Jean-Baptiste.
> 
> Whilst this is 'fairly obviously' fine, could you take a quick glance at it.
> I'm never keen to take my own patches without someone having agreed
> I haven't done anything particularly silly ;)

As these are still frustrating Mauro's attempt to get the docs to build
cleanly and it should be safe enough.

Applied to the togreg branch of iio.git and pushed out as testing for
the autobuilders to poke at it.

Jonathan

> 
> Jonathan
> 
> > 
> > This device has the unusual characteristic that the calibbias values
> > have well defined units (more commonly they are tweaks to a DAC)
> > Unfortunately the previous approach of having more specific documentation
> > in sysfs-bus-iio-icm42600 results in warnings during the documentation
> > build and random ordering in the resulting documentation.
> > 
> > To avoid this, add a note to the main documentation on this special
> > characteristic for the icm42600.   The _available for calibbias was
> > missing from the main sysfs-bus-iio docs so also add that, allowing
> > us to drop the icm42600 specific file.
> > 
> > Fixes
> > $ scripts/get_abi.pl validate warning:
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  ./Documentation/ABI/testing/sysfs-bus-iio:394
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  ./Documentation/ABI/testing/sysfs-bus-iio:395
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  ./Documentation/ABI/testing/sysfs-bus-iio:396
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  ./Documentation/ABI/testing/sysfs-bus-iio:397
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  ./Documentation/ABI/testing/sysfs-bus-iio:398
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  ./Documentation/ABI/testing/sysfs-bus-iio:399
> > 
> > Cc: Jean-Baptiste Maneyrol <jmaneyrol@invensense.com>
> > Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > ---
> >  Documentation/ABI/testing/sysfs-bus-iio       | 13 ++++++++++++
> >  .../ABI/testing/sysfs-bus-iio-icm42600        | 20 -------------------
> >  2 files changed, 13 insertions(+), 20 deletions(-)
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > index d957f5da5c04..d2dd9cc280f9 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -408,6 +408,19 @@ Contact:	linux-iio@vger.kernel.org
> >  Description:
> >  		Hardware applied calibration offset (assumed to fix production
> >  		inaccuracies).
> > +		icm42600: For this device values are real physical offsets
> > +		expressed in SI units (m/s^2 for accelerometers and rad/s
> > +		for gyroscope)/
> > +
> > +What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
> > +What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
> > +KernelVersion:  5.8
> > +Contact:        linux-iio@vger.kernel.org
> > +Description:
> > +		Available values of calibbias. Maybe expressed as either of:
> > +
> > +		- a small discrete set of values like "0 2 4 6 8"
> > +		- a range specified as "[min step max]"
> >  
> >  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
> >  What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-icm42600 b/Documentation/ABI/testing/sysfs-bus-iio-icm42600
> > deleted file mode 100644
> > index 0bf1fd4f5bf1..000000000000
> > --- a/Documentation/ABI/testing/sysfs-bus-iio-icm42600
> > +++ /dev/null
> > @@ -1,20 +0,0 @@
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias
> > -KernelVersion:  5.8
> > -Contact:        linux-iio@vger.kernel.org
> > -Description:
> > -		Hardware applied calibration offset (assumed to fix production
> > -		inaccuracies). Values represent a real physical offset expressed
> > -		in SI units (m/s^2 for accelerometer and rad/s for gyroscope).
> > -
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
> > -What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
> > -KernelVersion:  5.8
> > -Contact:        linux-iio@vger.kernel.org
> > -Description:
> > -		Range of available values for hardware offset. Values in SI
> > -		units (m/s^2 for accelerometer and rad/s for gyroscope).  
> 

[RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

The timer-stm32 provided a little more specific information than the main
docs about the value of 0 corresponding to stopping sampling.  Given that
this makes sense in general, move that statement over to the main docs
and drop the version in sysfs-bus-iio-timer-stm32

Fixes
$ scripts/get_abi.pl validate
/sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45

Cc: Fabrice Gasnier <fabrice.gasnier@st.com>
Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
 Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
 2 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index d2dd9cc280f9..9b5ceb22363d 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -55,6 +55,8 @@ Description:
 		direct access interfaces, it may be found in any of the
 		relevant directories.  If it affects all of the above
 		then it is to be found in the base device directory.
+		Note a value 0 where supported, will correspond to sampling
+		stopping.
 
 What:		/sys/bus/iio/devices/iio:deviceX/sampling_frequency_available
 What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
index c4a4497c249a..05074c4a65e2 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
@@ -90,14 +90,6 @@ Description:
 		Reading returns the current master modes.
 		Writing set the master mode
 
-What:		/sys/bus/iio/devices/triggerX/sampling_frequency
-KernelVersion:	4.11
-Contact:	benjamin.gaignard@st.com
-Description:
-		Reading returns the current sampling frequency.
-		Writing an value different of 0 set and start sampling.
-		Writing 0 stop sampling.
-
 What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
 KernelVersion:	4.12
 Contact:	benjamin.gaignard@st.com
-- 
2.30.0

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

[Fabrice Gasnier]

On 1/17/21 4:38 PM, Jonathan Cameron wrote:
> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
>
> The timer-stm32 provided a little more specific information than the main
> docs about the value of 0 corresponding to stopping sampling.  Given that
> this makes sense in general, move that statement over to the main docs
> and drop the version in sysfs-bus-iio-timer-stm32
>
> Fixes
> $ scripts/get_abi.pl validate
> /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
>
> Cc: Fabrice Gasnier <fabrice.gasnier@st.com>
> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
>  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
>  2 files changed, 2 insertions(+), 8 deletions(-)

Hi Jonathan,

Acked-by: Fabrice Gasnier <fabrice.gasnier@foss.st.com>

Thanks,

Fabrice

>
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index d2dd9cc280f9..9b5ceb22363d 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -55,6 +55,8 @@ Description:
>  		direct access interfaces, it may be found in any of the
>  		relevant directories.  If it affects all of the above
>  		then it is to be found in the base device directory.
> +		Note a value 0 where supported, will correspond to sampling
> +		stopping.
>  
>  What:		/sys/bus/iio/devices/iio:deviceX/sampling_frequency_available
>  What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> index c4a4497c249a..05074c4a65e2 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> @@ -90,14 +90,6 @@ Description:
>  		Reading returns the current master modes.
>  		Writing set the master mode
>  
> -What:		/sys/bus/iio/devices/triggerX/sampling_frequency
> -KernelVersion:	4.11
> -Contact:	benjamin.gaignard@st.com
> -Description:
> -		Reading returns the current sampling frequency.
> -		Writing an value different of 0 set and start sampling.
> -		Writing 0 stop sampling.
> -
>  What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
>  KernelVersion:	4.12
>  Contact:	benjamin.gaignard@st.com

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

[Lars-Peter Clausen]

On 1/17/21 4:38 PM, Jonathan Cameron wrote:
> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
>
> The timer-stm32 provided a little more specific information than the main
> docs about the value of 0 corresponding to stopping sampling.  Given that
> this makes sense in general, move that statement over to the main docs
> and drop the version in sysfs-bus-iio-timer-stm32
>
> Fixes
> $ scripts/get_abi.pl validate
> /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
>
> Cc: Fabrice Gasnier <fabrice.gasnier@st.com>
> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> ---
>   Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
>   Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
>   2 files changed, 2 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index d2dd9cc280f9..9b5ceb22363d 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -55,6 +55,8 @@ Description:
>   		direct access interfaces, it may be found in any of the
>   		relevant directories.  If it affects all of the above
>   		then it is to be found in the base device directory.
> +		Note a value 0 where supported, will correspond to sampling
> +		stopping.

Hm, I don't like this. 0 should be an invalid value for the standard 
ABI. Enabling/disabling of the trigger should be controlled by whether 
there are any active trigger consumers.

The stm32-timer-trigger implements a non-standard ABI and I think we 
need to document this explicitly. The driver does not have a set_state 
callback. So the frequency property is used to enable/disable the 
trigger, but as said above, for standard compliant triggers that should 
not be the case.

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

[Jonathan Cameron]

On Sun, 7 Mar 2021 10:40:18 +0100
Lars-Peter Clausen <lars@metafoo.de> wrote:

> On 1/17/21 4:38 PM, Jonathan Cameron wrote:
> > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> >
> > The timer-stm32 provided a little more specific information than the main
> > docs about the value of 0 corresponding to stopping sampling.  Given that
> > this makes sense in general, move that statement over to the main docs
> > and drop the version in sysfs-bus-iio-timer-stm32
> >
> > Fixes
> > $ scripts/get_abi.pl validate
> > /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
> >
> > Cc: Fabrice Gasnier <fabrice.gasnier@st.com>
> > Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > ---
> >   Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
> >   Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
> >   2 files changed, 2 insertions(+), 8 deletions(-)
> >
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > index d2dd9cc280f9..9b5ceb22363d 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -55,6 +55,8 @@ Description:
> >   		direct access interfaces, it may be found in any of the
> >   		relevant directories.  If it affects all of the above
> >   		then it is to be found in the base device directory.
> > +		Note a value 0 where supported, will correspond to sampling
> > +		stopping.  
> 
> Hm, I don't like this. 0 should be an invalid value for the standard 
> ABI. Enabling/disabling of the trigger should be controlled by whether 
> there are any active trigger consumers.
> 
> The stm32-timer-trigger implements a non-standard ABI and I think we 
> need to document this explicitly. The driver does not have a set_state 
> callback. So the frequency property is used to enable/disable the 
> trigger, but as said above, for standard compliant triggers that should 
> not be the case.
> 
Good point.  Ideally we'd also fix the stm32-timer-trigger to have
an explicit enable / disable (even if that works by setting the frequency
to 0 under the hook)

For now I've dropped the patch until this is resolved.

Thanks,

Jonathan

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

[Fabrice Gasnier]

On 3/7/21 1:04 PM, Jonathan Cameron wrote:
> On Sun, 7 Mar 2021 10:40:18 +0100
> Lars-Peter Clausen <lars@metafoo.de> wrote:
> 
>> On 1/17/21 4:38 PM, Jonathan Cameron wrote:
>>> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
>>>
>>> The timer-stm32 provided a little more specific information than the main
>>> docs about the value of 0 corresponding to stopping sampling.  Given that
>>> this makes sense in general, move that statement over to the main docs
>>> and drop the version in sysfs-bus-iio-timer-stm32
>>>
>>> Fixes
>>> $ scripts/get_abi.pl validate
>>> /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
>>>
>>> Cc: Fabrice Gasnier <fabrice.gasnier@st.com>
>>> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
>>> ---
>>>   Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
>>>   Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
>>>   2 files changed, 2 insertions(+), 8 deletions(-)
>>>
>>> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
>>> index d2dd9cc280f9..9b5ceb22363d 100644
>>> --- a/Documentation/ABI/testing/sysfs-bus-iio
>>> +++ b/Documentation/ABI/testing/sysfs-bus-iio
>>> @@ -55,6 +55,8 @@ Description:
>>>   		direct access interfaces, it may be found in any of the
>>>   		relevant directories.  If it affects all of the above
>>>   		then it is to be found in the base device directory.
>>> +		Note a value 0 where supported, will correspond to sampling
>>> +		stopping.  
>>
>> Hm, I don't like this. 0 should be an invalid value for the standard 
>> ABI. Enabling/disabling of the trigger should be controlled by whether 
>> there are any active trigger consumers.
>>
>> The stm32-timer-trigger implements a non-standard ABI and I think we 
>> need to document this explicitly. The driver does not have a set_state 
>> callback. So the frequency property is used to enable/disable the 
>> trigger, but as said above, for standard compliant triggers that should 
>> not be the case.
>>
> Good point.  Ideally we'd also fix the stm32-timer-trigger to have
> an explicit enable / disable (even if that works by setting the frequency
> to 0 under the hook)

Hi Jonathan,

I'd like to come up with something here...
The trivial use case is: the stm32-timer triggers the stm32-adc (by HW).
In this case, "set_trigger_state" perfectly fits the needs (looks like).

But such change doesn't seems trivial when considering one timer can
trig another timer in hardware here. The "set_trigger_state" isn't
called in such a case.
So, I'm not sure what could be suitable to implement explicit
enable/disable of the timer trigger ?

Just to share some thoughts here: For sure the stm32-timer-trigger would
need additional changes (I haven't forget other mail thread on the
preset attribute). I believe also some functionalities should be moved
to the counter framework. But, even provided this, I think there will
still be a need for an enable or disable attribute, for the trigger part.

Perhaps adding an enable/disable attribute could be a way here ?
If yes, would you have some suggestion on the naming ?

Please advice,
Thanks in advance,
Fabrice

> 
> For now I've dropped the patch until this is resolved.
> 
> Thanks,
> 
> Jonathan
> 
> 

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

[Jonathan Cameron]

On Fri, 12 Mar 2021 17:56:50 +0100
Fabrice Gasnier <fabrice.gasnier@foss.st.com> wrote:

> On 3/7/21 1:04 PM, Jonathan Cameron wrote:
> > On Sun, 7 Mar 2021 10:40:18 +0100
> > Lars-Peter Clausen <lars@metafoo.de> wrote:
> >   
> >> On 1/17/21 4:38 PM, Jonathan Cameron wrote:  
> >>> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> >>>
> >>> The timer-stm32 provided a little more specific information than the main
> >>> docs about the value of 0 corresponding to stopping sampling.  Given that
> >>> this makes sense in general, move that statement over to the main docs
> >>> and drop the version in sysfs-bus-iio-timer-stm32
> >>>
> >>> Fixes
> >>> $ scripts/get_abi.pl validate
> >>> /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
> >>>
> >>> Cc: Fabrice Gasnier <fabrice.gasnier@st.com>
> >>> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >>> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> >>> ---
> >>>   Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
> >>>   Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
> >>>   2 files changed, 2 insertions(+), 8 deletions(-)
> >>>
> >>> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> >>> index d2dd9cc280f9..9b5ceb22363d 100644
> >>> --- a/Documentation/ABI/testing/sysfs-bus-iio
> >>> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> >>> @@ -55,6 +55,8 @@ Description:
> >>>   		direct access interfaces, it may be found in any of the
> >>>   		relevant directories.  If it affects all of the above
> >>>   		then it is to be found in the base device directory.
> >>> +		Note a value 0 where supported, will correspond to sampling
> >>> +		stopping.    
> >>
> >> Hm, I don't like this. 0 should be an invalid value for the standard 
> >> ABI. Enabling/disabling of the trigger should be controlled by whether 
> >> there are any active trigger consumers.
> >>
> >> The stm32-timer-trigger implements a non-standard ABI and I think we 
> >> need to document this explicitly. The driver does not have a set_state 
> >> callback. So the frequency property is used to enable/disable the 
> >> trigger, but as said above, for standard compliant triggers that should 
> >> not be the case.
> >>  
> > Good point.  Ideally we'd also fix the stm32-timer-trigger to have
> > an explicit enable / disable (even if that works by setting the frequency
> > to 0 under the hook)  
> 
> Hi Jonathan,
> 
> I'd like to come up with something here...
> The trivial use case is: the stm32-timer triggers the stm32-adc (by HW).
> In this case, "set_trigger_state" perfectly fits the needs (looks like).
> 
> But such change doesn't seems trivial when considering one timer can
> trig another timer in hardware here. The "set_trigger_state" isn't
> called in such a case.

Ah. I'd forgotten that complexity.

> So, I'm not sure what could be suitable to implement explicit
> enable/disable of the timer trigger ?

Perhaps we should just document this one as non standard.  We already have
a few ABI docs that reflect devices that do something that is kind of
'in the spirit' of the ABI, but stretches in a little in an unusual direction.
For those we just say what parts they apply to.  It is existing ABI anyway
so there is no disadvantage in keeping it around if we can't come up with
something better.

> 
> Just to share some thoughts here: For sure the stm32-timer-trigger would
> need additional changes (I haven't forget other mail thread on the
> preset attribute). I believe also some functionalities should be moved
> to the counter framework. But, even provided this, I think there will
> still be a need for an enable or disable attribute, for the trigger part.
> 
> Perhaps adding an enable/disable attribute could be a way here ?

Hmm. At least based on limited caffeine in my system this morning I think
that we may be better off with it just being as it is now and a slightly
'stretch' of the ABI.  

What do others think?

Jonathan

> If yes, would you have some suggestion on the naming ?
> 
> Please advice,
> Thanks in advance,
> Fabrice
> 
> > 
> > For now I've dropped the patch until this is resolved.
> > 
> > Thanks,
> > 
> > Jonathan
> > 
> >   

[RFC PATCH 3/7] iio:ABI docs: Drop device specific docs for _powerdown for the adf4371

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

The interface is standard and the extra info provided on exactly what is
being powered down is not of interest to most users.  Hence this doesn't
need it's own documentation and can rely on the docs in sysfs-bus-iio

Fixes:
$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:36  ./Documentation/ABI/testing/sysfs-bus-iio:588

Cc: Alexandru Ardelean <alexandru.ardelean@analog.com>
Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
index 544548ee794c..457f75903963 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
+++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
@@ -34,11 +34,3 @@ Description:
 		  out_altvoltage2_name: RF16x
 		  out_altvoltage3_name: RF32x
 
-What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown
-KernelVersion:
-Contact:	linux-iio@vger.kernel.org
-Description:
-		This attribute allows the user to power down the PLL and it's
-		RFOut buffers.
-		Writing 1 causes the specified channel to power down.
-		Clearing returns to normal operation.
-- 
2.30.0

Re: [RFC PATCH 3/7] iio:ABI docs: Drop device specific docs for _powerdown for the adf4371

[Jonathan Cameron]

On Sun, 17 Jan 2021 15:38:12 +0000
Jonathan Cameron <jic23@kernel.org> wrote:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> 
> The interface is standard and the extra info provided on exactly what is
> being powered down is not of interest to most users.  Hence this doesn't
> need it's own documentation and can rely on the docs in sysfs-bus-iio
> 
> Fixes:
> $ scripts/get_abi.pl validate
> Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:36  ./Documentation/ABI/testing/sysfs-bus-iio:588
> 
> Cc: Alexandru Ardelean <alexandru.ardelean@analog.com>
> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
I'm guessing I can't make a mistake removing docs :)

Applied to the togreg branch of iio.git and pushed out as testing for the
autobuilders to do nothing with it.

Thanks,

Jonathan

> ---
>  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 | 8 --------
>  1 file changed, 8 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
> index 544548ee794c..457f75903963 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
> @@ -34,11 +34,3 @@ Description:
>  		  out_altvoltage2_name: RF16x
>  		  out_altvoltage3_name: RF32x
>  
> -What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown
> -KernelVersion:
> -Contact:	linux-iio@vger.kernel.org
> -Description:
> -		This attribute allows the user to power down the PLL and it's
> -		RFOut buffers.
> -		Writing 1 causes the specified channel to power down.
> -		Clearing returns to normal operation.

[RFC PATCH 4/7] iio:ABI docs: Fix issue around repeated definition of out_currentY_raw

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

This one is challenging as both the places this appears in specific drivers
are making 'unusual' uses of what looks like a simple output current
channel.
As a side note, this was particular bit of ABI occurs in other drivers
where the use is much more straight forward e.g. dac/ad5421

This patch attempts to make a best effort of adding it to the main docs but
retaining enough information. Both of these drivers probably need
specific documents being written to describe their unusual interfaces, but
those should be in the main documentation, not under Documentation/ABI.
That is a non trivial job so left for another time.

Fixes:
$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als:43  ./Documentation/ABI/testing/sysfs-bus-iio-health-afe440x:38

Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 Documentation/ABI/testing/sysfs-bus-iio               | 11 +++++++++++
 .../ABI/testing/sysfs-bus-iio-health-afe440x          | 10 ++--------
 .../ABI/testing/sysfs-bus-iio-light-lm3533-als        | 11 +++--------
 3 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 9b5ceb22363d..ed50f4b21dcc 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -631,6 +631,17 @@ Description:
 		specified and unique if the output corresponds to a single
 		channel.
 
+What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
+Date:		May 2012
+KernelVersion:	3.5
+Contact:	Johan Hovold <jhovold@gmail.com>
+Description:
+		Set/get output current for channel Y. Units after application
+		of scale and offset are milliamps.
+		For some devices current channels are used to specify
+		current supplied to elements used in taking a measurement
+		of a different type. E.g. LED currents.
+
 What:		/sys/bus/iio/devices/iio:deviceX/events
 KernelVersion:	2.6.35
 Contact:	linux-iio@vger.kernel.org
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
index 66b621f10223..a8e04b41d9ff 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
+++ b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
@@ -18,6 +18,8 @@ Description:
 		respectively which simply helper channels containing the
 		calculated difference in the value of stage 1 - 2 and 3 - 4.
 		The values are expressed in 24-bit twos complement.
+		The LED current for the stage is controlled via
+		out_currentY_raw.
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_intensityY_offset
 Date:		May 2016
@@ -35,11 +37,3 @@ Contact:	Andrew F. Davis <afd@ti.com>
 Description:
 		Get and set the resistance and the capacitance settings for the
 		Transimpedance Amplifier during the associated stage.
-
-What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
-Date:		May 2016
-KernelVersion:
-Contact:	Andrew F. Davis <afd@ti.com>
-Description:
-		Get and set the LED current for the specified LED active during
-		this stage. Y is the specific stage number.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
index 22c5ea670971..c476d48d0f82 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
+++ b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
@@ -41,14 +41,6 @@ Description:
 		Get the current light zone (0..4) as defined by the
 		in_illuminance0_threshY_{falling,rising} thresholds.
 
-What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
-Date:		May 2012
-KernelVersion:	3.5
-Contact:	Johan Hovold <jhovold@gmail.com>
-Description:
-		Get output current for channel Y (0..255), that is,
-		out_currentY_currentZ_raw, where Z is the current zone.
-
 What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_currentZ_raw
 Date:		May 2012
 KernelVersion:	3.5
@@ -59,3 +51,6 @@ Description:
 
 		These values correspond to the ALS-mapper target registers for
 		ALS-mapper Y + 1.
+
+		Note that out_currentY_raw provides the current for the
+		current zone.
-- 
2.30.0

Re: [RFC PATCH 4/7] iio:ABI docs: Fix issue around repeated definition of out_currentY_raw

[Jonathan Cameron]

On Sun, 17 Jan 2021 15:38:13 +0000
Jonathan Cameron <jic23@kernel.org> wrote:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> 
> This one is challenging as both the places this appears in specific drivers
> are making 'unusual' uses of what looks like a simple output current
> channel.
> As a side note, this was particular bit of ABI occurs in other drivers
> where the use is much more straight forward e.g. dac/ad5421
> 
> This patch attempts to make a best effort of adding it to the main docs but
> retaining enough information. Both of these drivers probably need
> specific documents being written to describe their unusual interfaces, but
> those should be in the main documentation, not under Documentation/ABI.
> That is a non trivial job so left for another time.
> 
> Fixes:
> $ scripts/get_abi.pl validate
> Warning: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als:43  ./Documentation/ABI/testing/sysfs-bus-iio-health-afe440x:38
> 
> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Another one I think I can't have gotten wrong. Hence whilst I like to know
they've had eyes on them, I'll take this one anyway.

Applied to the togreg branch of iio.git and pushed out as testing.

Thanks,

Jonathan

> ---
>  Documentation/ABI/testing/sysfs-bus-iio               | 11 +++++++++++
>  .../ABI/testing/sysfs-bus-iio-health-afe440x          | 10 ++--------
>  .../ABI/testing/sysfs-bus-iio-light-lm3533-als        | 11 +++--------
>  3 files changed, 16 insertions(+), 16 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index 9b5ceb22363d..ed50f4b21dcc 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -631,6 +631,17 @@ Description:
>  		specified and unique if the output corresponds to a single
>  		channel.
>  
> +What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
> +Date:		May 2012
> +KernelVersion:	3.5
> +Contact:	Johan Hovold <jhovold@gmail.com>
> +Description:
> +		Set/get output current for channel Y. Units after application
> +		of scale and offset are milliamps.
> +		For some devices current channels are used to specify
> +		current supplied to elements used in taking a measurement
> +		of a different type. E.g. LED currents.
> +
>  What:		/sys/bus/iio/devices/iio:deviceX/events
>  KernelVersion:	2.6.35
>  Contact:	linux-iio@vger.kernel.org
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
> index 66b621f10223..a8e04b41d9ff 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
> @@ -18,6 +18,8 @@ Description:
>  		respectively which simply helper channels containing the
>  		calculated difference in the value of stage 1 - 2 and 3 - 4.
>  		The values are expressed in 24-bit twos complement.
> +		The LED current for the stage is controlled via
> +		out_currentY_raw.
>  
>  What:		/sys/bus/iio/devices/iio:deviceX/in_intensityY_offset
>  Date:		May 2016
> @@ -35,11 +37,3 @@ Contact:	Andrew F. Davis <afd@ti.com>
>  Description:
>  		Get and set the resistance and the capacitance settings for the
>  		Transimpedance Amplifier during the associated stage.
> -
> -What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
> -Date:		May 2016
> -KernelVersion:
> -Contact:	Andrew F. Davis <afd@ti.com>
> -Description:
> -		Get and set the LED current for the specified LED active during
> -		this stage. Y is the specific stage number.
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
> index 22c5ea670971..c476d48d0f82 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
> @@ -41,14 +41,6 @@ Description:
>  		Get the current light zone (0..4) as defined by the
>  		in_illuminance0_threshY_{falling,rising} thresholds.
>  
> -What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
> -Date:		May 2012
> -KernelVersion:	3.5
> -Contact:	Johan Hovold <jhovold@gmail.com>
> -Description:
> -		Get output current for channel Y (0..255), that is,
> -		out_currentY_currentZ_raw, where Z is the current zone.
> -
>  What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_currentZ_raw
>  Date:		May 2012
>  KernelVersion:	3.5
> @@ -59,3 +51,6 @@ Description:
>  
>  		These values correspond to the ALS-mapper target registers for
>  		ALS-mapper Y + 1.
> +
> +		Note that out_currentY_raw provides the current for the
> +		current zone.

[RFC PATCH 5/7] iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one file

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

These contain only one entry for out_current_heater_raw (_available).
Document this in a new sysfs-bus-iio-humidity file, and make it a little
more generic by allowing for non 0/1 values.

Fixes:
$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1

Cc: Eugene Zaikonnikov <ez@norphonic.com>
Cc: Matt Ranostay <matt.ranostay@konsulko.com>
Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 ...s-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} | 3 ++-
 Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x | 9 ---------
 2 files changed, 2 insertions(+), 10 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 b/Documentation/ABI/testing/sysfs-bus-iio-humidity
similarity index 79%
rename from Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
rename to Documentation/ABI/testing/sysfs-bus-iio-humidity
index 5b78af5f341d..cb0d7e75d297 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
+++ b/Documentation/ABI/testing/sysfs-bus-iio-humidity
@@ -6,4 +6,5 @@ Description:
 		Controls the heater device within the humidity sensor to get
 		rid of excess condensation.
 
-		Valid control values are 0 = OFF, and 1 = ON.
+		In some devices, this is just a switch in which case 0 = OFF,
+		and 1 = ON.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x b/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
deleted file mode 100644
index b72bb62552cf..000000000000
--- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
+++ /dev/null
@@ -1,9 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/out_current_heater_raw
-What:		/sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available
-KernelVersion:	4.3
-Contact:	linux-iio@vger.kernel.org
-Description:
-		Controls the heater device within the humidity sensor to get
-		rid of excess condensation.
-
-		Valid control values are 0 = OFF, and 1 = ON.
-- 
2.30.0

Re: [RFC PATCH 5/7] iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one file

[Matt Ranostay]

On Sun, Jan 17, 2021 at 7:40 AM Jonathan Cameron <jic23@kernel.org> wrote:
>
> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
>
> These contain only one entry for out_current_heater_raw (_available).
> Document this in a new sysfs-bus-iio-humidity file, and make it a little
> more generic by allowing for non 0/1 values.
>
> Fixes:
> $ scripts/get_abi.pl validate
> Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
> Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
>
> Cc: Eugene Zaikonnikov <ez@norphonic.com>
> Cc: Matt Ranostay <matt.ranostay@konsulko.com>
> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Reviewed-by: Matt Ranostay <matt.ranostay@konsulko.com>

> ---
>  ...s-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} | 3 ++-
>  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x | 9 ---------
>  2 files changed, 2 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 b/Documentation/ABI/testing/sysfs-bus-iio-humidity
> similarity index 79%
> rename from Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
> rename to Documentation/ABI/testing/sysfs-bus-iio-humidity
> index 5b78af5f341d..cb0d7e75d297 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-humidity
> @@ -6,4 +6,5 @@ Description:
>                 Controls the heater device within the humidity sensor to get
>                 rid of excess condensation.
>
> -               Valid control values are 0 = OFF, and 1 = ON.
> +               In some devices, this is just a switch in which case 0 = OFF,
> +               and 1 = ON.
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x b/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
> deleted file mode 100644
> index b72bb62552cf..000000000000
> --- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
> +++ /dev/null
> @@ -1,9 +0,0 @@
> -What:          /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw
> -What:          /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available
> -KernelVersion: 4.3
> -Contact:       linux-iio@vger.kernel.org
> -Description:
> -               Controls the heater device within the humidity sensor to get
> -               rid of excess condensation.
> -
> -               Valid control values are 0 = OFF, and 1 = ON.
> --
> 2.30.0
>

Re: [RFC PATCH 5/7] iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one file

[Jonathan Cameron]

On Sun, 17 Jan 2021 15:12:40 -0800
Matt Ranostay <matt.ranostay@konsulko.com> wrote:

> On Sun, Jan 17, 2021 at 7:40 AM Jonathan Cameron <jic23@kernel.org> wrote:
> >
> > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> >
> > These contain only one entry for out_current_heater_raw (_available).
> > Document this in a new sysfs-bus-iio-humidity file, and make it a little
> > more generic by allowing for non 0/1 values.
> >
> > Fixes:
> > $ scripts/get_abi.pl validate
> > Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
> > Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
> >
> > Cc: Eugene Zaikonnikov <ez@norphonic.com>
> > Cc: Matt Ranostay <matt.ranostay@konsulko.com>
> > Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>  
> 
> Reviewed-by: Matt Ranostay <matt.ranostay@konsulko.com>
Applied, thanks

J
> 
> > ---
> >  ...s-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} | 3 ++-
> >  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x | 9 ---------
> >  2 files changed, 2 insertions(+), 10 deletions(-)
> >
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 b/Documentation/ABI/testing/sysfs-bus-iio-humidity
> > similarity index 79%
> > rename from Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
> > rename to Documentation/ABI/testing/sysfs-bus-iio-humidity
> > index 5b78af5f341d..cb0d7e75d297 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio-humidity
> > @@ -6,4 +6,5 @@ Description:
> >                 Controls the heater device within the humidity sensor to get
> >                 rid of excess condensation.
> >
> > -               Valid control values are 0 = OFF, and 1 = ON.
> > +               In some devices, this is just a switch in which case 0 = OFF,
> > +               and 1 = ON.
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x b/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
> > deleted file mode 100644
> > index b72bb62552cf..000000000000
> > --- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
> > +++ /dev/null
> > @@ -1,9 +0,0 @@
> > -What:          /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw
> > -What:          /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available
> > -KernelVersion: 4.3
> > -Contact:       linux-iio@vger.kernel.org
> > -Description:
> > -               Controls the heater device within the humidity sensor to get
> > -               rid of excess condensation.
> > -
> > -               Valid control values are 0 = OFF, and 1 = ON.
> > --
> > 2.30.0
> >  

[RFC PATCH 6/7] iio:ABI docs: Combine the two instances of docs for sensor_sensitivity

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

This control on the gain of a measurement used for time of flight sensing
is standard but the expected values for different enviroments may not be.
As we cannot have the same ABI element documented in two files, add a
generic version to sysfs-bus-iio-proximity and a note on the expected
value vs measuring environment for the as3935.

Fixes:
$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  ./Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8

Cc: Matt Ranostay <matt.ranostay@konsulko.com>
Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 .../ABI/testing/sysfs-bus-iio-distance-srf08       |  8 --------
 Documentation/ABI/testing/sysfs-bus-iio-proximity  | 14 ++++++++++++++
 .../ABI/testing/sysfs-bus-iio-proximity-as3935     |  9 ---------
 3 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
index 40df5c9fef99..9dae94aa880b 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
+++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
@@ -1,11 +1,3 @@
-What:		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
-Date:		January 2017
-KernelVersion:	4.11
-Contact:	linux-iio@vger.kernel.org
-Description:
-		Show or set the gain boost of the amp, from 0-31 range.
-		default 31
-
 What:		/sys/bus/iio/devices/iio:deviceX/sensor_max_range
 Date:		January 2017
 KernelVersion:	4.11
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity b/Documentation/ABI/testing/sysfs-bus-iio-proximity
index 2172f3bb9c64..3aac6dab8775 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-proximity
+++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity
@@ -8,3 +8,17 @@ Description:
 		considered close to the device. If the value read from the
 		sensor is above or equal to the value in this file an object
 		should typically be considered near.
+
+What:		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
+Date:		March 2014
+KernelVersion:	3.15
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Proximity sensors sometimes have a controllable amplifier
+		on the signal from which time of flight measurements are
+		taken.
+		The appropriate values to take is dependent on both the
+		sensor and it's operating environment:
+		* as3935 (0-31 range)
+		18 = indoors (default)
+		14 = outdoors
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
index c59d95346341..1e5c40775a6c 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
+++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
@@ -6,15 +6,6 @@ Description:
 		Get the current distance in meters of storm (1km steps)
 		1000-40000 = distance in meters
 
-What:		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
-Date:		March 2014
-KernelVersion:	3.15
-Contact:	Matt Ranostay <matt.ranostay@konsulko.com>
-Description:
-		Show or set the gain boost of the amp, from 0-31 range.
-		18 = indoors (default)
-		14 = outdoors
-
 What		/sys/bus/iio/devices/iio:deviceX/noise_level_tripped
 Date:		May 2017
 KernelVersion:	4.13
-- 
2.30.0

Re: [RFC PATCH 6/7] iio:ABI docs: Combine the two instances of docs for sensor_sensitivity

[Matt Ranostay]

On Sun, Jan 17, 2021 at 7:40 AM Jonathan Cameron <jic23@kernel.org> wrote:
>
> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
>
> This control on the gain of a measurement used for time of flight sensing
> is standard but the expected values for different enviroments may not be.
> As we cannot have the same ABI element documented in two files, add a
> generic version to sysfs-bus-iio-proximity and a note on the expected
> value vs measuring environment for the as3935.
>
> Fixes:
> $ scripts/get_abi.pl validate
> Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  ./Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
>
> Cc: Matt Ranostay <matt.ranostay@konsulko.com>
> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Reviewed-by: Matt Ranostay <matt.ranostay@konsulko.com>

> ---
>  .../ABI/testing/sysfs-bus-iio-distance-srf08       |  8 --------
>  Documentation/ABI/testing/sysfs-bus-iio-proximity  | 14 ++++++++++++++
>  .../ABI/testing/sysfs-bus-iio-proximity-as3935     |  9 ---------
>  3 files changed, 14 insertions(+), 17 deletions(-)
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
> index 40df5c9fef99..9dae94aa880b 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
> @@ -1,11 +1,3 @@
> -What:          /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
> -Date:          January 2017
> -KernelVersion: 4.11
> -Contact:       linux-iio@vger.kernel.org
> -Description:
> -               Show or set the gain boost of the amp, from 0-31 range.
> -               default 31
> -
>  What:          /sys/bus/iio/devices/iio:deviceX/sensor_max_range
>  Date:          January 2017
>  KernelVersion: 4.11
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity b/Documentation/ABI/testing/sysfs-bus-iio-proximity
> index 2172f3bb9c64..3aac6dab8775 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity
> @@ -8,3 +8,17 @@ Description:
>                 considered close to the device. If the value read from the
>                 sensor is above or equal to the value in this file an object
>                 should typically be considered near.
> +
> +What:          /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
> +Date:          March 2014
> +KernelVersion: 3.15
> +Contact:       linux-iio@vger.kernel.org
> +Description:
> +               Proximity sensors sometimes have a controllable amplifier
> +               on the signal from which time of flight measurements are
> +               taken.
> +               The appropriate values to take is dependent on both the
> +               sensor and it's operating environment:
> +               * as3935 (0-31 range)
> +               18 = indoors (default)
> +               14 = outdoors
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
> index c59d95346341..1e5c40775a6c 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
> @@ -6,15 +6,6 @@ Description:
>                 Get the current distance in meters of storm (1km steps)
>                 1000-40000 = distance in meters
>
> -What:          /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
> -Date:          March 2014
> -KernelVersion: 3.15
> -Contact:       Matt Ranostay <matt.ranostay@konsulko.com>
> -Description:
> -               Show or set the gain boost of the amp, from 0-31 range.
> -               18 = indoors (default)
> -               14 = outdoors
> -
>  What           /sys/bus/iio/devices/iio:deviceX/noise_level_tripped
>  Date:          May 2017
>  KernelVersion: 4.13
> --
> 2.30.0
>

[RFC PATCH 7/7] iio:ABI docs: Move specific description of out_altvoltageX_frequency to main docs.

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

The adf4371 has channels that are very closely coupled, so additional
documentation is needed to express these constraints.
Unfortunately having the same sysfs filename in multiple documentation
does not work well when generating automated documentation.
To avoid this issue, we add a new device specific description to the
main docs and remove the one in the device specific file.

Fixes:
$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:0  ./Documentation/ABI/testing/sysfs-bus-iio:599

Cc: Alexandru Ardelean <alexandru.ardelean@analog.com>
Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 Documentation/ABI/testing/sysfs-bus-iio       | 19 ++++++++++++++
 .../testing/sysfs-bus-iio-frequency-adf4371   | 25 -------------------
 2 files changed, 19 insertions(+), 25 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index ed50f4b21dcc..515c4290d43d 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -620,6 +620,25 @@ Description:
 		Output frequency for channel Y in Hz. The number must always be
 		specified and unique if the output corresponds to a single
 		channel.
+		Some drivers have additional constraints:
+		ADF4371 has an integrated VCO with fundamendal output
+		frequency ranging from 4000000000 Hz 8000000000 Hz.
+
+		out_altvoltage0_frequency:
+			A divide by 1, 2, 4, 8, 16, 32 or circuit generates
+			frequencies from 62500000 Hz to 8000000000 Hz.
+		out_altvoltage1_frequency:
+			This channel duplicates the channel 0 frequency
+		out_altvoltage2_frequency:
+			A frequency doubler generates frequencies from
+			8000000000 Hz to 16000000000 Hz.
+		out_altvoltage3_frequency:
+			A frequency quadrupler generates frequencies from
+			16000000000 Hz to 32000000000 Hz.
+
+		Note: writes to one of the channels will affect the frequency of
+		all the other channels, since it involves changing the VCO
+		fundamental output frequency.
 
 What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_phase
 KernelVersion:	3.4.0
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
index 457f75903963..7fe6935d1448 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
+++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
@@ -1,28 +1,3 @@
-What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
-KernelVersion:
-Contact:	linux-iio@vger.kernel.org
-Description:
-		Stores the PLL frequency in Hz for channel Y.
-		Reading returns the actual frequency in Hz.
-		The ADF4371 has an integrated VCO with fundamendal output
-		frequency ranging from 4000000000 Hz 8000000000 Hz.
-
-		out_altvoltage0_frequency:
-			A divide by 1, 2, 4, 8, 16, 32 or circuit generates
-			frequencies from 62500000 Hz to 8000000000 Hz.
-		out_altvoltage1_frequency:
-			This channel duplicates the channel 0 frequency
-		out_altvoltage2_frequency:
-			A frequency doubler generates frequencies from
-			8000000000 Hz to 16000000000 Hz.
-		out_altvoltage3_frequency:
-			A frequency quadrupler generates frequencies from
-			16000000000 Hz to 32000000000 Hz.
-
-		Note: writes to one of the channels will affect the frequency of
-		all the other channels, since it involves changing the VCO
-		fundamental output frequency.
-
 What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name
 KernelVersion:
 Contact:	linux-iio@vger.kernel.org
-- 
2.30.0

Re: [RFC PATCH 7/7] iio:ABI docs: Move specific description of out_altvoltageX_frequency to main docs.

[Jonathan Cameron]

On Sun, 17 Jan 2021 15:38:16 +0000
Jonathan Cameron <jic23@kernel.org> wrote:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> 
> The adf4371 has channels that are very closely coupled, so additional
> documentation is needed to express these constraints.
> Unfortunately having the same sysfs filename in multiple documentation
> does not work well when generating automated documentation.
> To avoid this issue, we add a new device specific description to the
> main docs and remove the one in the device specific file.
> 
> Fixes:
> $ scripts/get_abi.pl validate
> Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:0  ./Documentation/ABI/testing/sysfs-bus-iio:599
> 
> Cc: Alexandru Ardelean <alexandru.ardelean@analog.com>
> Reported-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Applied.

Thanks,

Jonathan

> ---
>  Documentation/ABI/testing/sysfs-bus-iio       | 19 ++++++++++++++
>  .../testing/sysfs-bus-iio-frequency-adf4371   | 25 -------------------
>  2 files changed, 19 insertions(+), 25 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index ed50f4b21dcc..515c4290d43d 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -620,6 +620,25 @@ Description:
>  		Output frequency for channel Y in Hz. The number must always be
>  		specified and unique if the output corresponds to a single
>  		channel.
> +		Some drivers have additional constraints:
> +		ADF4371 has an integrated VCO with fundamendal output
> +		frequency ranging from 4000000000 Hz 8000000000 Hz.
> +
> +		out_altvoltage0_frequency:
> +			A divide by 1, 2, 4, 8, 16, 32 or circuit generates
> +			frequencies from 62500000 Hz to 8000000000 Hz.
> +		out_altvoltage1_frequency:
> +			This channel duplicates the channel 0 frequency
> +		out_altvoltage2_frequency:
> +			A frequency doubler generates frequencies from
> +			8000000000 Hz to 16000000000 Hz.
> +		out_altvoltage3_frequency:
> +			A frequency quadrupler generates frequencies from
> +			16000000000 Hz to 32000000000 Hz.
> +
> +		Note: writes to one of the channels will affect the frequency of
> +		all the other channels, since it involves changing the VCO
> +		fundamental output frequency.
>  
>  What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_phase
>  KernelVersion:	3.4.0
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
> index 457f75903963..7fe6935d1448 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
> @@ -1,28 +1,3 @@
> -What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
> -KernelVersion:
> -Contact:	linux-iio@vger.kernel.org
> -Description:
> -		Stores the PLL frequency in Hz for channel Y.
> -		Reading returns the actual frequency in Hz.
> -		The ADF4371 has an integrated VCO with fundamendal output
> -		frequency ranging from 4000000000 Hz 8000000000 Hz.
> -
> -		out_altvoltage0_frequency:
> -			A divide by 1, 2, 4, 8, 16, 32 or circuit generates
> -			frequencies from 62500000 Hz to 8000000000 Hz.
> -		out_altvoltage1_frequency:
> -			This channel duplicates the channel 0 frequency
> -		out_altvoltage2_frequency:
> -			A frequency doubler generates frequencies from
> -			8000000000 Hz to 16000000000 Hz.
> -		out_altvoltage3_frequency:
> -			A frequency quadrupler generates frequencies from
> -			16000000000 Hz to 32000000000 Hz.
> -
> -		Note: writes to one of the channels will affect the frequency of
> -		all the other channels, since it involves changing the VCO
> -		fundamental output frequency.
> -
>  What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name
>  KernelVersion:
>  Contact:	linux-iio@vger.kernel.org

Re: [RFC PATCH 0/7] IIO ABI documentation duplication fixes

[Jonathan Cameron]

On Sun, 17 Jan 2021 15:38:09 +0000
Jonathan Cameron <jic23@kernel.org> wrote:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Hi All,

Suffering from "maintainer's" curse on these of there being no one I can
generically moan at over lack of reviews :)   If someone could just
cast their eyes over patches 1, 3, 4 and 7 to check I haven't done anything
exceedingly stupid that would be great.

Thanks,

Jonathan

> 
> The nature of IIO devices is that they are highly varied and occaisonly
> ABI is used in somewhat of a 'best fit' fashion.  This has lead to a
> situation where we had additional more specific ABI docs for some sysfs
> parameters in certain drivers.  Unfortunately the automated documentation
> building doesn't work well with this both issuing warnings and building
> a less than ideal output.
> 
> So this series attempts to fix that up, mostly by moving the application
> specific parts, of properties that are documented in more than one place,
> into a higher level documentation file, sometimes with a device specific
> note. In a few cases this the result is a bit non-obvious hence the RFC.
> Roughly speaking I've put the more 'interesting' cases towards the end
> of the series.
> 
> It's worth noting that a general reorganzation, audit of missing docs
> etc is needed for the IIO ABI docs, but as that's a big job it may well
> take sometime to get it done. In the meantime let's deal with these
> issues.  Some of the drivers have complex enough ABI that we should probably
> have detailed docs for them in addition to Documentation/ABI.
> 
> Note I haven't yet touched the remaining case of
> Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_preset is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:100  ./Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
> Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  ./Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8
> 
> This is mainly because I don't really know enough about these devices
> to conclude exactly what a fused bit of docs should look like.
> Also worth noting that those are probably deprecated ABI anyway given
> the move of counters into their own subsystem.
> 
> Jonathan Cameron (7):
>   iio:ABI docs: Fix up duplicate *_calibbias_* documentation for
>     icm42600
>   iio:ABI docs: Avoid repitition of triggerX/sampling_frequency
>   iio:ABI docs: Drop device specific docs for _powerdown for the adf4371
>   iio:ABI docs: Fix issue around repeated definition of out_currentY_raw
>   iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one
>     file
>   iio:ABI docs: Combine the two instances of docs for sensor_sensitivity
>   iio:ABI docs: Move specific description of out_altvoltageX_frequency
>     to main docs.
> 
>  Documentation/ABI/testing/sysfs-bus-iio       | 45 +++++++++++++++++++
>  .../ABI/testing/sysfs-bus-iio-distance-srf08  |  8 ----
>  .../testing/sysfs-bus-iio-frequency-adf4371   | 33 --------------
>  .../ABI/testing/sysfs-bus-iio-health-afe440x  | 10 +----
>  ...umidity-hdc2010 => sysfs-bus-iio-humidity} |  3 +-
>  .../testing/sysfs-bus-iio-humidity-hdc100x    |  9 ----
>  .../ABI/testing/sysfs-bus-iio-icm42600        | 20 ---------
>  .../testing/sysfs-bus-iio-light-lm3533-als    | 11 ++---
>  .../ABI/testing/sysfs-bus-iio-proximity       | 14 ++++++
>  .../testing/sysfs-bus-iio-proximity-as3935    |  9 ----
>  .../ABI/testing/sysfs-bus-iio-timer-stm32     |  8 ----
>  11 files changed, 66 insertions(+), 104 deletions(-)
>  rename Documentation/ABI/testing/{sysfs-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} (79%)
>  delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
>  delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-icm42600
>