dts/upstream/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.

  Datasheets for supported chips:
    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,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

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

    properties:
      reg:
        minimum: 0
        maximum: 15

      diff-channels:
        items:
          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

    required:
      - reg
      - diff-channels

required:
  - compatible
  - reg

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

  # Only ad7172-4, ad7173-8 and ad7175-8 support vref2
  # Other models have [0-3] channel registers
  - 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
            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:
      anyOf:
        - required: [clock-names]
        - required: [clocks]
    then:
      properties:
        '#clock-cells': false

unevaluatedProperties: false

examples:
  - |
    #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";
        };
      };
    };