iio: adc: ADEMA124/ADEMA127 driver with hardware-triggered SPI Offload streaming for SC846

Documentation/devicetree/bindings/iio/adc/adi,adema127.yaml

@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,adema127.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices ADEMA124 / ADEMA127 poly-phase energy metering ADCs
+
+maintainers:
+  - Michael Hennerich <michael.hennerich@analog.com>
+
+description: |
+  The ADEMA124 and ADEMA127 are 4- and 7-channel simultaneous-sampling
+  24-bit sigma-delta ADCs targeted at energy metering. They share the same
+  SPI command / long-frame response protocol, and are keyed at runtime by
+  the PRODUCT_ID register (0x13 = ADEMA124, 0x16 = ADEMA127).
+
+  Data conversions are announced on the DREADY pin. Two capture paths are
+  supported:
+
+  * A per-DREADY software-triggered IIO buffer that runs on any SPI
+    controller. The DREADY interrupt must be described in the "interrupts"
+    property (or via an "interrupt-names" entry named "dready").
+
+  * An autonomous SPI Offload streaming path. When the underlying SPI
+    controller advertises SPI_OFFLOAD_CAP_TRIGGER + SPI_OFFLOAD_CAP_RX_STREAM_DMA,
+    the driver enables it automatically. Refer to the controller's binding
+    for how to describe the offload channel and its trigger source.
+
+  Datasheet:
+  * https://www.analog.com/en/products/adema124.html
+  * https://www.analog.com/en/products/adema127.html
+
+$ref: /schemas/spi/spi-peripheral-props.yaml#
+
+properties:
+  compatible:
+    enum:
+      - adi,adema124
+      - adi,adema127
+
+  reg:
+    maxItems: 1
+
+  spi-max-frequency:
+    maximum: 22000000
+
+  # SPI mode 3 (CPOL=1, CPHA=1)
+  spi-cpol: true
+  spi-cpha: true
+
+  interrupts:
+    description:
+      DREADY interrupt line. The interrupt fires on the falling edge each
+      time a new sample set is latched into the SPI shift-out buffer.
+    maxItems: 1
+
+  interrupt-names:
+    items:
+      - const: dready
+
+  dready-gpios:
+    description: |
+      Alternative description of the DREADY line as a GPIO. Preferred on
+      SoCs whose pin interrupt blocks observe the pad behind an input
+      buffer enable (e.g. ADI SC5xx PINT): the driver claims the GPIO as
+      an input (which enables the pad's input buffer) and derives the
+      interrupt via the GPIO controller's irq domain. Takes precedence
+      over the "interrupts" property when both are present. Not used in
+      SPI-offload streaming mode, where DREADY feeds a hardware trigger
+      chain instead.
+    maxItems: 1
+
+  vdd-supply:
+    description: 3.3 V ±10 % analog / digital supply.
+
+  refio-supply:
+    description:
+      Optional external 1.25 V reference. When absent the internal
+      band-gap reference is used.
+
+  clocks:
+    description: |
+      Master clock feeding XTALIN / MCLKIN. Nominally 16.384 MHz; the driver
+      reads clk_get_rate() to derive DATARATE register values for other
+      supported crystal frequencies. Describe the crystal as a fixed-clock
+      when there is no on-SoC gateable source.
+    maxItems: 1
+
+  clock-names:
+    items:
+      - const: xtal
+
+  reset-gpios:
+    description: |
+      Optional GPIO wired to the RESET pin (active-low on the ADEMA124/127).
+      The driver pulses RESET at probe: it asserts (drives the pin low), waits
+      for the hardware to settle, then deasserts. When this property is absent
+      the driver falls back to a software reset (write 0xD6 to SWRST).
+      Describe the phandle with GPIO_ACTIVE_LOW so gpiod handles the polarity.
+    maxItems: 1
+
+  adi,offload-frames-per-interrupt:
+    description: |
+      SPI-offload streaming only. Default number of long-frames the RX
+      DMA descriptor ring accumulates per completion interrupt (the
+      interrupt rate is sample-rate divided by this number). Used when
+      userspace has not expressed a preference through the standard IIO
+      buffer watermark (watermark left at its kernel default of 1); a
+      watermark of 2 or more set by userspace always takes precedence.
+    $ref: /schemas/types.yaml#/definitions/uint32
+    minimum: 1
+    maximum: 4096
+    default: 128
+
+  "#address-cells":
+    const: 1
+
+  "#size-cells":
+    const: 0
+
+patternProperties:
+  "^channel@[0-6]$":
+    type: object
+    additionalProperties: false
+    description: Optional per-channel configuration node.
+
+    properties:
+      reg:
+        description: Channel index (0..6 for ADEMA127; 0..3 for ADEMA124).
+        minimum: 0
+        maximum: 6
+
+      adi,input-gain:
+        description:
+          Hardware analogue input gain applied at the channel front-end.
+          Written to ADC_GAIN[channel].
+        $ref: /schemas/types.yaml#/definitions/uint32
+        enum: [1, 2]
+        default: 1
+
+      adi,input-invert:
+        description:
+          Invert the analogue-input polarity for this channel.
+          Sets ADC_INV[channel].
+        type: boolean
+
+    required:
+      - reg
+
+required:
+  - compatible
+  - reg
+  - clocks
+
+oneOf:
+  - required:
+      - interrupts
+  - required:
+      - dready-gpios
+
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: adi,adema124
+    then:
+      patternProperties:
+        "^channel@[4-6]$": false
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    xtal_16m384: xtal-16m384 {
+        compatible = "fixed-clock";
+        #clock-cells = <0>;
+        clock-frequency = <16384000>;
+    };
+
+    spi {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        adc@0 {
+            compatible = "adi,adema127";
+            reg = <0>;
+            spi-max-frequency = <20000000>;
+            spi-cpol;
+            spi-cpha;
+
+            interrupt-parent = <&gpio0>;
+            interrupts = <17 IRQ_TYPE_EDGE_FALLING>;
+            interrupt-names = "dready";
+
+            vdd-supply = <&vdd_3v3>;
+            clocks = <&xtal_16m384>;
+            clock-names = "xtal";
+            reset-gpios = <&gpio0 22 GPIO_ACTIVE_LOW>;
+
+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            channel@0 {
+                reg = <0>;
+                adi,input-gain = <2>;
+            };
+        };
+    };
+...

Documentation/devicetree/bindings/spi/adi,spi3.yaml

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/spi/adi,spi3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ADI ADSP-SC5xx / SC84x SPI3 controller
+
+maintainers:
+  - Michael Hennerich <michael.hennerich@analog.com>
+
+description: |
+  Enhanced SPI (SPI3) controller found on the ADI ADSP-SC5xx / SC84x
+  processor family. Supports PIO and DMA transfers, GPIO chip selects,
+  and an optional SPI Offload streaming mode in which hardware-triggered
+  transactions run autonomously through dedicated DMA channels
+  (trigger routed via the on-chip TRU, e.g. from a data-ready pin).
+
+allOf:
+  - $ref: spi-controller.yaml#
+
+properties:
+  compatible:
+    const: adi,spi3
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    const: spi
+
+  dmas:
+    minItems: 1
+    maxItems: 4
+
+  dma-names:
+    description: |
+      Regular "tx"/"rx" channels serve slaves that opt into DMA via
+      adi,enable-dma; when absent, non-offload transfers fall back to
+      PIO. "offload-tx"/"offload-rx" declare the dedicated SPI Offload
+      stream channels handed to the offload consumer; listing
+      "offload-rx" (and optionally "offload-tx") advertises the
+      corresponding SPI_OFFLOAD_CAP_*_STREAM_DMA capabilities. On
+      parts with a single physical DMA channel per direction, a port
+      is either regular or offload-only.
+    minItems: 1
+    maxItems: 4
+    items:
+      enum: [ tx, rx, offload-tx, offload-rx ]
+
+  trigger-sources:
+    description: |
+      Phandle to a SPI offload trigger provider (e.g. the TRU-backed
+      data-ready trigger, see
+      trigger-source/adi,sc59x-spi-offload-trigger.yaml). Presence of
+      this property enables the SPI Offload provider on this port.
+    maxItems: 1
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    /* Offload-only port streaming an ADEMA127 via hardware triggers */
+    spi@3102e000 {
+        #address-cells = <1>;
+        #size-cells = <0>;
+        compatible = "adi,spi3";
+        reg = <0x3102e000 0xff>;
+        interrupts = <GIC_SPI 233 IRQ_TYPE_LEVEL_HIGH>;
+        clocks = <&clk 25>;
+        clock-names = "spi";
+        dmas = <&spi_cluster 22>, <&spi_cluster 23>;
+        dma-names = "offload-tx", "offload-rx";
+        trigger-sources = <&adema_dready_trigger>;
+    };
+...