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

[Jonathan Cameron <jic23@jic23.retrosnub.co.uk>]

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.