diff mbox series

[1/4] docs: iio: add documentation for ad3552r driver

Message ID 20250321-wip-bl-ad3552r-fixes-v1-1-3c1aa249d163@baylibre.com (mailing list archive)
State Changes Requested
Headers show
Series iio: ad3552r-hs: add support for internal ramp generator | expand

Commit Message

Angelo Dureghello March 21, 2025, 8:28 p.m. UTC 
From: Angelo Dureghello <adureghello@baylibre.com>

Add documentation for ad3552r driver, needed to describe the high-speed
driver debugfs attributes and shows how the user may use them.

Signed-off-by: Angelo Dureghello <adureghello@baylibre.com>
---
 Documentation/iio/ad3552r.rst | 65 +++++++++++++++++++++++++++++++++++++++++++
 Documentation/iio/index.rst   |  1 +
 MAINTAINERS                   |  1 +
 3 files changed, 67 insertions(+)

Comments

Marcelo Schmitt March 26, 2025, 10:28 p.m. UTC | #1 
The doc seems to be all about the high-speed setup despite classical SPI support
being mentioned. It would be interesting to see how the regular SPI and hs
ad3552r IIO devices differ from each other (wiring connections, IIO device
interfaces (attributes, debug files, ...), any other relevant peculiarities).
Some comments about that inline.

On 03/21, Angelo Dureghello wrote:
> From: Angelo Dureghello <adureghello@baylibre.com>
> 
> Add documentation for ad3552r driver, needed to describe the high-speed
> driver debugfs attributes and shows how the user may use them.
> 
> Signed-off-by: Angelo Dureghello <adureghello@baylibre.com>
> ---
...
> +==============
> +AD3552R driver
> +==============
> +
> +Device driver for Analog Devices Inc. AD35XXR series of DACs. The module name
> +is ``ad3552r``.
> +With the same module name, two different driver variants are available, the
> +``generic spi`` variant, to be used with any classic SPI controllers, and the
> +``hs`` (high speed) variant, for an ADI ``axi-dac`` (IP core) based controller
> +that allows to reach the maximum sample rate supported from the DACs, using the
> +DMA transfer and all the SPI lines available (D/QDSPI)..
Is D/QDSPI about dual and quad SPI? If so, what about saying that more clearly? 

> +The high speed driver variant is intended to be used with the ``adi-axi-dac``
> +backend support enabled, that is enabled by default when the driver is selected.
> +
> +Supported devices
> +=================
> +
> +* `AD3541R <https://www.analog.com/en/products/ad3541r.html>`_
> +* `AD3542R <https://www.analog.com/en/products/ad3542r.html>`_
> +* `AD3551R <https://www.analog.com/en/products/ad3551r.html>`_
> +* `AD3552R <https://www.analog.com/en/products/ad3552r.html>`_
> +
> +Wiring connections
> +------------------
> +
> +::
> +
> +    .-----------------.                .-------.
> +    |                 |--- D/QSPI -----|       |
> +    |   DAC IP CORE   |--- SPI S_CLK --|  DAC  |
> +    |                 |--- SPI CS -----|       |
> +    |                 |--- LDAC -------|       |
> +    |                 |--- RESET ------|       |
> +    |_________________|                |_______|

This only describes how the HDL IP connects to the DAC which is the high speed
use case. Maybe add a diagram for the regular SPI connection wiring or say that
the above is only for the hs setup?
Also, what about adding a link to the HDL documentation page?
https://analogdevicesinc.github.io/hdl/projects/ad35xxr_evb/index.html

> +
> +
> +High speed features
> +===================
> +
> +Device attributes
> +-----------------
This is only describing the debugfs file. What about also listing the usual
IIO device channels and attributes (out_voltageX_raw, out_voltageX_en, ...)?

> +
> +The following table shows the ad35xxr related device debug files, found in the
> +specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.
> +
> ++----------------------+-------------------------------------------------------+
> +| Debugfs device files | Description                                           |
> ++----------------------+-------------------------------------------------------+
> +| data_source          | The used data source,                                 |
> +|                      | as ``iio-buffer`` or ``backend-ramp-generator``.      |
> ++----------------------+-------------------------------------------------------+
> +
Angelo Dureghello March 27, 2025, 8:52 a.m. UTC | #2 
Hi Marcelo,

On 26.03.2025 19:28, Marcelo Schmitt wrote:
> The doc seems to be all about the high-speed setup despite classical SPI support
> being mentioned. It would be interesting to see how the regular SPI and hs
> ad3552r IIO devices differ from each other (wiring connections, IIO device
> interfaces (attributes, debug files, ...), any other relevant peculiarities).
> Some comments about that inline.
> 

