linux-loongson/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml

# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
# Copyright 2023 Analog Devices Inc.
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/adc/adi,ad7173.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Analog Devices AD7173 ADC

maintainers:
  - Ceclan Dumitru <dumitru.ceclan@analog.com>

description: |
  Analog Devices AD717x ADC's:
  The AD717x family offer a complete integrated Sigma-Delta ADC solution which
  can be used in high precision, low noise single channel applications
  (Life Science measurements) or higher speed multiplexed applications
  (Factory Automation PLC Input modules). The Sigma-Delta ADC is intended
  primarily for measurement of signals close to DC but also delivers
  outstanding performance with input bandwidths out to ~10kHz.

  Analog Devices AD411x ADC's:
  The AD411X family encompasses a series of low power, low noise, 24-bit,
  sigma-delta analog-to-digital converters that offer a versatile range of
  specifications. They integrate an analog front end suitable for processing
  fully differential/single-ended and bipolar voltage inputs.

  Datasheets for supported chips:
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD4111.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD4112.pdf
    <AD4113: not released yet>
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD4114.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD4115.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD4116.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7172-2.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7172-4.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7173-8.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7175-2.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7175-8.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7176-2.pdf
    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7177-2.pdf  

properties:
  compatible:
    enum:
      - adi,ad4111
      - adi,ad4112
      - adi,ad4113
      - adi,ad4114
      - adi,ad4115
      - adi,ad4116
      - adi,ad7172-2
      - adi,ad7172-4
      - adi,ad7173-8
      - adi,ad7175-2
      - adi,ad7175-8
      - adi,ad7176-2
      - adi,ad7177-2

  reg:
    maxItems: 1

  interrupts:
    minItems: 1
    items:
      - description: |
          Ready: multiplexed with SPI data out. While SPI CS is low,
          can be used to indicate the completion of a conversion.          

      - description: |
          Error: The three error bits in the status register (ADC_ERROR, CRC_ERROR,
          and REG_ERROR) are OR'ed, inverted, and mapped to the ERROR pin.
          Therefore, the ERROR pin indicates that an error has occurred.          

  interrupt-names:
    minItems: 1
    items:
      - const: rdy
      - const: err

  '#address-cells':
    const: 1

  '#size-cells':
    const: 0

  spi-max-frequency:
    maximum: 20000000

  gpio-controller:
    description: Marks the device node as a GPIO controller.

  '#gpio-cells':
    const: 2
    description:
      The first cell is the GPIO number and the second cell specifies
      GPIO flags, as defined in <dt-bindings/gpio/gpio.h>.

  vref-supply:
    description: |
      Differential external reference supply used for conversion. The reference
      voltage (Vref) specified here must be the voltage difference between the
      REF+ and REF- pins: Vref = (REF+) - (REF-).      

  vref2-supply:
    description: |
      Differential external reference supply used for conversion. The reference
      voltage (Vref2) specified here must be the voltage difference between the
      REF2+ and REF2- pins: Vref2 = (REF2+) - (REF2-).      

  avdd-supply:
    description: Avdd supply, can be used as reference for conversion.
                 This supply is referenced to AVSS, voltage specified here
                 represents (AVDD1 - AVSS).

  avdd2-supply:
    description: Avdd2 supply, used as the input to the internal voltage regulator.
                 This supply is referenced to AVSS, voltage specified here
                 represents (AVDD2 - AVSS).

  iovdd-supply:
    description: iovdd supply, used for the chip digital interface.

  clocks:
    maxItems: 1
    description: |
      Optional external clock source. Can include one clock source: external
      clock or external crystal.      

  clock-names:
    enum:
      - ext-clk
      - xtal

  '#clock-cells':
    const: 0

  rdy-gpios:
    description:
      GPIO reading the R̅D̅Y̅ line. Having such a GPIO is technically optional but
      highly recommended because DOUT/R̅D̅Y̅ toggles during SPI transfers (in its
      DOUT aka MISO role) and so usually triggers a spurious interrupt. The
      distinction between such a spurious event and a real one can only be done
      by reading such a GPIO. (There is a register telling the same
      information, but accessing that one needs a SPI transfer which then
      triggers another interrupt event.)
    maxItems: 1

