[PATCH RFC v4 14/15] dt-bindings: iio: adc: adi,ad4695: add SPI offload properties

[David Lechner <dlechner@xxxxxxxxxxxx>]

Add a pwms property to the adi,ad4695 binding to specify an optional PWM
output connected to the CNV pin on the ADC.

Also add #trigger-source-cells property to allow the BUSY output to be
used as a SPI offload trigger source to indicate when a sample is ready
to be read.

The $ref for spi-peripheral-props.yaml is moved to keep similar $refs
grouped together.

Signed-off-by: David Lechner <dlechner@xxxxxxxxxxxx>
---

v4 changes: new patch in v4

For offload support, this doesn't actually tell the whole story. For
some use cases, it would be perfectly reasonable to have a PWM directly
connected to the CNV pin, which is why I have made the bindings like
this. However, in order to work with the the AXI SPI Engine SPI offload
and allow for non-cyclic DMA transfers, the actual signal that is being
connected to the CNV pin is:

    CNV = (PWM_OUT && !DMA_FULL) || CNV_GPIO_OUT

RFC: Is this binding sufficient for this use case? Or should we consider
something that describes it more accurately?

The gory details (mostly of interest for those reviewing the driver
patch that uses this binding):
* The PWM output has to be disabled in hardware by connecting it to an
  AND gate where the 2nd input comes from the DMA controller. This is
  necessary to ensure that we can only trigger conversions as long as
  there is room in the DMA buffer to receive them. If we continue to
  trigger conversions when the DMA is full, then the advanced sequencer
  in the ADC chip keeps advancing and we will end up starting the next
  batch of conversions with a random channel when DMA is no longer full.
* To get out of conversion mode, we also have to toggle the CNV pin
  manually one time. If it wasn't for the DMA mask on the PWM output,
  we could just use 0% and 100% duty cycle to toggle the CNV pin, but
  since the PWM output is masked by the DMA, we have to use a GPIO to
  toggle the CNV pin. The GPIO signal is connected to an input of an OR
  gate along with the output of the AND gate mentioned above.
---
 Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml
index 310f046e139f..0d767d8b867a 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml
@@ -18,8 +18,6 @@ description: |
   * https://www.analog.com/en/products/ad4697.html
   * https://www.analog.com/en/products/ad4698.html
 
-$ref: /schemas/spi/spi-peripheral-props.yaml#
-
 properties:
   compatible:
     enum:
@@ -84,6 +82,9 @@ properties:
     description: The Reset Input (RESET). Should be configured GPIO_ACTIVE_LOW.
     maxItems: 1
 
+  pwms:
+    description: PWM signal connected to the CNV pin.
+
   interrupts:
     minItems: 1
     items:
@@ -106,6 +107,12 @@ properties:
       The first cell is the GPn number: 0 to 3.
       The second cell takes standard GPIO flags.
 
+  '#trigger-source-cells':
+    description: |
+      First cell indicates the output signal: 0 = BUSY, 1 = ALERT.
+      Second cell indicates which GPn pin is used: 0 to 3.
+    const: 2
+
   "#address-cells":
     const: 1
 
@@ -165,6 +172,8 @@ required:
   - vio-supply
 
 allOf:
+  - $ref: /schemas/spi/spi-peripheral-props.yaml#
+  - $ref: /schemas/spi/trigger-source.yaml#
   - oneOf:
       - required:
           - ldo-in-supply

-- 
2.43.0