| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20241218194804.GA2203791-robh@kernel.org>
Date: Wed, 18 Dec 2024 13:48:04 -0600
From: Rob Herring <robh@...nel.org>
To: Marcelo Schmitt <marcelo.schmitt@...log.com>
Cc: linux-iio@...r.kernel.org, devicetree@...r.kernel.org,
linux-kernel@...r.kernel.org, jic23@...nel.org, lars@...afoo.de,
Michael.Hennerich@...log.com, krzk+dt@...nel.org,
conor+dt@...nel.org, ana-maria.cusco@...log.com,
marcelo.schmitt1@...il.com
Subject: Re: [RFC PATCH 2/4] dt-bindings: iio: adc: Add AD4170
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@...log.com>
> ---
> .../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@...log.com>
> +
> +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
>
Powered by blists - more mailing lists