patternProperties:
  "^channel@[0-9a-f]$":
    type: object
    $ref: adc.yaml
    unevaluatedProperties: false

    properties:
      reg:
        minimum: 0
        maximum: 15

      diff-channels:
        description: |
          This property is used for defining the inputs of a differential
          voltage channel. The first value is the positive input and the second
          value is the negative input of the channel.

          Family AD411x supports a dedicated VINCOM voltage input.
          To select it set the second channel to 16.
            (VIN2, VINCOM) -> diff-channels = <2 16>

          There are special values that can be selected besides the voltage
          analog inputs:
            21: REF+
            22: REF−

          Supported only by AD7172-2, AD7172-4, AD7175-2, AD7175-8, AD7177-2,
          must be paired together and can be used to monitor the power supply
          of the ADC:
            19: ((AVDD1 − AVSS)/5)+
            20: ((AVDD1 − AVSS)/5)−          

        items:
          minimum: 0
          maximum: 31

      single-channel:
        description: |
          This property is used for defining a current channel or the positive
          input of a voltage channel (single-ended or pseudo-differential).

          Models AD4111 and AD4112 support current channels.
            Example: (IIN2+, IIN2−) -> single-channel = <2>
          To correctly configure a current channel set the "adi,current-channel"
          property to true.

          To configure a single-ended/pseudo-differential channel set the
          "common-mode-channel" property to the desired negative voltage input.

          When used as a voltage channel, special inputs are valid as well.          
        minimum: 0
        maximum: 31

      common-mode-channel:
        description:
          This property is used for defining the negative input of a
          single-ended or pseudo-differential voltage channel.

          Special inputs are valid as well.
        minimum: 0
        maximum: 31

      adi,reference-select:
        description: |
          Select the reference source to use when converting on
          the specific channel. Valid values are:
          vref       : REF+  /REF−
          vref2      : REF2+ /REF2−
          refout-avss: REFOUT/AVSS (Internal reference)
          avdd       : AVDD  /AVSS

          External reference ref2 only available on ad7173-8 and ad7172-4.
          Internal reference refout-avss not available on ad7172-4.

          If not specified, internal reference used (if available).          
        $ref: /schemas/types.yaml#/definitions/string
        enum:
          - vref
          - vref2
          - refout-avss
          - avdd
        default: refout-avss

      adi,current-channel:
        $ref: /schemas/types.yaml#/definitions/flag
        description: |
          Signal that the selected inputs are current channels.
          Only available on AD4111 and AD4112.          

    required:
      - reg

    allOf:
      - oneOf:
          - required: [single-channel]
            properties:
              diff-channels: false
          - required: [diff-channels]
            properties:
              single-channel: false
              adi,current-channel: false
              common-mode-channel: false

      - if:
          required: [common-mode-channel]
        then:
          properties:
            adi,current-channel: false

required:
  - compatible
  - reg