had to add this file mainly to describe ramp generator usage.

The ad3552r (classic SPI) is quite old stuff, may work with whatever
controller with classic simple SPI (SDI/SDO/S_CLK/CS) so no particular
wiring diagram or explainations should be needed. 

> On 03/21, Angelo Dureghello wrote:
> > From: Angelo Dureghello <adureghello@baylibre.com>
> > 
> > Add documentation for ad3552r driver, needed to describe the high-speed
> > driver debugfs attributes and shows how the user may use them.
> > 
> > Signed-off-by: Angelo Dureghello <adureghello@baylibre.com>
> > ---
> ...
> > +==============
> > +AD3552R driver
> > +==============
> > +
> > +Device driver for Analog Devices Inc. AD35XXR series of DACs. The module name
> > +is ``ad3552r``.
> > +With the same module name, two different driver variants are available, the
> > +``generic spi`` variant, to be used with any classic SPI controllers, and the
> > +``hs`` (high speed) variant, for an ADI ``axi-dac`` (IP core) based controller
> > +that allows to reach the maximum sample rate supported from the DACs, using the
> > +DMA transfer and all the SPI lines available (D/QDSPI)..
> Is D/QDSPI about dual and quad SPI? If so, what about saying that more clearly? 
> 
> > +The high speed driver variant is intended to be used with the ``adi-axi-dac``
> > +backend support enabled, that is enabled by default when the driver is selected.
> > +
> > +Supported devices
> > +=================
> > +
> > +* `AD3541R <https://www.analog.com/en/products/ad3541r.html>`_
> > +* `AD3542R <https://www.analog.com/en/products/ad3542r.html>`_
> > +* `AD3551R <https://www.analog.com/en/products/ad3551r.html>`_
> > +* `AD3552R <https://www.analog.com/en/products/ad3552r.html>`_
> > +
> > +Wiring connections
> > +------------------
> > +
> > +::
> > +
> > +    .-----------------.                .-------.
> > +    |                 |--- D/QSPI -----|       |
> > +    |   DAC IP CORE   |--- SPI S_CLK --|  DAC  |
> > +    |                 |--- SPI CS -----|       |
> > +    |                 |--- LDAC -------|       |
> > +    |                 |--- RESET ------|       |
> > +    |_________________|                |_______|
> 
> This only describes how the HDL IP connects to the DAC which is the high speed
> use case. Maybe add a diagram for the regular SPI connection wiring or say that
> the above is only for the hs setup?
> Also, what about adding a link to the HDL documentation page?
> https://analogdevicesinc.github.io/hdl/projects/ad35xxr_evb/index.html
> 
> > +
> > +
> > +High speed features
> > +===================
> > +
> > +Device attributes
> > +-----------------
> This is only describing the debugfs file. What about also listing the usual
> IIO device channels and attributes (out_voltageX_raw, out_voltageX_en, ...)?
> 

they are already documented, since part of the iio stuff.
Please see Documentation/ABI/testing/sysfs-bus-iio.

> > +
> > +The following table shows the ad35xxr related device debug files, found in the
> > +specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.
> > +
> > ++----------------------+-------------------------------------------------------+
> > +| Debugfs device files | Description                                           |
> > ++----------------------+-------------------------------------------------------+
> > +| data_source          | The used data source,                                 |
> > +|                      | as ``iio-buffer`` or ``backend-ramp-generator``.      |
> > ++----------------------+-------------------------------------------------------+
> > +

Reagrds,
angelo
Marcelo Schmitt March 27, 2025, 12:54 p.m. UTC | #3 
Hi Angelo,

On 03/27, Angelo Dureghello wrote:
> Hi Marcelo,
> 
> On 26.03.2025 19:28, Marcelo Schmitt wrote:
> > The doc seems to be all about the high-speed setup despite classical SPI support
> > being mentioned. It would be interesting to see how the regular SPI and hs
> > ad3552r IIO devices differ from each other (wiring connections, IIO device
> > interfaces (attributes, debug files, ...), any other relevant peculiarities).
> > Some comments about that inline.
> > 
> 
> had to add this file mainly to describe ramp generator usage.
> 
> The ad3552r (classic SPI) is quite old stuff, may work with whatever
> controller with classic simple SPI (SDI/SDO/S_CLK/CS) so no particular
> wiring diagram or explainations should be needed. 
> 
Okay, then maybe say so in the doc too. Otherwise this looks like a doc about
ad3552r driver that is said to support both SPI and hs SPI setups, but only
info about hs SPI is provided.

