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

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

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