allOf:
  - $ref: /schemas/spi/spi-peripheral-props.yaml#

  # Only ad7172-4, ad7173-8 and ad7175-8 support vref2
  - if:
      properties:
        compatible:
          not:
            contains:
              enum:
                - adi,ad7172-4
                - adi,ad7173-8
                - adi,ad7175-8
    then:
      properties:
        vref2-supply: false
      patternProperties:
        "^channel@[0-9a-f]$":
          properties:
            adi,reference-select:
              enum:
                - vref
                - refout-avss
                - avdd

  - if:
      properties:
        compatible:
          contains:
            enum:
              - adi,ad4114
              - adi,ad4115
              - adi,ad4116
              - adi,ad7173-8
              - adi,ad7175-8
    then:
      patternProperties:
        "^channel@[0-9a-f]$":
          properties:
            reg:
              maximum: 15

  - if:
      properties:
        compatible:
          contains:
            enum:
              - adi,ad7172-2
              - adi,ad7175-2
              - adi,ad7176-2
              - adi,ad7177-2
    then:
      patternProperties:
        "^channel@[0-9a-f]$":
          properties:
            reg:
              maximum: 3

  # Model ad7172-4 does not support internal reference
  - if:
      properties:
        compatible:
          contains:
            const: adi,ad7172-4
    then:
      patternProperties:
        "^channel@[0-9a-f]$":
          properties:
            reg:
              maximum: 7
            adi,reference-select:
              enum:
                - vref
                - vref2
                - avdd
          required:
            - adi,reference-select

  - if:
      properties:
        compatible:
          contains:
            enum:
              - adi,ad4111
              - adi,ad4112
              - adi,ad4113
              - adi,ad4114
              - adi,ad4115
              - adi,ad4116
    then:
      properties:
        avdd2-supply: false

  - if:
      properties:
        compatible:
          not:
            contains:
              enum:
                - adi,ad4111
                - adi,ad4112
    then:
      patternProperties:
        "^channel@[0-9a-f]$":
          properties:
            adi,current-channel: false

  - if:
      anyOf:
        - required: [clock-names]
        - required: [clocks]
    then:
      properties:
        '#clock-cells': false

unevaluatedProperties: false

examples:
  # Example AD7173-8 with external reference connected to REF+/REF-:
  - |
    #include <dt-bindings/gpio/gpio.h>
    #include <dt-bindings/interrupt-controller/irq.h>

    spi {
      #address-cells = <1>;
      #size-cells = <0>;

      adc@0 {
        compatible = "adi,ad7173-8";
        reg = <0>;

        #address-cells = <1>;
        #size-cells = <0>;

        interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
        interrupt-names = "rdy";
        interrupt-parent = <&gpio>;
        spi-max-frequency = <5000000>;
        gpio-controller;
        #gpio-cells = <2>;
        #clock-cells = <0>;

        vref-supply = <&dummy_regulator>;

        channel@0 {
          reg = <0>;
          bipolar;
          diff-channels = <0 1>;
          adi,reference-select = "vref";
        };

        channel@1 {
          reg = <1>;
          diff-channels = <2 3>;
        };

        channel@2 {
          reg = <2>;
          bipolar;
          diff-channels = <4 5>;
        };

        channel@3 {
          reg = <3>;
          bipolar;
          diff-channels = <6 7>;
        };

        channel@4 {
          reg = <4>;
          diff-channels = <8 9>;
          adi,reference-select = "avdd";
        };
      };
    };    

  # Example AD4111 with current channel and single-ended channel:
  - |
    #include <dt-bindings/gpio/gpio.h>
    #include <dt-bindings/interrupt-controller/irq.h>

    spi {
      #address-cells = <1>;
      #size-cells = <0>;

       adc@0 {
        compatible = "adi,ad4111";
        reg = <0>;

        #address-cells = <1>;
        #size-cells = <0>;

        interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
        interrupt-names = "rdy";
        interrupt-parent = <&gpio>;
        rdy-gpios = <&gpio 25 GPIO_ACTIVE_LOW>;
        spi-max-frequency = <5000000>;
        gpio-controller;
        #gpio-cells = <2>;
        #clock-cells = <0>;

        channel@0 {
          reg = <0>;
          bipolar;
          diff-channels = <4 5>;
        };

        // Single ended channel VIN2/VINCOM
        channel@1 {
          reg = <1>;
          bipolar;
          single-channel = <2>;
          common-mode-channel = <16>;
        };

        // Current channel IN2+/IN2-
        channel@2 {
          reg = <2>;
          single-channel = <2>;
          adi,current-channel;
        };
      };
    };