> > On 03/21, Angelo Dureghello wrote:
> > > From: Angelo Dureghello <adureghello@baylibre.com>
> > > 
> > > Add documentation for ad3552r driver, needed to describe the high-speed
> > > driver debugfs attributes and shows how the user may use them.
> > > 
> > > Signed-off-by: Angelo Dureghello <adureghello@baylibre.com>
> > > ---
...
> > > +High speed features
> > > +===================
> > > +
> > > +Device attributes
> > > +-----------------
> > This is only describing the debugfs file. What about also listing the usual
> > IIO device channels and attributes (out_voltageX_raw, out_voltageX_en, ...)?
> > 
> 
> they are already documented, since part of the iio stuff.
> Please see Documentation/ABI/testing/sysfs-bus-iio.

Agree, the sysfs interface we often refer to as device attributes is documented
in sysfs-bus-iio. Though, some of the docs for other IIO drivers complement the
ABI doc by elaborating on the regular sysfs interface they provide. If there
would be anything else to say about AD3552R interface, it could be added here.
Anyway, I think it's also fine to only have the debugfs if there is nothing
special about the other sysfs files.

Regards,
Marcelo
Jonathan Cameron March 30, 2025, 4:50 p.m. UTC | #4 
On Fri, 21 Mar 2025 21:28:48 +0100
Angelo Dureghello <adureghello@baylibre.com> wrote:

> From: Angelo Dureghello <adureghello@baylibre.com>
> 
> Add documentation for ad3552r driver, needed to describe the high-speed
> driver debugfs attributes and shows how the user may use them.
> 
> Signed-off-by: Angelo Dureghello <adureghello@baylibre.com>
> ---
>  Documentation/iio/ad3552r.rst | 65 +++++++++++++++++++++++++++++++++++++++++++
>  Documentation/iio/index.rst   |  1 +
>  MAINTAINERS                   |  1 +
>  3 files changed, 67 insertions(+)
> 
> diff --git a/Documentation/iio/ad3552r.rst b/Documentation/iio/ad3552r.rst
> new file mode 100644
> index 0000000000000000000000000000000000000000..638a62c99fb876cca026a0b1df469c81ba39ff29
> --- /dev/null
> +++ b/Documentation/iio/ad3552r.rst
> @@ -0,0 +1,65 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +==============
> +AD3552R driver
> +==============
> +
> +Device driver for Analog Devices Inc. AD35XXR series of DACs. The module name
> +is ``ad3552r``.
> +With the same module name, two different driver variants are available, the
> +``generic spi`` variant, to be used with any classic SPI controllers, and the
> +``hs`` (high speed) variant, for an ADI ``axi-dac`` (IP core) based controller
> +that allows to reach the maximum sample rate supported from the DACs, using the
> +DMA transfer and all the SPI lines available (D/QDSPI)..
> +The high speed driver variant is intended to be used with the ``adi-axi-dac``
> +backend support enabled, that is enabled by default when the driver is selected.
> +
> +Supported devices
> +=================
> +
> +* `AD3541R <https://www.analog.com/en/products/ad3541r.html>`_
> +* `AD3542R <https://www.analog.com/en/products/ad3542r.html>`_
> +* `AD3551R <https://www.analog.com/en/products/ad3551r.html>`_
> +* `AD3552R <https://www.analog.com/en/products/ad3552r.html>`_
> +
> +Wiring connections
> +------------------
> +
> +::
> +
> +    .-----------------.                .-------.
> +    |                 |--- D/QSPI -----|       |
> +    |   DAC IP CORE   |--- SPI S_CLK --|  DAC  |
> +    |                 |--- SPI CS -----|       |
> +    |                 |--- LDAC -------|       |
> +    |                 |--- RESET ------|       |
> +    |_________________|                |_______|
> +
> +
> +High speed features
> +===================
> +
> +Device attributes
> +-----------------
> +
> +The following table shows the ad35xxr related device debug files, found in the
> +specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.
> +
> ++----------------------+-------------------------------------------------------+
> +| Debugfs device files | Description                                           |
> ++----------------------+-------------------------------------------------------+
> +| data_source          | The used data source,                                 |
> +|                      | as ``iio-buffer`` or ``backend-ramp-generator``.      |
> ++----------------------+-------------------------------------------------------+
Hmm. I'm not convinced yet that this is something that belongs in debugfs but will
read on through the series.

> +
> +Usage examples
> +--------------
> +
> +. code-block:: bash
> +	root:/sys/bus/iio/devices/iio:device0# cat data_source
> +	iio-buffer
> +	root:/sys/bus/iio/devices/iio:device0# echo -n backend-ramp-generator > data_source
> +	root:/sys/bus/iio/devices/iio:device0# cat data_source⏎

Not sure what the trailing character is.

