Re: [PATCH v2 1/7] dt-bindings: iio: adc: Add AD4170

Rob Herring
2025-05-09T18:56:09Z

On Mon, Apr 28, 2025 at 09:27:46AM -0300, Marcelo Schmitt wrote:
> Add device tree documentation for AD4170 and similar sigma-delta ADCs.
> The AD4170 is a 24-bit, multichannel, sigma-delta ADC.
>
> Signed-off-by: Marcelo Schmitt <marcelo.schmitt@analog.com>
> ---
> [device tree changes]
> - Referenced adc.yaml from sensor-node.
> - Merged property descriptions to reduce doc duplication.
> - Every child node type is now in the example.
> - Better described sensor-type property with a list of possible types.
> - Updated adi,excitation-pins description to cover a use case I had overlooked.
> - Added default to interrupt-names and to clock-names.
> - Added support for clock-output-names
> - Dropped '|' from descriptions when not needed.
> - Added extra example
> -
>
> .../bindings/iio/adc/adi,ad4170.yaml | 554 ++++++++++++++++++
> MAINTAINERS | 7 +
> 2 files changed, 561 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad4170.yaml
>
> diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4170.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4170.yaml
> new file mode 100644
> index 000000000000..679825be1f15
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4170.yaml
> @@ -0,0 +1,554 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/adc/adi,ad4170.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices AD4170 and similar Analog to Digital Converters
> +
> +maintainers:
> + - Marcelo Schmitt <marcelo.schmitt@analog.com>
> +
> +description: |
> + Analog Devices AD4170 series of Sigma-delta Analog to Digital Converters.
> + Specifications can be found at:
> + https://www.analog.com/media/en/technical-documentation/data-sheets/ad4170-4.pdf
> + https://www.analog.com/media/en/technical-documentation/data-sheets/ad4190-4.pdf
> + https://www.analog.com/media/en/technical-documentation/data-sheets/ad4195-4.pdf
> +
> +$ref: /schemas/spi/spi-peripheral-props.yaml#
> +
> +$defs:
> + sensor-node:
> + type: object
> + $ref: /schemas/iio/adc/adc.yaml#
> + description:
> + The AD4170 and similar designs have features to aid interfacing with weigh
> + scale, RTD, and thermocouple sensors. Each of those sensor types requires
> + either distinct wiring configuration or external circuitry for proper
> + sensor operation and can use different AD4170 functionality on their
> + setups. A key characteristic of those external sensors is that they must
> + be excited either by voltage supply or by AD4170 excitation signals. The
> + sensor can then be read through a pair of analog inputs. These properties
> + describe external sensor circuitry connected to the ADC.
> +
> + properties:
> + reg:
> + description:
> + Channel number. Connects the sensor to the channel with this number
> + of the device.
> + minimum: 1
> + maximum: 16
> +
> + diff-channels:
> + description:
> + Defines the ADC input pins used to read sensor data. Only regular
> + analog input pins can be used.
> + items:
> + enum: [0, 1, 2, 3, 4, 5, 6, 7, 8]
> +
> + bipolar: true
> +
> + adi,sensor-type:
> + description: |
> + Type of sensor connected to the device. Depending on the sensor type
> + (weigh scale, RTD, or thermocouple) the values of sensor-node
> + properties have slightly different constraints. This property
> + specifies which particular external sensor is connected to the ADC so
> + the sensor-node properties can be properly parsed and verified. The
> + possible sensor types are:
> + 0: weigh scale;
> + 1: RTD;
> + 2: thermocouple.
> + $ref: /schemas/types.yaml#/definitions/uint8
> +
> + adi,reference-select:
> + description: |
> + Selects the reference source to use when converting on the specific
> + channel. Valid values are:
> + 0: Differential reference voltage REFIN+ - REFIN−.
> + 1: Differential reference voltage REFIN2+ - REFIN2−.
> + 2: Internal 2.5V referece (REFOUT) relative to AVSS.
> + 3: Analog supply voltage (AVDD) relative AVSS.
> + $ref: /schemas/types.yaml#/definitions/uint8
> + enum: [0, 1, 2, 3]
> +
> + adi,excitation-ac:
> + type: boolean
> + description:
> + Whether the external sensor has to be AC or DC excited.
> +
> + adi,excitation-pins:
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + description:
> + Pins used to excite the sensor or external circuit that contains the
> + sensor. Thermocouples and RTD sensors are excited either with one
> + current source or with a pair of current sources to minimize the
> + excitation current mismatch and the excitation current drift matching
> + on the ADC. E.g. <0>; <1>; <0 1>. Load cell weigh scales may be
> + excited with one current source, a pair of excitation currents, or two
> + pairs of excitation currents. When four pins are defined, the first
> + two values specify the first pair and the last ones specify the second
> + pair of excitation currents. E.g. <0>; <0 1>; <0 1 2 3>.
> + items:
> + minimum: 0
> + maximum: 20
> +
> + adi,excitation-current-microamp:
> + description:
> + Excitation current in microamperes to be output to each excitation pin
> + specified by adi,excitation-pins property. If not provided and
> + adi,excitation-ac is true, use predefined ACX1, ACX1 negated, ACX2,
> + and ACX2 negated signals to AC excite the bridge circuit. Those
> + singals are output on GPIO2, GPIO0, GPIO3, and GPIO1, respectively.
> + enum: [0, 10, 50, 100, 250, 500, 1000, 1500]
> + default: 0
> +
> + adi,power-down-switch-pin:
> + description:
> + Number of the GPIO used as power-down switch for the bridge circuit.
> + $ref: /schemas/types.yaml#/definitions/uint8
> + enum: [0, 1]
> +
> + adi,vbias:
> + type: boolean
> + description:
> + For unbiased thermocouple applications, the voltage generated by the
> + thermocouple must be biased around some DC voltage. When present, this
> + property specifies a bias voltage of (AVDD + AVSS)/2 to be applied as
> + common-mode voltage for the sensor.
> +
> + required:
> + - reg
> + - diff-channels
> + - bipolar
> + - adi,sensor-type
> + - adi,reference-select
> +
> +
> +properties:
> + compatible:
> + enum:
> + - adi,ad4170
> + - adi,ad4190
> + - adi,ad4195
> +
> + avss-supply:
> + description:
> + Referece voltage supply for AVSS. If provided, describes the magnitude
> + (absolute value) of the negative voltage supplied to the AVSS pin. Since
> + AVSS must be −2.625V minimum and 0V maximum, the declared supply voltage
> + must be between 0 and 2.65V. If not provided, AVSS is assumed to be at
> + system ground (0V).
> +
> + avdd-supply:
> + description:
> + A supply of 4.75V to 5.25V relative to AVSS that powers the chip (AVDD).
> +
> + iovdd-supply:
> + description: 1.7V to 5.25V reference supply to the serial interface (IOVDD).
> +
> + refin1p-supply:
> + description: REFIN+ supply that can be used as reference for conversion.
> +
> + refin1n-supply:
> + description: REFIN- supply that can be used as reference for conversion. If
> + provided, describes the magnitude (absolute value) of the negative voltage
> + supplied to the REFIN- pin.
> +
> + refin2p-supply:
> + description: REFIN2+ supply that can be used as reference for conversion.
> +
> + refin2n-supply:
> + description: REFIN2- supply that can be used as reference for conversion. If
> + provided, describes the magnitude (absolute value) of the negative voltage
> + supplied to the REFIN2- pin.
> +
> + spi-cpol: true
> +
> + spi-cpha: true
> +
> + interrupts:
> + maxItems: 1
> +
> + interrupt-names:
> + description:
> + Specify which pin should be configured as Data Ready interrupt.
> + enum:
> + - sdo
> + - dig_aux1
> + default: sdo
> +
> + clocks:
> + maxItems: 1
> + description:
> + Optional external clock source. Can specify either an external clock or
> + external crystal.
> +
> + clock-names:
> + enum:
> + - ext-clk
> + - xtal
> + default: ext-clk
> +
> + '#clock-cells':
> + const: 0
> +
> + clock-output-names:
> + maxItems: 1
> +
> + gpio-controller: true
> +
> + "#gpio-cells":
> + const: 2
> + description: |
> + The first cell is for the GPIO number: 0 to 3.
> + The second cell takes standard GPIO flags.
> +
> + ldac-gpios:
> + description:
> + GPIO connected to DIG_AUX2 pin to be used as LDAC toggle to control the
> + transfer of data from the DAC_INPUT_A register to the DAC.
> + maxItems: 1
> +
> + '#address-cells':
> + const: 1
> +
> + '#size-cells':
> + const: 0
> +
> +patternProperties:
> + "^channel@[0-9a-f]$":
> + $ref: adc.yaml
> + type: object
> + unevaluatedProperties: false
> + description:
> + Represents the external channels which are connected to the ADC.
> +
> + properties:
> + reg:
> + description:
> + The channel number.
> + 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.
> +
> + Besides the analog input pins AIN0 to AIN8, there are special inputs
> + that can be selected with the following values:
> + 17: Internal temperature sensor
> + 18: (AVDD-AVSS)/5
> + 19: (IOVDD-DGND)/5
> + 20: DAC output
> + 21: ALDO
> + 22: DLDO
> + 23: AVSS
> + 24: DGND
> + 25: REFIN+
> + 26: REFIN-
> + 27: REFIN2+
> + 28: REFIN2-
> + 29: REFOUT
> + For the internal temperature sensor, use the input number for both
> + inputs (i.e. diff-channels = <17 17>).
> + items:
> + enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 17, 18, 19, 20, 21, 22, 23, 24, 25,
> + 26, 27, 28, 29]
> +
> + single-channel: true
> +
> + common-mode-channel: true
> +
> + bipolar: true
> +
> + adi,buffered-positive:
> + description: |
> + Enable precharge buffer, full buffer, or skip reference buffering of
> + the positive voltage reference. Because the output impedance of the
> + source driving the voltage reference inputs may be dynamic, RC
> + combinations of those inputs can cause DC gain errors if the reference
> + inputs go unbuffered into the ADC. Enable reference buffering if the
> + provided reference source has dynamic high impedance output. Note the
> + absolute voltage allowed on positive reference inputs (REFIN+,
> + REFIN2+) is from AVSS − 50 mV to AVDD + 50 mV when the reference
> + buffers are disabled but narrows to AVSS to AVDD when reference
> + buffering is enabled or in precharge mode.
> + 0: Reference precharge buffer.
> + 1: Full Buffer.
> + 2: Bypass reference buffers (buffering disabled).
> + $ref: /schemas/types.yaml#/definitions/uint8
> + enum: [0, 1, 2]
> + default: 1
> +
> + adi,buffered-negative:
> + description: |
> + Enable precharge buffer, full buffer, or skip reference buffering of
> + the negative voltage reference. Because the output impedance of the
> + source driving the voltage reference inputs may be dynamic, RC
> + combinations of those inputs can cause DC gain errors if the reference
> + inputs go unbuffered into the ADC. Enable reference buffering if the
> + provided reference source has dynamic high impedance output. Note the
> + absolute voltage allowed on negative reference inputs (REFIN-,
> + REFIN2-) is from AVSS − 50 mV to AVDD + 50 mV when the reference
> + buffers are disabled but narrows to AVSS to AVDD when reference
> + buffering is enabled or in precharge mode.
> + 0: Reference precharge buffer.
> + 1: Full Buffer.
> + 2: Bypass reference buffers (buffering disabled).
> + $ref: /schemas/types.yaml#/definitions/uint8
> + enum: [0, 1, 2]
> + default: 1
> +
> + adi,reference-select:
> + description: |
> + Select the reference source to use when converting on the specific
> + channel. Valid values are:
> + 0: Differential reference voltage REFIN+ - REFIN−.
> + 1: Differential reference voltage REFIN2+ - REFIN2−.
> + 2: Internal 2.5V referece (REFOUT) relative to AVSS.
> + 3: Analog supply voltage (AVDD) relative AVSS.
> + If this field is left empty, the internal reference is selected.
> + $ref: /schemas/types.yaml#/definitions/uint8

You already defined the type in the $defs, so no need to do it again.

> + enum: [0, 1, 2, 3]
> + default: 2
> +
> + required:
> + - reg
> +
> + allOf:

Don't need allOf.

> + - oneOf:
> + - required: [single-channel]
> + properties:
> + diff-channels: false
> + - required: [diff-channels]
> + properties:
> + single-channel: false
> + common-mode-channel: false
> +
> + "^weighscale@":
> + $ref: '#/$defs/sensor-node'
> + unevaluatedProperties: false
> +
> + properties:
> + diff-channels: true
> + bipolar: true
> +
> + adi,sensor-type:
> + description: Weigh scale sensor.
> + $ref: /schemas/types.yaml#/definitions/uint8

Already defined the type. And for the rest...

Rob