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

# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/adc/adi,ad7606.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Analog Devices AD7606 Simultaneous Sampling ADC

maintainers:
  - Michael Hennerich <michael.hennerich@analog.com>

description: |
  Analog Devices AD7606 Simultaneous Sampling ADC
  https://www.analog.com/media/en/technical-documentation/data-sheets/AD7605-4.pdf
  https://www.analog.com/media/en/technical-documentation/data-sheets/ad7606_7606-6_7606-4.pdf
  https://www.analog.com/media/en/technical-documentation/data-sheets/AD7606B.pdf
  https://www.analog.com/media/en/technical-documentation/data-sheets/ad7606c-16.pdf
  https://www.analog.com/media/en/technical-documentation/data-sheets/ad7606c-18.pdf
  https://www.analog.com/media/en/technical-documentation/data-sheets/ad7607.pdf
  https://www.analog.com/media/en/technical-documentation/data-sheets/ad7608.pdf
  https://www.analog.com/media/en/technical-documentation/data-sheets/ad7609.pdf
  https://www.analog.com/media/en/technical-documentation/data-sheets/AD7616.pdf  

properties:
  compatible:
    enum:
      - adi,ad7605-4
      - adi,ad7606-4
      - adi,ad7606-6
      - adi,ad7606-8  # Referred to as AD7606 (without -8) in the datasheet
      - adi,ad7606b
      - adi,ad7606c-16
      - adi,ad7606c-18
      - adi,ad7607
      - adi,ad7608
      - adi,ad7609
      - adi,ad7616

  reg:
    maxItems: 1

  "#address-cells":
    const: 1

  "#size-cells":
    const: 0

  '#trigger-source-cells':
    description: |
      Cell indicates the output signal: 0 = BUSY, 1 = FIRSTDATA.

      For convenience, macros for these values are available in
      dt-bindings/iio/adc/adi,ad7606.h.      
    const: 1

  # According to the datasheet, "Data is clocked in from SDI on the falling
  # edge of SCLK, while data is clocked out on DOUTA on the rising edge of
  # SCLK".  Also, even if not stated textually in the datasheet, it is made
  # clear on the diagrams that sclk idles at high.  Subsequently, in case SPI
  # interface is used, the correct way is to only set spi-cpol.
  spi-cpha: true

  spi-cpol: true

  avcc-supply: true

  vdrive-supply:
    description:
      Determines the voltage level at which the interface logic pins will
      operate.

  refin-supply:
    description:
      The voltage supply for optional external reference voltage.

  interrupts:
    description:
      The BUSY pin falling edge indicates that the conversion is over, and thus
      new data is available.
    maxItems: 1

  adi,conversion-start-gpios:
    description:
      Must be the device tree identifier of the CONVST pin(s). This logic input
      is used to initiate conversions on the analog input channels. As the line
      is active high, it should be marked GPIO_ACTIVE_HIGH.
    minItems: 1
    maxItems: 2

  reset-gpios:
    description:
      Must be the device tree identifier of the RESET pin. If specified, it will
      be asserted during driver probe. On the AD7606x, as the line is active
      high, it should be marked GPIO_ACTIVE_HIGH. On the AD7616, as the line is
      active low, it should be marked GPIO_ACTIVE_LOW.
    maxItems: 1

  standby-gpios:
    description:
      Must be the device tree identifier of the STBY pin. This pin is used to
      place the AD7606 into one of two power-down modes, Standby mode or
      Shutdown mode. As the line is active low, it should be marked
      GPIO_ACTIVE_LOW.
    maxItems: 1

  adi,first-data-gpios:
    description:
      Must be the device tree identifier of the FRSTDATA pin. The FRSTDATA
      output indicates when the first channel, V1, is being read back on either
      the parallel, byte or serial interface. As the line is active high, it
      should be marked GPIO_ACTIVE_HIGH.
    maxItems: 1

  adi,range-gpios:
    description:
      Must be the device tree identifier of the RANGE pin. The state on this
      pin determines the input range of the analog input channels. If this pin
      is tied to a logic high, the analog input range is ±10V for all channels.
      On the AD760X, if this pin is tied to a logic low, the analog input range
      is ±5V for all channels. As the line is active high, it should be marked
      GPIO_ACTIVE_HIGH. On the AD7616, there are 2 pins, and if the 2 pins are
      tied to a logic high, software mode is enabled, otherwise one of the 3
      possible range values is selected.
    minItems: 1
    maxItems: 2

  adi,oversampling-ratio-gpios:
    description:
      Must be the device tree identifier of the over-sampling mode pins. As the
      line is active high, it should be marked GPIO_ACTIVE_HIGH. On the AD7606X
      parts that support it, if all 3 pins are tied to a logic high, software
      mode is enabled.
    maxItems: 3

  adi,sw-mode:
    description:
      Software mode of operation, so far available only for AD7616 and AD7606B.
      It is enabled when all three oversampling mode pins are connected to high
      level for the AD7606B, or both the range selection are connected to high
      level for the AD7616. The device is configured by the corresponding
      registers. If the adi,oversampling-ratio-gpios property is defined, then
      the driver will set the oversampling gpios to high. Otherwise, it is
      assumed that the pins are hardwired to VDD.
    type: boolean

  pwms:
    description:
      In case the conversion is triggered by a PWM instead of a GPIO plugged to
      the CONVST pin, the PWM must be referenced.
      The first is the PWM connected to CONVST or CONVST1 for the chips with the
      2nd PWM connected to CONVST2, if CONVST2 is available and not shorted to
      CONVST1.
    minItems: 1
    maxItems: 2

  pwm-names:
    minItems: 1
    items:
      - const: convst1
      - const: convst2

  io-backends:
    description:
      A reference to the iio-backend, which is responsible handling the BUSY
      pin's falling edge and communication.
      An example of backend can be found at
      http://analogdevicesinc.github.io/hdl/library/axi_ad7606x/index.html