> +	backend-ramp-generator
> +
> +
> diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
> index bbb2edce8272e7483acca500d1a757bbcc11c1e0..2d6afc5a8ed54a90cd8d5723f0dc5212b8593d16 100644
> --- a/Documentation/iio/index.rst
> +++ b/Documentation/iio/index.rst
> @@ -19,6 +19,7 @@ Industrial I/O Kernel Drivers
>  .. toctree::
>     :maxdepth: 1
>  
> +   ad3552r
>     ad4000
>     ad4030
>     ad4695
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 57eaab00f6cb53df52a4799eb2c1afbbd1e77a1e..52bc56a9ee22c66b90555681c4757ea4399adae1 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1295,6 +1295,7 @@ L:	linux-iio@vger.kernel.org
>  S:	Supported
>  W:	https://ez.analog.com/linux-software-drivers
>  F:	Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
> +F:	Documentation/iio/ad3552r.rst
>  F:	drivers/iio/dac/ad3552r.c
>  
>  ANALOG DEVICES INC AD4000 DRIVER
>
diff mbox series

Patch

diff --git a/Documentation/iio/ad3552r.rst b/Documentation/iio/ad3552r.rst
new file mode 100644
index 0000000000000000000000000000000000000000..638a62c99fb876cca026a0b1df469c81ba39ff29
--- /dev/null
+++ b/Documentation/iio/ad3552r.rst
@@ -0,0 +1,65 @@ 
+.. SPDX-License-Identifier: GPL-2.0-only
+
+==============
+AD3552R driver
+==============
+
+Device driver for Analog Devices Inc. AD35XXR series of DACs. The module name
+is ``ad3552r``.
+With the same module name, two different driver variants are available, the
+``generic spi`` variant, to be used with any classic SPI controllers, and the
+``hs`` (high speed) variant, for an ADI ``axi-dac`` (IP core) based controller
+that allows to reach the maximum sample rate supported from the DACs, using the
+DMA transfer and all the SPI lines available (D/QDSPI)..
+The high speed driver variant is intended to be used with the ``adi-axi-dac``
+backend support enabled, that is enabled by default when the driver is selected.
+
+Supported devices
+=================
+
+* `AD3541R <https://www.analog.com/en/products/ad3541r.html>`_
+* `AD3542R <https://www.analog.com/en/products/ad3542r.html>`_
+* `AD3551R <https://www.analog.com/en/products/ad3551r.html>`_
+* `AD3552R <https://www.analog.com/en/products/ad3552r.html>`_
+
+Wiring connections
+------------------
+
+::
+
+    .-----------------.                .-------.
+    |                 |--- D/QSPI -----|       |
+    |   DAC IP CORE   |--- SPI S_CLK --|  DAC  |
+    |                 |--- SPI CS -----|       |
+    |                 |--- LDAC -------|       |
+    |                 |--- RESET ------|       |
+    |_________________|                |_______|
+
+
+High speed features
+===================
+
+Device attributes
+-----------------
+
+The following table shows the ad35xxr related device debug files, found in the
+specific device debug folder path ``/sys/kernel/debug/iio/iio:deviceX``.
+
++----------------------+-------------------------------------------------------+
+| Debugfs device files | Description                                           |
++----------------------+-------------------------------------------------------+
+| data_source          | The used data source,                                 |
+|                      | as ``iio-buffer`` or ``backend-ramp-generator``.      |
++----------------------+-------------------------------------------------------+
+
+Usage examples
+--------------
+
+. code-block:: bash
+	root:/sys/bus/iio/devices/iio:device0# cat data_source
+	iio-buffer
+	root:/sys/bus/iio/devices/iio:device0# echo -n backend-ramp-generator > data_source
+	root:/sys/bus/iio/devices/iio:device0# cat data_source⏎
+	backend-ramp-generator
+
+
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index bbb2edce8272e7483acca500d1a757bbcc11c1e0..2d6afc5a8ed54a90cd8d5723f0dc5212b8593d16 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -19,6 +19,7 @@  Industrial I/O Kernel Drivers
 .. toctree::
    :maxdepth: 1
 
+   ad3552r
    ad4000
    ad4030
    ad4695
diff --git a/MAINTAINERS b/MAINTAINERS
index 57eaab00f6cb53df52a4799eb2c1afbbd1e77a1e..52bc56a9ee22c66b90555681c4757ea4399adae1 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1295,6 +1295,7 @@  L:	linux-iio@vger.kernel.org
 S:	Supported
 W:	https://ez.analog.com/linux-software-drivers
 F:	Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
+F:	Documentation/iio/ad3552r.rst
 F:	drivers/iio/dac/ad3552r.c
 
 ANALOG DEVICES INC AD4000 DRIVER