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

[David Lechner <dlechner@baylibre.com>]

On 11/24/24 11:38 AM, Jonathan Cameron wrote:
> 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.

There are separate sampling frequency attributes per channel. I wrote
"attributes" to try to indicate this. But I was lazy and abbreviated the
attribute names. So I can fix that.

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