patternProperties:
  "^channel@[1-8]$":
    type: object
    $ref: adc.yaml
    unevaluatedProperties: false

    properties:
      reg:
        description:
          The channel number, as specified in the datasheet (from 1 to 8).
        minimum: 1
        maximum: 8

      diff-channels:
        description:
          Each channel can be configured as a bipolar differential channel.
          The ADC uses the same positive and negative inputs for this.
          This property must be specified as 'reg' (or the channel number) for
          both positive and negative inputs (i.e. diff-channels = <reg reg>).
          Since the configuration is bipolar differential, the 'bipolar'
          property is required.
        items:
          minimum: 1
          maximum: 8

      bipolar:
        description:
          The ADC channels can be configured as
             * Bipolar single-ended
             * Unipolar single-ended
             * Bipolar differential
          Therefore in the DT, if no channel node is specified, it is considered
          'unipolar single-ended'. So for the other configurations the 'bipolar'
          property must be specified. If 'diff-channels' is specified, it is
          considered a bipolar differential channel. Otherwise it is bipolar
          single-ended.

      adi,rfilter-ohms:
        description:
          For ADCs that supports gain calibration, this property must be set to
          the value of the external RFilter resistor. Proper gain error
          correction is applied based on this value.
        default: 0
        minimum: 0
        maximum: 64512

    required:
      - reg
      - bipolar

