[3/4] Documentation: ABI: testing: adf4377: add ABI docs

Message ID 20221104092802.90725-4-antoniu.miclaus@analog.com
State New
Headers
Series Add support for ADF4377 |

Commit Message

Antoniu Miclaus Nov. 4, 2022, 9:28 a.m. UTC
  Add documentation for the use of the output frequency and muxout select.

Signed-off-by: Antoniu Miclaus <antoniu.miclaus@analog.com>
---
 .../testing/sysfs-bus-iio-frequency-adf4377   | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4377
  

Comments

Jonathan Cameron Nov. 6, 2022, 5:58 p.m. UTC | #1
On Fri, 4 Nov 2022 11:28:01 +0200
Antoniu Miclaus <antoniu.miclaus@analog.com> wrote:

> Add documentation for the use of the output frequency and muxout select.
> 
> Signed-off-by: Antoniu Miclaus <antoniu.miclaus@analog.com>
Hi Antoniu,

A few questions inline.
> ---
>  .../testing/sysfs-bus-iio-frequency-adf4377   | 32 +++++++++++++++++++
>  1 file changed, 32 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4377
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4377 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4377
> new file mode 100644
> index 000000000000..0324de5c9328
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4377
> @@ -0,0 +1,32 @@
> +What:		/sys/bus/iio/devices/iio:deviceX/frequency
> +KernelVersion:
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Stores the PLL frequency in Hz for output channels.
> +		Reading returns the frequency in Hz.

I'm a little confused. Should we not tie this to the output channels?
out_altvoltageX_frequency

> +
> +What:		/sys/bus/iio/devices/iio:deviceX/muxout_select

Why would userspace change this? 
I'd sort of expect this to typically be chosen by what it is physically wired
up to.

You could treat muxout_low and muxout_high as a gpio (possibly high_z as well).
If that were the case, then device tree binding should allow you detect that usecase.

Lock detector is normally wired to a GPI so that software can check if the lock is
successful (or it's wired to some other circuits we can't see).  The two
clock dividers should be represented as a clock provider.

Note this is partly driven by my desire to keep custom ABI to the minimum because
it is rare that userspace has a clue what to do with it.  That is probably less
of a consideration here though as I doubt this device is going to be much used
with software stacks that don't know exactly what it is.

Jonathan

> +KernelVersion:
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		The mux output allows the user to access various internal points on
> +		the chip. Valid values that can be written are:
> +		* high_z -> high impedance output
> +		* lock_detect -> digital lock detector output
> +		* muxout_low -> low output
> +		* f_div_rclk_2 -> fdiv_rclk/2
> +		* f_div_nclk_2 -> fdiv_nclk/2
> +		* muxout_high -> high output
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/muxout_select_available
> +KernelVersion:
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Reading this returns the valid values that can be written to the
> +		muxout_mode attribute:
> +		* high_z
> +		* lock_detect
> +		* muxout_low
> +		* f_div_rclk_2
> +		* f_div_nclk_2
> +		* muxout_high
  

Patch

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4377 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4377
new file mode 100644
index 000000000000..0324de5c9328
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4377
@@ -0,0 +1,32 @@ 
+What:		/sys/bus/iio/devices/iio:deviceX/frequency
+KernelVersion:
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Stores the PLL frequency in Hz for output channels.
+		Reading returns the frequency in Hz.
+
+What:		/sys/bus/iio/devices/iio:deviceX/muxout_select
+KernelVersion:
+Contact:	linux-iio@vger.kernel.org
+Description:
+		The mux output allows the user to access various internal points on
+		the chip. Valid values that can be written are:
+		* high_z -> high impedance output
+		* lock_detect -> digital lock detector output
+		* muxout_low -> low output
+		* f_div_rclk_2 -> fdiv_rclk/2
+		* f_div_nclk_2 -> fdiv_nclk/2
+		* muxout_high -> high output
+
+What:		/sys/bus/iio/devices/iio:deviceX/muxout_select_available
+KernelVersion:
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Reading this returns the valid values that can be written to the
+		muxout_mode attribute:
+		* high_z
+		* lock_detect
+		* muxout_low
+		* f_div_rclk_2
+		* f_div_nclk_2
+		* muxout_high