Add device tree documentation for AD4170 sigma-delta ADCs. Signed-off-by: Marcelo Schmitt <marcelo.schmitt@xxxxxxxxxx> --- .../bindings/iio/adc/adi,ad4170.yaml | 473 ++++++++++++++++++ 1 file changed, 473 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..8c5defc614ee --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4170.yaml @@ -0,0 +1,473 @@ +# 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 Analog to Digital Converter + +maintainers: + - Marcelo Schmitt <marcelo.schmitt@xxxxxxxxxx> + +description: | + Analog Devices AD4170 Analog to Digital Converter. + Specifications can be found at: + https://www.analog.com/media/en/technical-documentation/data-sheets/ad4170-4.pdf + +$ref: /schemas/spi/spi-peripheral-props.yaml# + +properties: + compatible: + enum: + - adi,ad4170 + + avss-supply: + description: + Referece voltage supply for AVDD. AVSS can be set below 0V to provide a + bipolar power supply to AD4170-4. Must be −2.625V at minimum, 0V maximum. + If not specified, this is assumed to be analog ground. + + 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. + + 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. + + interrupts: + maxItems: 1 + + 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 + + adi,gpio0-power-down-switch: + type: boolean + description: + Describes whether GPIO0 is used as a switch to disconnect bridge circuits + from AVSS. Pin defaults to GPIO if this property is not present. + + adi,gpio1-power-down-switch: + type: boolean + description: + Describes whether GPIO1 is used as a switch to disconnect bridge circuits + from AVSS. Pin defaults to GPIO if this property is not present. + + adi,vbias-pins: + description: Analog inputs to apply a voltage bias of (AVDD − AVSS) / 2 to. + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 9 + items: + minimum: 0 + maximum: 8 + + adi,dig-aux1: + description: + Describes whether DIG_AUX1 pin will operate as data ready output, + synchronization output signal (SYNC_OUT), or if it will be disabled. + A value of 0 indicates DIG_AUX1 pin disabled. High impedance. + A value of 1 indicates DIG_AUX1 is configured as ADC data ready output. + A value of 1 indicates DIG_AUX1 is configured as SYNC_OUT output. + If this property is absent, DIG_AUX1 pin is disabled. + $ref: /schemas/types.yaml#/definitions/uint8 + enum: [0, 1, 2] + default: 0 + + adi,dig-aux2: + description: + Describes whether DIG_AUX2 pin will function as DAC LDAC input, + synchronization start input (START), or if it will be disabled. + A value of 0 indicates DIG_AUX2 pin is disabled. High impedance. + A value of 1 indicates DIG_AUX2 pin is configured as active-low LDAC input + for the DAC. + A value of 2 indicates DIG_AUX2 pin is configured as START input. + If this property is absent, DIG_AUX2 pin is disabled. + $ref: /schemas/types.yaml#/definitions/uint8 + enum: [0, 1, 2] + default: 0 + + adi,sync-option: + description: + Describes how ADC conversions are going to be synchronized. A value of 1 + indicates the SYNC_IN pin will function as a synchronization input that + allows the user to control the start of sampling by pulling SYNC_IN high. + Use option number 2 to set the alternate synchronization functionality + which allows per channel conversion start control when multiple channels + are enabled. Option number 0 disables synchronization. + A value of 0 indicates no synchronization. SYNC_IN pin disabled. + A value of 1 indicates standard synchronization functionality. + A value of 2 indicates alternate synchronization functionality. + If this property is absent, no synchronization is performed. + $ref: /schemas/types.yaml#/definitions/uint8 + enum: [0, 1, 2] + default: 1 + + adi,excitation-pin-0: + description: | + Specifies the pin to apply excitation current 0 (IOUT0). Besides the + analog pins 0 to 8, the excitation current can be applied to GPIO pins. + 17: Output excitation current IOUT0 to GPIO0. + 18: Output excitation current IOUT0 to GPIO1. + 19: Output excitation current IOUT0 to GPIO2. + 20: Output excitation current IOUT0 to GPIO3. + If this property is absent, IOUT0 is not routed to any pin. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 17, 18, 19, 20] + default: 0 + + adi,excitation-pin-1: + description: | + Specifies the pin to apply excitation current 1 (IOUT1). Besides the + analog pins 0 to 8, the excitation current can be applied to GPIO pins. + 17: Output excitation current IOUT1 to GPIO0. + 18: Output excitation current IOUT1 to GPIO1. + 19: Output excitation current IOUT1 to GPIO2. + 20: Output excitation current IOUT1 to GPIO3. + If this property is absent, IOUT1 is not routed to any pin. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 17, 18, 19, 20] + default: 0 + + adi,excitation-pin-2: + description: | + Specifies the pin to apply excitation current 2 (IOUT2). Besides the + analog pins 0 to 8, the excitation current can be applied to GPIO pins. + 17: Output excitation current IOUT2 to GPIO0. + 18: Output excitation current IOUT2 to GPIO1. + 19: Output excitation current IOUT2 to GPIO2. + 20: Output excitation current IOUT2 to GPIO3. + If this property is absent, IOUT2 is not routed to any pin. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 17, 18, 19, 20] + default: 0 + + adi,excitation-pin-3: + description: | + Specifies the pin to apply excitation current 3 (IOUT3). Besides the + analog pins 0 to 8, the excitation current can be applied to GPIO pins. + 17: Output excitation current IOUT3 to GPIO0. + 18: Output excitation current IOUT3 to GPIO1. + 19: Output excitation current IOUT3 to GPIO2. + 20: Output excitation current IOUT3 to GPIO3. + If this property is absent, IOUT3 is not routed to any pin. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 17, 18, 19, 20] + default: 0 + + adi,excitation-current-0-microamp: + description: | + Excitation current in microamps to be applied to IOUT0 output pin + specified in adi,excitation-pin-0. + enum: [0, 10, 50, 100, 250, 500, 1000, 1500] + default: 0 + + adi,excitation-current-1-microamp: + description: | + Excitation current in microamps to be applied to IOUT1 output pin + specified in adi,excitation-pin-1. + enum: [0, 10, 50, 100, 250, 500, 1000, 1500] + default: 0 + + adi,excitation-current-2-microamp: + description: | + Excitation current in microamps to be applied to IOUT2 output pin + specified in adi,excitation-pin-2. + enum: [0, 10, 50, 100, 250, 500, 1000, 1500] + default: 0 + + adi,excitation-current-3-microamp: + description: | + Excitation current in microamps to be applied to IOUT3 output pin + specified in adi,excitation-pin-3. + enum: [0, 10, 50, 100, 250, 500, 1000, 1500] + default: 0 + + adi,chop-iexc: + description: | + Specifies the chopping/swapping functionality for excitation currents. + 0: No Chopping of Excitation Currents. + 1: Chop/swap IOUT0 and IOUT1 (pair AB) excitation currents. + 2: Chop/swap IOUT2 and IOUT3 (pair CD) excitation currents. + 3: Chop/swap both pairs (pair AB and pair CD) of excitation currents. + If this property is absent, no chopping is performed. + There are macros for the above values in dt-bindings/iio/adi,ad4170.h. + $ref: /schemas/types.yaml#/definitions/uint8 + enum: [0, 1, 2, 3] + default: 0 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +patternProperties: + "^channel@([0-9]|1[0-5])$": + $ref: adc.yaml + type: object + unevaluatedProperties: false + description: | + Represents the external channels which are connected to the ADC. + + properties: + reg: + description: | + The channel number. The device can have up to 16 channels numbered + from 0 to 15. + items: + 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: Temperature sensor input + 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 + + There are macros for those values in dt-bindings/iio/adi,ad4170.h. + + items: + minimum: 0 + maximum: 31 + + single-channel: true + + common-mode-channel: true + + bipolar: true + + adi,config-setup-number: + description: | + Specifies which of the 8 setups are used to configure the channel. + A setup comprises of: AFE, FILTER, FILTER_FS, MISC, OFFSET, and GAIN + registers. More than one channel can use the same configuration setup + number in which case they will share the settings of the above + mentioned registers. + items: + minimum: 0 + maximum: 7 + + adi,chop-adc: + description: | + Specifies the chopping/swapping functionality for a channel setup. + Macros for adi,chop-adc values are available in + dt-bindings/iio/adi,ad4170.h. When enabled, the analog inputs are + continuously swapped and a conversion is generated for each time a + swap occurs. The analog input pins are connected in one direction, + sampled, swapped, sampled again, and then the conversion results are + averaged. The input swap minimizes system offset and offset drift. + This property also specifies whether AC excitation using 2 or 4 GPIOs + are going to be used. + 0: No channel chop. + 1: Chop/swap the channel inputs. + 2: AC Excitation using 4 GPIOs. + 3: AC Excitation using 2 GPIOs. + If this property is absent, no chopping is performed. + $ref: /schemas/types.yaml#/definitions/uint16 + enum: [0, 1, 2, 3] + default: 0 + + adi,burnout-current-nanoamp: + description: | + Current in nanoamps to be applied for this channel. Burnout currents + are only active when the channel is selected for conversion. + enum: [0, 100, 2000, 10000] + default: 0 + + 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. + enum: [0, 1, 2] + default: 0 + + 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. + enum: [0, 1, 2] + default: 0 + + 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 relative AVSS. + If this field is left empty, the internal reference is selected. + $ref: /schemas/types.yaml#/definitions/uint8 + enum: [0, 1, 2, 3] + default: 2 + + required: + - reg + - adi,config-setup-number + + allOf: + - oneOf: + - required: [single-channel] + properties: + diff-channels: false + - required: [diff-channels] + properties: + single-channel: false + common-mode-channel: false + +required: + - compatible + - reg + - avdd-supply + - iovdd-supply + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/iio/adc/adi,ad4170.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "adi,ad4170"; + reg = <0>; + avdd-supply = <&avdd>; + iovdd-supply = <&iovdd>; + spi-max-frequency = <20000000>; + interrupt-parent = <&gpio_in>; + interrupts = <0 IRQ_TYPE_EDGE_FALLING>; + adi,dig-aux1 = /bits/ 8 <1>; + adi,dig-aux2 = /bits/ 8 <0>; + adi,sync-option = /bits/ 8 <0>; + adi,excitation-pin-0 = <19>; + adi,excitation-current-0-microamp = <10>; + adi,excitation-pin-1 = <20>; + adi,excitation-current-1-microamp = <10>; + adi,chop-iexc = /bits/ 8 <1>; + adi,vbias-pins = <5 6>; + #address-cells = <1>; + #size-cells = <0>; + + // Sample AIN0 with respect to AIN1 throughout AVDD/AVSS input range + // Fully differential. If AVSS < 0V, Fully differential true bipolar + channel@0 { + reg = <0>; + bipolar; + diff-channels = <AD4170_MAP_AIN0 AD4170_MAP_AIN1>; + adi,config-setup-number = <0>; + adi,reference-select = /bits/ 8 <3>; + adi,burnout-current-nanoamp = <100>; + }; + // Sample AIN2 with respect to DGND throughout AVDD/DGND input range + // Peseudo-differential unipolar (fig. 2a) + channel@1 { + reg = <1>; + single-channel = <AD4170_MAP_AIN2>; + common-mode-channel = <AD4170_MAP_DGND>; + adi,config-setup-number = <1>; + adi,reference-select = /bits/ 8 <3>; + }; + // Sample AIN3 with respect to 2.5V throughout AVDD/AVSS input range + // Pseudo-differential bipolar (fig. 2b) + channel@2 { + reg = <2>; + bipolar; + single-channel = <AD4170_MAP_AIN3>; + common-mode-channel = <AD4170_MAP_REFOUT>; + adi,config-setup-number = <2>; + adi,reference-select = /bits/ 8 <3>; + }; + // Sample AIN4 with respect to DGND throughout AVDD/AVSS input range + // Pseudo-differential true bipolar if AVSS < 0V (fig. 2c) + channel@3 { + reg = <3>; + bipolar; + single-channel = <AD4170_MAP_AIN4>; + common-mode-channel = <AD4170_MAP_DGND>; + adi,config-setup-number = <3>; + adi,reference-select = /bits/ 8 <3>; + }; + // Sample AIN5 with respect to 2.5V throughout AVDD/REFOUT input range + // Pseudo-differential unipolar (AD4170 datasheet page 46 example) + channel@4 { + reg = <4>; + single-channel = <AD4170_MAP_AIN5>; + common-mode-channel = <AD4170_MAP_REFOUT>; + adi,config-setup-number = <4>; + adi,reference-select = /bits/ 8 <2>; + }; + // Sample AIN6 with respect to REFIN+ throughout AVDD/AVSS input range + // Pseudo-differential unipolar + channel@5 { + reg = <5>; + single-channel = <AD4170_MAP_AIN6>; + common-mode-channel = <AD4170_MAP_REFIN1_P>; + adi,config-setup-number = <4>; + adi,reference-select = /bits/ 8 <2>; + }; + // Sample AIN7 with respect to DGND throughout REFIN+/REFIN- input range + // Pseudo-differential bipolar + channel@6 { + reg = <6>; + bipolar; + diff-channels = <AD4170_MAP_AIN7 AD4170_MAP_DGND>; + adi,config-setup-number = <5>; + adi,reference-select = /bits/ 8 <0>; + }; + }; + }; +... + -- 2.45.2