required:
  - compatible
  - reg
  - avcc-supply
  - vdrive-supply

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

  - oneOf:
      - required:
          - adi,conversion-start-gpios
      - required:
          - pwms

  - if:
      properties:
        compatible:
          contains:
            const: adi,ad7616
    then:
      properties:
        adi,first-data-gpios: false
        standby-gpios: false
        adi,range-gpios:
          maxItems: 2
    else:
      properties:
        adi,range-gpios:
          maxItems: 1

  - if:
      properties:
        compatible:
          contains:
            enum:
              - adi,ad7605-4
              - adi,ad7616
    then:
      properties:
        adi,oversampling-ratio-gpios: false

  - if:
      properties:
        compatible:
          contains:
            enum:
              - adi,ad7605-4
              - adi,ad7606-4
              - adi,ad7606-6
              - adi,ad7606-8
              - adi,ad7607
              - adi,ad7608
              - adi,ad7609
              - adi,ad7616
    then:
      patternProperties:
        "^channel@[0-9a-f]+$":
          properties:
            adi,rfilter-ohms: false

  - if:
      properties:
        compatible:
          contains:
            enum:
              - adi,ad7605-4
              - adi,ad7606-4
              - adi,ad7606-6
              - adi,ad7606-8
              - adi,ad7607
              - adi,ad7608
              - adi,ad7609
    then:
      properties:
        adi,sw-mode: false
    else:
      properties:
        pwms:
          maxItems: 1
        pwm-names:
          maxItems: 1
        adi,conversion-start-gpios:
          maxItems: 1

  - if:
      not:
        required:
          - adi,sw-mode
    then:
      patternProperties:
        "^channel@[1-8]$": false

  - if:
      not:
        properties:
          compatible:
            enum:
              - adi,ad7606c-16
              - adi,ad7606c-18
    then:
      patternProperties:
        "^channel@[1-8]$": false

unevaluatedProperties: false

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>
    iio-backend {
        #address-cells = <1>;
        #size-cells = <0>;
        adi_adc@0 {
            compatible = "adi,ad7606b";
            reg = <0>;
            pwms = <&axi_pwm_gen 0 0>;

            avcc-supply = <&adc_vref>;
            vdrive-supply = <&vdd_supply>;

            reset-gpios = <&gpio0 91 GPIO_ACTIVE_HIGH>;
            standby-gpios = <&gpio0 90 GPIO_ACTIVE_LOW>;
            adi,range-gpios = <&gpio0 89 GPIO_ACTIVE_HIGH>;
            adi,oversampling-ratio-gpios = <&gpio0 88 GPIO_ACTIVE_HIGH
                                            &gpio0 87 GPIO_ACTIVE_HIGH
                                            &gpio0 86 GPIO_ACTIVE_HIGH>;
            io-backends = <&iio_backend>;
        };
    };    

  - |
    #include <dt-bindings/gpio/gpio.h>
    #include <dt-bindings/interrupt-controller/irq.h>
    spi {
        #address-cells = <1>;
        #size-cells = <0>;

        adc@0 {
            compatible = "adi,ad7606-8";
            reg = <0>;
            spi-max-frequency = <1000000>;
            spi-cpol;

            avcc-supply = <&adc_vref>;
            vdrive-supply = <&vdd_supply>;

            interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
            interrupt-parent = <&gpio>;

            adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
            reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
            adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
            adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH>,
                                           <&gpio 23 GPIO_ACTIVE_HIGH>,
                                           <&gpio 26 GPIO_ACTIVE_HIGH>;
            standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>;
        };
    };    
  - |
    #include <dt-bindings/gpio/gpio.h>
    #include <dt-bindings/interrupt-controller/irq.h>
    spi {
        #address-cells = <1>;
        #size-cells = <0>;

        adc@0 {
            compatible = "adi,ad7606c-18";
            reg = <0>;

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

            spi-max-frequency = <1000000>;
            spi-cpol;

            avcc-supply = <&adc_vref>;
            vdrive-supply = <&vdd_supply>;

            interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
            interrupt-parent = <&gpio>;

            adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
            reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
            adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
            standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>;

            adi,sw-mode;

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

            channel@3 {
                reg = <3>;
                bipolar;
            };

            channel@8 {
                reg = <8>;
                diff-channels = <8 8>;
                bipolar;
                adi,rfilter-ohms = <2048>;
            };

        };
    };    
...