Re: [PATCH v5 16/16] doc: iio: ad4695: add SPI offload support

[Jonathan Cameron <jic23@kernel.org>]

On Fri, 15 Nov 2024 14:18:55 -0600
David Lechner <dlechner@baylibre.com> wrote:

> Document SPI offload support for the ad4695 driver.
> 
> Signed-off-by: David Lechner <dlechner@baylibre.com>
> ---
> 
> v5 changes: new patch in v5
> ---
>  Documentation/iio/ad4695.rst | 68 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 68 insertions(+)
> 
> diff --git a/Documentation/iio/ad4695.rst b/Documentation/iio/ad4695.rst
> index 9ec8bf466c15..8009a0c272bc 100644
> --- a/Documentation/iio/ad4695.rst
> +++ b/Documentation/iio/ad4695.rst
> @@ -47,6 +47,36 @@ In this mode, CNV and CS are tied together and there is a single SDO line.
>  To use this mode, in the device tree, omit the ``cnv-gpios`` and
>  ``spi-rx-bus-width`` properties.
>  
> +SPI offload wiring
> +^^^^^^^^^^^^^^^^^^
> +
> +When used with a SPI offload, the supported wiring configuration is:
> +
> +.. code-block::
> +
> +    +-------------+         +-------------+
> +    |    GP0/BUSY |-------->| TRIGGER     |
> +    |          CS |<--------| CS          |
> +    |             |         |             |
> +    |     ADC     |         |     SPI     |
> +    |             |         |             |
> +    |         SDI |<--------| SDO         |
> +    |         SDO |-------->| SDI         |
> +    |        SCLK |<--------| SCLK        |
> +    |             |         |             |
> +    |             |         +-------------+
> +    |         CNV |<-----+--| PWM         |
> +    |             |      +--| GPIO        |
> +    +-------------+         +-------------+
> +
> +In this case, both the ``cnv-gpios`` and  ``pwms`` properties are required.
> +The ``#trigger-source-cells = <2>`` property is also required to connect back
> +to the SPI offload. The SPI offload will have ``trigger-sources`` property
> +with cells to indicate the busy signal and which GPx pin is used, e.g
> +``<&ad4695 AD4695_TRIGGER_EVENT_BUSY AD4695_TRIGGER_PIN_GP0>``.
> +
> +.. seealso:: `SPI offload support`_
> +
>  Channel configuration
>  ---------------------
>  
> @@ -158,6 +188,27 @@ Unimplemented features
>  - GPIO support
>  - CRC support
>  
> +SPI offload support
> +===================
> +
> +To be able to achieve the maximum sample rate, the driver can be used with the
> +`AXI SPI Engine`_ to provide SPI offload support.
> +
> +.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/ad469x_fmc/index.html
> +
> +.. seealso:: `SPI offload wiring`_
> +
> +When SPI offload is being used, some attributes will be different.
> +
> +* ``trigger`` directory is removed.
> +* ``in_voltage0_sampling_frequency`` attributes are added for setting the sample
> +  rate.
> +* ``in_voltage0_sampling_frequency_available`` attributes are added for querying
> +  the max sample rate.
> +* ``timestamp`` channel is removed.
> +* Buffer data format may be different compared to when offload is not used,
> +  e.g. the ``in_voltage0_type`` attribute.
> +
>  Device buffers
>  ==============
>  
> @@ -165,3 +216,20 @@ This driver supports hardware triggered buffers. This uses the "advanced
>  sequencer" feature of the chip to trigger a burst of conversions.
>  
>  Also see :doc:`iio_devbuf` for more general information.
> +
> +Effective sample rate for buffered reads
> +----------------------------------------
> +
> +When SPI offload is not used, the sample rate is determined by the trigger that
> +is manually configured in userspace. All enabled channels will be read in a
> +burst when the trigger is received.
> +
> +When SPI offload is used, the sample rate is configured per channel. All
> +all channels will have the same rate, so only one ``sampling_frequency``
Double all.
> +attribute needs to be set. Since this rate determines the delay between each
> +individual conversion, the effective sample rate for each sample is actually
> +the sum of the periods of each enabled channel in a buffered read. In other
> +words, it is the value of the ``sampling_frequency`` attribute divided by the
> +number of enabled channels. So if 4 channels are enabled, with the
> +``sampling_frequency`` attributes set to 1 MHz, the effective sample rate is
> +250 kHz.
If you are exposing that as a single sampling_frequency I think we should be
adjusting the frequency so it represents the same thing in both modes.

So divide by the number of channels (conversely run faster if more channels
enabled).

Jonathan
>