On Wed, Dec 18, 2024 at 11:37:42AM -0300, Marcelo Schmitt wrote: > Add device tree documentation for AD4170 sigma-delta ADCs. > The usual question with long lists of properties. Any of these should be run-time controlled (by userspace) instead? If they might vary by the user for given h/w design, then should be user controlled instead. > 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: | Don't need '|' if no formatting to preserve. > + 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])$": Unit-addresses are typically hex, not decimal. > + $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. Don't need to say in prose what the schema says. IOW, drop the 2nd sentence. > + 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 >
