Skip to contentSkip to conversation

dt-bindings: adc: add AD7173

PATCH Superseded Dumitru Ceclan 5 participants 11 messages Jan 18, 2024 – Jan 22, 2024

Subsystems (4)

v12 of 16 Superseded Latest is v16 →

lore
Share & tools
lore
#0 lore raw

PATCH v12 1/2 dt-bindings: adc: add AD7173

The AD7173 family offer a complete integrated Sigma-Delta ADC solution which can be used in high precision, low noise single channel applications or higher speed multiplexed applications. The Sigma-Delta ADC is intended primarily for measurement of signals close to DC but also delivers outstanding performance with input bandwidths out to ~10kHz.

---

V11->V12
- Drop "binding", describe hardware in binding description
- Rename refin and refin2 to vref and vref2
- Add better description to external references to better show that the voltage value that needs to be specified is the difference between the positive and negative reference pins
- Add optional clocks properties
- Add optional adi,clock-select property
- Add option for second interrupt, error
- Add description to interrupts
V10->V11
- Fix example warning: '#gpio-cells' is a dependency of 'gpio-controller'
- Add description to #gpio-cells property
V9->V10
- Fix dt_binding_check type warning from adi,reference-select
V8->v9
- Add gpio-controller and "#gpio-cells" properties
- Add missing avdd2 and iovdd supplies
- Add string type to reference-select
V7->V8
- include missing fix from V6
V6->V7 <no changes>
V5->V6
- Moved global required property to proper placement
V4 -> V5
- Use string enum instead of integers for "adi,reference-select"
- Fix conditional checking in regards to compatible
V3 -> V4
- include supply attributes
- add channel attribute for selecting conversion reference
V2 -> V3
- remove redundant descriptions
- use referenced 'bipolar' property
- remove newlines from example
V1 -> V2 <no changes>

 .../bindings/iio/adc/adi,ad7173.yaml          | 242 ++++++++++++++++++
 1 file changed, 242 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +242 -0
new file mode 100644
index 000000000000..4d0870cc014c
@@ -0,0 +1,242 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2023 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7173.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7173 ADC
+
+maintainers:
+  - Ceclan Dumitru <[email protected]>
+
+description: |
+  Analog Devices AD717x ADC's:
+  The AD717x family offer a complete integrated Sigma-Delta ADC solution which
+  can be used in high precision, low noise single channel applications
+  (Life Science measurements) or higher speed multiplexed applications
+  (Factory Automation PLC Input modules). The Sigma-Delta ADC is intended
+  primarily for measurement of signals close to DC but also delivers
+  outstanding performance with input bandwidths out to ~10kHz.
+
+  Datasheets for supported chips:
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7172-2.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7173-8.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7175-2.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7176-2.pdf
+
+properties:
+  compatible:
+    enum:
+      - adi,ad7172-2
+      - adi,ad7173-8
+      - adi,ad7175-2
+      - adi,ad7176-2
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    minItems: 1
+    description: |
+      Ready interrupt: multiplexed with SPI data out. While SPI CS is low,
+      can be used to indicate the completion of a conversion.
+
+      Error: The three error bits in the status register (ADC_ERROR, CRC_ERROR,
+      and REG_ERROR) are OR'ed, inverted, and mapped to the ERROR pin. Therefore,
+      the ERROR pin indicates that an error has occurred.
+
+  interrupt-names:
+    minItems: 1
+    items:
+      - const: rdy
+      - const: err
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0
+
+  spi-max-frequency:
+    maximum: 20000000
+
+  gpio-controller:
+    description: Marks the device node as a GPIO controller.
+
+  "#gpio-cells":
+    const: 2
+    description:
+      The first cell is the GPIO number and the second cell specifies
+      GPIO flags, as defined in <dt-bindings/gpio/gpio.h>.
+
+  vref-supply:
+    description: |
+      Differential external reference supply used for conversion. The reference
+      voltage (Vref) specified here must be the voltage difference between the
+      REF+ and REF- pins: Vref = (REF+) - (REF-).
+
+  vref2-supply:
+    description: |
+      Differential external reference supply used for conversion. The reference
+      voltage (Vref2) specified here must be the voltage difference between the
+      REF2+ and REF2- pins: Vref2 = (REF2+) - (REF2-).
+
+  avdd-supply:
+    description: avdd supply, can be used as reference for conversion.
+
+  avdd2-supply:
+    description: avdd2 supply, used as the input to the internal voltage regulator.
+
+  iovdd-supply:
+    description: iovdd supply, used for the chip digital interface.
+
+  clocks:
+    maxItems: 1
+    description: |
+      Optional external clock source. Can include one clock source: external
+      clock or external crystal.
+
+  clock-names:
+    enum:
+      - ext-clk
+      - xtal
+
+  adi,clock-select:
+    description: |
+      Select the ADC clock source. Valid values are:
+      int         : Internal oscillator
+      int-out     : Internal oscillator with output on XTAL2 pin
+      ext-clk     : External clock input on XTAL2 pin
+      xtal        : External crystal on XTAL1 and XTAL2 pins
+
+    $ref: /schemas/types.yaml#/definitions/string
+    enum:
+      - int
+      - int-out
+      - ext-clk
+      - xtal
+    default: int
+
+patternProperties:
+  "^channel@[0-9a-f]$":
+    type: object
+    $ref: adc.yaml
+    unevaluatedProperties: false
+
+    properties:
+      reg:
+        minimum: 0
+        maximum: 15
+
+      diff-channels:
+        items:
+          minimum: 0
+          maximum: 31
+
+      adi,reference-select:
+        description: |
+          Select the reference source to use when converting on
+          the specific channel. Valid values are:
+          vref       : REF+  /REF−
+          vref2      : REF2+ /REF2−
+          refout-avss: REFOUT/AVSS (Internal reference)
+          avdd       : AVDD
+
+          External reference ref2 only available on ad7173-8.
+          If not specified, internal reference used.
+        $ref: /schemas/types.yaml#/definitions/string
+        enum:
+          - vref
+          - vref2
+          - refout-avss
+          - avdd
+        default: refout-avss
+
+    required:
+      - reg
+      - diff-channels
+
+required:
+  - compatible
+  - reg
+
+allOf:
+  - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+  - if:
+      properties:
+        compatible:
+          not:
+            contains:
+              const: adi,ad7173-8
+    then:
+      properties:
+        vref2-supply: false
+      patternProperties:
+        "^channel@[0-9a-f]$":
+          properties:
+            adi,reference-select:
+              enum:
+                - vref
+                - refout-avss
+                - avdd
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    spi {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      adc@0 {
+        compatible = "adi,ad7173-8";
+        reg = <0>;
+
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+        interrupt-names = "rdy";
+        interrupt-parent = <&gpio>;
+        spi-max-frequency = <5000000>;
+        gpio-controller;
+        #gpio-cells = <2>;
+
+        vref-supply = <&dummy_regulator>;
+
+        channel@0 {
+          reg = <0>;
+          bipolar;
+          diff-channels = <0 1>;
+          adi,reference-select = "vref";
+        };
+
+        channel@1 {
+          reg = <1>;
+          diff-channels = <2 3>;
+        };
+
+        channel@2 {
+          reg = <2>;
+          bipolar;
+          diff-channels = <4 5>;
+        };
+
+        channel@3 {
+          reg = <3>;
+          bipolar;
+          diff-channels = <6 7>;
+        };
+
+        channel@4 {
+          reg = <4>;
+          diff-channels = <8 9>;
+          adi,reference-select = "avdd";
+        };
+      };
+    };
Signature · 1 line
2.42.0
#1 lore raw

PATCH v12 2/2 iio: adc: ad7173: add AD7173 driver

The AD7173 family offer a complete integrated Sigma-Delta ADC solution which can be used in high precision, low noise single channel applications or higher speed multiplexed applications. The Sigma-Delta ADC is intended primarily for measurement of signals close to DC but also delivers outstanding performance with input bandwidths out to ~10kHz.

---

V11-> V12
- rename refin, refin2 to vref, vref2
V10-> V11 <no changes>
V9 -> V10 <no changes>
V8 -> V9
- Add '(x)' to some macro's definition to reduce NO of checks
- Use reg 0 constant definition in debug_reg_access()
- Rename channels_st_priv_arr to chans_st_arr
- Remove unnecessary u32 cast from read_raw()
- Compute read_raw() offset instead of constant
- Add offset comments to data rate arrays
- Removed redundant newline in _parse_channel_config()
V7 -> V8
- remove Kconfig commas
- reorder include <...gpio/regmap.h>
- GPO12_DATA(x) from BIT(x) -> BIT(x+0)
- use the same pointer to dev in ad7173_setup()
- rewrite temp channel read_raw scale for better readability
- add comment to explain temp channel offset
- follow multi-line comment style
- change ref_sel type to signed int
- use fwnode_property_match_property_string()
V6 -> V7
- format Kconfig supported models using '-'
- include types.h instead of stddef.h
- change device_info->num_gpios type to u8
- reorder fields in ad7173_state, place ad_sigma_delta
- reorder fields in ad7173_device_info, group by type
- add default case in read_raw()
- rename ad7173_debug() to ad7173_debug_reg_access()
- remove explicit u8 cast
- remove return 0; for offset in read_raw()
- add '\n' to error messages
- reorder probe variables -> reversed xmas tree
- remove redundant inner commas in of_match and id_table
- simplify selected reference code by setting default value and ignoring fwnode_property_read_string() error
- use match_string() for finding selected reference
- err on no channels specified
- add missing fwnode_handle_put(child) on err return branches
- remove spi_set_drvdata() from probe
- remove offset variable from find_live_config(), not used
- add comment showing a generic LRU implementation might be used if one
will exist
- MISC: add blank line to chanel_config struct, trailing comma ref_sel_str[], remove blank line in update_scan_mode(), add spaces around '/'
V5->V6 <no changes>
V4 -> V5
- List Kconfig supported models one per line
- Include <array_size.h> and <container_of.h>
- Remove bits.h and kernel.h include
- Add spaces before '\' on multi-line definitions
- Change constant definition name from "..._MICROV" to "..._uV"
- Change ad7173_channel_config attributes order for grouping by type
- Remove redundant {} in ad7173_gpio_init()
- Add array with reference select strings
- Change parsing of device tree adi,reference-select from integer to string
- Change indentation for ad7173_find_live_config() header
- Use struct_group() in config struct
- Use offsetofend() and sizeof_field() in ad7173_find_live_config()
- Split line on logic operator in ad7173_find_live_config() at configs comparison
- Use IDA for config slots allocation
- Reverse xmas tree order for probe local variables
- Use BIT() for computing bipolar channels offset
- Change (MICRO/MILLI) to MILLI in read_raw for integer part of sampling frequency
- MISC: remove blank line, use 0 value dirrectly, one line statement devm_kcalloc()
V3 -> V4
- cleaned up includes
- add ad7173_gpio_disable(), include to devm actions
- remove iio_device_claim_direct_mode() from update_scan_mode()
- always set differential iio_chan attribute to true, retain bipolar info only in private struct
- store multiple regulators in state for voltage references
- compute read_raw offset depending on channel used reference
- configure channel setup using selected reference
- add ad7173_get_ref_voltage_milli()
- clean up ad7173_fw_sparse_channel_config() changing array access of channel structs to pointers
- retain chip name in st->info structure
- use spi_device_get_match_data() in probe
V2 -> V3
- change Kconfig GPIO_REGMAP and REGMAP_SPI to be conditioned by GPIOLIB
- cast chip info to (kernel_ulong_t) to suppress warnings
- adjust copyright year to reflect the out-of-tree history
- remove unused sysfs and trigger header files
- clean up defined macros by using FIELD_PREP( ) inline
- use DECLARE_BITMAP( ) for defiining cfg_slots_status
- use clear/set _bit instead of assign_bit
- rename state field regmap to reg_gpiocon_regmap to better represent usage
- replace container_of( ) usages to ad_sigma_delta_to_ad7173( )
- improve readability of sampling frequency conversion in write_raw( )
specifying conversion from Micro to Milli
- use iio_device_claim_direct_mode( ) correctly in write_raw( )
- flip logic in write_raw( ) to reduce line length
- pass only state struct to gpio_init function
- remove else branch at end of probe
- remove comma after list terminator for of_match and id_table arrays
- clarify write_raw( ) realbits 32 bit size check in a comment
- change parsed fw property 'adi,bipolar' to 'bipolar' to matched referenced adc.yaml
- use reg_set_base for gpio regmap xlate
V1 -> V2
- keep original out-of-tree AD7173 naming
- remove gpio_cleanup
- handle 32bit realbits offset case
- use iio_device_claim_direct_mode, drop own mutex
- use dev_err_probe
- cleanup headers include
- use GENMASK() and FIELD_PREP()
- use HZ_PER_MHZ
- change #ifdef GPIOLIB to if( IS_ENABLED(CONFIG_GPIOLIB))
- use gpio-regmap
- change boolean flag in info struct to number of gpios
- NIH memset64
- use struct pointers for config comparison
- use spi_write_then_read for ADC reset
- use stack allocated buffer for reset
- define constant for reset sequence size
- use kcalloc instead of kzalloc
- change of naming to fw of dt parse function
- change de-referencing chain to local variable dev in multiple locations
- drop write_raw_get_fmt
- add driver private data to spi_device_id table
- use fsleep() instead of usleep_range()
- put config value inline
- align read/write raw arguments
- remove zeroed values from channel templates structure
- define constants for temperature sensor positive and negative inputs
- always enable temperature channel
- configure spi clock phase and polarity from driver
misc changes (test bit, return disable all, indentation fix, change statements to single line)

 drivers/iio/adc/Kconfig  |  17 +
 drivers/iio/adc/Makefile |   1 +
 drivers/iio/adc/ad7173.c | 974 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 992 insertions(+)
 create mode 100644 drivers/iio/adc/ad7173.c
drivers/iio/adc/Kconfig +17 -0
index 3b73c509bd68..c32054afdfc4 100644
@@ -70,6 +70,23 @@ config AD7124
 	  To compile this driver as a module, choose M here: the module will be
 	  called ad7124.
 
+config AD7173
+	tristate "Analog Devices AD7173 driver"
+	depends on SPI_MASTER
+	select AD_SIGMA_DELTA
+	select GPIO_REGMAP if GPIOLIB
+	select REGMAP_SPI if GPIOLIB
+	help
+	  Say yes here to build support for Analog Devices AD7173 and similar ADC
+	  Currently supported models:
+	   - AD7172-2
+	   - AD7173-8
+	   - AD7175-2
+	   - AD7176-2
+
+	  To compile this driver as a module, choose M here: the module will be
+	  called ad7173.
+
 config AD7192
 	tristate "Analog Devices AD7190 AD7192 AD7193 AD7195 ADC driver"
 	depends on SPI
drivers/iio/adc/Makefile +1 -0
index d2fda54a3259..dd4210a3634f 100644
@@ -11,6 +11,7 @@ obj-$(CONFIG_AD7091R) += ad7091r-base.o
 obj-$(CONFIG_AD7091R5) += ad7091r5.o
 obj-$(CONFIG_AD7091R8) += ad7091r8.o
 obj-$(CONFIG_AD7124) += ad7124.o
+obj-$(CONFIG_AD7173) += ad7173.o
 obj-$(CONFIG_AD7192) += ad7192.o
 obj-$(CONFIG_AD7266) += ad7266.o
 obj-$(CONFIG_AD7280) += ad7280a.o
drivers/iio/adc/ad7173.c new file +974 -0

974 lines not on this page · raw message

Signature · 1 line
2.42.0
maintainer
#2 lore raw

Re: [PATCH v12 2/2] iio: adc: ad7173: add AD7173 driver

Quoted 9 lines · On Thu, 18 Jan 2024 14:49:23 +0200 Dumitru Ceclan <[email protected]>…

The AD7173 family offer a complete integrated Sigma-Delta ADC solution which can be used in high precision, low noise single channel applications or higher speed multiplexed applications. The Sigma-Delta ADC is intended primarily for measurement of signals close to DC but also delivers outstanding performance with input bandwidths out to ~10kHz.

One comment following through from adding the named irq support to the binding. The driver needs to check that it has the right one as perhaps only the error one is wired, or it is the first one specified in the binding.

Quoted 27 lines
drivers/iio/adc/ad7173.c new file +27 -0
+static int ad7173_probe(struct spi_device *spi)
+{
+	struct device *dev = &spi->dev;
+	struct ad7173_state *st;
+	struct iio_dev *indio_dev;
+	int ret;
+
+	indio_dev = devm_iio_device_alloc(dev, sizeof(*st));
+	if (!indio_dev)
+		return -ENOMEM;
+
+	st = iio_priv(indio_dev);
+	st->info = spi_get_device_match_data(spi);
+	if (!st->info)
+		return -ENODEV;
+
+	ida_init(&st->cfg_slots_status);
+	ret = devm_add_action_or_reset(dev, ad7173_ida_destroy, st);
+	if (ret)
+		return ret;
+
+	indio_dev->name = st->info->name;
+	indio_dev->modes = INDIO_DIRECT_MODE;
+	indio_dev->info = &ad7173_info;
+
+	spi->mode = SPI_MODE_3;
+

drivers/iio/adc/ad7173.c line 921

Quoted 10 lines
drivers/iio/adc/ad7173.c new file +10 -0
+	ad7173_sigma_delta_info.num_slots = st->info->num_configs;
+	ret = ad_sd_init(&st->sd, indio_dev, spi, &ad7173_sigma_delta_info);
+	if (ret)
+		return ret;
+
+	ret = ad7173_fw_parse_channel_config(indio_dev);
+	if (ret)
+		return ret;
+
+	ret = devm_ad_sd_setup_buffer_and_trigger(dev, indio_dev);

If the error interrupt is provided either first, or as the only interrupt this is going to use the wrong one.

Probably need to have a variant of that which takes an explicit irq so that figuring out which irq is relevant becomes a driver problem rather than the library having a go based on spi->irq.

Quoted 16 lines
drivers/iio/adc/ad7173.c new file +16 -0
+	if (ret)
+		return ret;
+
+	ret = ad7173_setup(indio_dev);
+	if (ret)
+		return ret;
+
+	ret = devm_iio_device_register(dev, indio_dev);
+	if (ret)
+		return ret;
+
+	if (IS_ENABLED(CONFIG_GPIOLIB))
+		return ad7173_gpio_init(st);
+
+	return 0;
+}
#3 lore raw

Re: [PATCH v12 2/2] iio: adc: ad7173: add AD7173 driver

Quoted 7 lines · Jonathan Cameron

drivers/iio/adc/ad7173.c line 921

Quoted 1 line
drivers/iio/adc/ad7173.c new file +1 -0
+	ret = devm_ad_sd_setup_buffer_and_trigger(dev, indio_dev);

If the error interrupt is provided either first, or as the only interrupt this is going to use the wrong one.

Probably need to have a variant of that which takes an explicit irq so that figuring out which irq is relevant becomes a driver problem rather than the library having a go based on spi->irq.

Would it be acceptable to check if spi->irq interrupt number is equal to fwnode_irq_get_byname(dev_fwnode(dev), "rdy")?

If not, a message could be passed that specifies either that "rdy" is needed or that it must be placed first.

Another alternative would be adding irq to ad_sigma_delta_info so a driver could specify the desired interrupt to be used for conversions.

#4 lore raw

Re: [PATCH v12 2/2] iio: adc: ad7173: add AD7173 driver

Quoted 11 lines · On Mon, 22 Jan 2024 12:02:35 +0200 Ceclan Dumitru <[email protected]>…
Quoted 7 lines · Jonathan Cameron

drivers/iio/adc/ad7173.c line 921

Quoted 1 line
drivers/iio/adc/ad7173.c new file +1 -0
+	ret = devm_ad_sd_setup_buffer_and_trigger(dev, indio_dev);  

If the error interrupt is provided either first, or as the only interrupt this is going to use the wrong one.

Probably need to have a variant of that which takes an explicit irq so that figuring out which irq is relevant becomes a driver problem rather than the library having a go based on spi->irq.

Would it be acceptable to check if spi->irq interrupt number is equal to fwnode_irq_get_byname(dev_fwnode(dev), "rdy")?

That would be a good start and probably cover most cases.

Quoted 3 lines

If not, a message could be passed that specifies either that "rdy" is needed or that it must be placed first.

If you are mandating the order, that should possibly be reflected in the binding. If this was hard to fix, I'd be fine with leaving for when someone runs into a case where they have it ordered the other way around, but given it seems simple to fix up probably better to just do it and avoid having to remember anything about it later.

Quoted 5 lines

Another alternative would be adding irq to ad_sigma_delta_info so a driver could specify the desired interrupt to be used for conversions.

That works. Make it optional so if value is 0 use spi->irq as before so that you don't need to modify the other drivers.

Jonathan

#5 lore raw
In reply to Dumitru Ceclan
Quoted 92 lines · Dumitru Ceclan

The AD7173 family offer a complete integrated Sigma-Delta ADC solution which can be used in high precision, low noise single channel applications or higher speed multiplexed applications. The Sigma-Delta ADC is intended primarily for measurement of signals close to DC but also delivers outstanding performance with input bandwidths out to ~10kHz.

---

V11->V12
- Drop "binding", describe hardware in binding description
- Rename refin and refin2 to vref and vref2
- Add better description to external references to better show that the voltage value that needs to be specified is the difference between the positive and negative reference pins
- Add optional clocks properties
- Add optional adi,clock-select property
- Add option for second interrupt, error
- Add description to interrupts
V10->V11
- Fix example warning: '#gpio-cells' is a dependency of 'gpio-controller'
- Add description to #gpio-cells property
V9->V10
- Fix dt_binding_check type warning from adi,reference-select
V8->v9
- Add gpio-controller and "#gpio-cells" properties
- Add missing avdd2 and iovdd supplies
- Add string type to reference-select
V7->V8
- include missing fix from V6
V6->V7 <no changes>
V5->V6
- Moved global required property to proper placement
V4 -> V5
- Use string enum instead of integers for "adi,reference-select"
- Fix conditional checking in regards to compatible
V3 -> V4
- include supply attributes
- add channel attribute for selecting conversion reference
V2 -> V3
- remove redundant descriptions
- use referenced 'bipolar' property
- remove newlines from example
V1 -> V2 <no changes>

 .../bindings/iio/adc/adi,ad7173.yaml          | 242 ++++++++++++++++++
 1 file changed, 242 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +37 -0
new file mode 100644
index 000000000000..4d0870cc014c
@@ -0,0 +1,242 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2023 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7173.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7173 ADC
+
+maintainers:
+  - Ceclan Dumitru <[email protected]>
+
+description: |
+  Analog Devices AD717x ADC's:
+  The AD717x family offer a complete integrated Sigma-Delta ADC solution which
+  can be used in high precision, low noise single channel applications
+  (Life Science measurements) or higher speed multiplexed applications
+  (Factory Automation PLC Input modules). The Sigma-Delta ADC is intended
+  primarily for measurement of signals close to DC but also delivers
+  outstanding performance with input bandwidths out to ~10kHz.
+
+  Datasheets for supported chips:
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7172-2.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7173-8.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7175-2.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7176-2.pdf
+
+properties:
+  compatible:
+    enum:
+      - adi,ad7172-2
+      - adi,ad7173-8
+      - adi,ad7175-2
+      - adi,ad7176-2
+
+  reg:
+    maxItems: 1

Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml line 47

Quoted 10 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +10 -0
+
+  interrupts:
+    minItems: 1
+    description: |
+      Ready interrupt: multiplexed with SPI data out. While SPI CS is low,
+      can be used to indicate the completion of a conversion.
+
+      Error: The three error bits in the status register (ADC_ERROR, CRC_ERROR,
+      and REG_ERROR) are OR'ed, inverted, and mapped to the ERROR pin. Therefore,
+      the ERROR pin indicates that an error has occurred.

Instead of having a single description like this, you can create an items list with two descriptions, one for each interrupt.

Quoted 23 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +22 -0
+
+  interrupt-names:
+    minItems: 1
+    items:
+      - const: rdy
+      - const: err
 
+  clocks:
+    maxItems: 1
+    description: |
+      Optional external clock source. Can include one clock source: external
+      clock or external crystal.
+
+  clock-names:
+    enum:
+      - ext-clk
+      - xtal
+
+  adi,clock-select:
+    description: |
+      Select the ADC clock source. Valid values are:
+      int         : Internal oscillator
+      int-out     : Internal oscillator with output on XTAL2 pin

Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml line 119

Quoted 10 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +10 -0
+      ext-clk     : External clock input on XTAL2 pin
+      xtal        : External crystal on XTAL1 and XTAL2 pins
+
+    $ref: /schemas/types.yaml#/definitions/string
+    enum:
+      - int
+      - int-out
+      - ext-clk
+      - xtal
+    default: int

I am not a fan of properties like this one, that in my view reimplement things that are supported by the regular clocks properties. I've got some questions for you so I can understand whether or not this custom property is required.

Whether or not the ext-clk or xtal is used is known based on clock-names - why is the custom property required to determine that? If neither of those clocks are present, then the internal clock would be used. Choosing to use the internal clock if an external one is provided sounds to me like a software policy decision made by the operating system.

Finally, if the ADC has a clock output, why can that not be represented by making the ADC a clock-controller?

Cheers,
Conor.

#6 lore raw
Quoted 1 line · Conor Dooley

On Thu, Jan 18, 2024 at 02:49:22PM +0200, Dumitru Ceclan wrote:

...

Quoted 20 lines
Quoted 5 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +5 -0
+  adi,clock-select:
+    description: |
+      Select the ADC clock source. Valid values are:
+      int         : Internal oscillator
+      int-out     : Internal oscillator with output on XTAL2 pin

Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml line 119

Quoted 10 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +10 -0
+      ext-clk     : External clock input on XTAL2 pin
+      xtal        : External crystal on XTAL1 and XTAL2 pins
+
+    $ref: /schemas/types.yaml#/definitions/string
+    enum:
+      - int
+      - int-out
+      - ext-clk
+      - xtal
+    default: int

I am not a fan of properties like this one, that in my view reimplement things that are supported by the regular clocks properties. I've got some questions for you so I can understand whether or not this custom property is required.

Quoted 6 lines

Whether or not the ext-clk or xtal is used is known based on clock-names - why is the custom property required to determine that? If neither of those clocks are present, then the internal clock would be used. Choosing to use the internal clock if an external one is provided sounds to me like a software policy decision made by the operating system.

If there was no int-out, sure. I considered that the choice between int and int-out could be made here. So better for driver to choose int/int-out?

Quoted 4 lines

Finally, if the ADC has a clock output, why can that not be represented by making the ADC a clock-controller?

Was not familiar with this/did not cross my mind. So if xtal/ext-clk is present, the driver should detect it and disable the option for clock output? (Common pin XTAL2)

#7 lore raw
Quoted 30 lines · Ceclan Dumitru
Quoted 1 line · Conor Dooley

On Thu, Jan 18, 2024 at 02:49:22PM +0200, Dumitru Ceclan wrote:

...

Quoted 22 lines
Quoted 5 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +5 -0
+  adi,clock-select:
+    description: |
+      Select the ADC clock source. Valid values are:
+      int         : Internal oscillator
+      int-out     : Internal oscillator with output on XTAL2 pin

Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml line 119

Quoted 10 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +10 -0
+      ext-clk     : External clock input on XTAL2 pin
+      xtal        : External crystal on XTAL1 and XTAL2 pins
+
+    $ref: /schemas/types.yaml#/definitions/string
+    enum:
+      - int
+      - int-out
+      - ext-clk
+      - xtal
+    default: int

I am not a fan of properties like this one, that in my view reimplement things that are supported by the regular clocks properties. I've got some questions for you so I can understand whether or not this custom property is required.

Whether or not the ext-clk or xtal is used is known based on clock-names - why is the custom property required to determine that?

Quoted 7 lines
Quoted 4 lines

If neither of those clocks are present, then the internal clock would be used. Choosing to use the internal clock if an external one is provided sounds to me like a software policy decision made by the operating system.

If there was no int-out, sure. I considered that the choice between int and int-out could be made here. So better for driver to choose int/int-out?

This part of my comments was specifically about choosing between use of the internal clock when ext-clk or xtal are provided, which I think excludes the possibility of using int-out, since the XTAL2 pin is an input.

There's 3 situations:
- no external clock provided
- ext-clk provided
- xtal provided

For the former, you know you're in that state when no "clocks" property is present. The latter two you can differentiate based on "clock-names".

Choosing to use the internal clock if an external clock is provided seems to be a software policy decision, unless I am mistaken.

Quoted 8 lines
Quoted 4 lines

Finally, if the ADC has a clock output, why can that not be represented by making the ADC a clock-controller?

Was not familiar with this/did not cross my mind. So if xtal/ext-clk is present, the driver should detect it and disable the option for clock output? (Common pin XTAL2)

Yeah, if those clocks are provided you would not register as a clock controller. If there is a user of the output clock, it should have its own "clocks" property that references the ADC's output.

Your dt-binding could also make clocks/clock-names & clock-controller mutually exclusive.

Cheers,
Conor.

maintainer
#8 lore raw
Quoted 49 lines · On Thu, 18 Jan 2024 16:06:29 +0000 Conor Dooley <[email protected]> wrote:
Quoted 30 lines · Ceclan Dumitru
Quoted 1 line · Conor Dooley

On Thu, Jan 18, 2024 at 02:49:22PM +0200, Dumitru Ceclan wrote:

...

Quoted 22 lines
Quoted 5 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +5 -0
+  adi,clock-select:
+    description: |
+      Select the ADC clock source. Valid values are:
+      int         : Internal oscillator
+      int-out     : Internal oscillator with output on XTAL2 pin

Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml line 119

Quoted 10 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +10 -0
+      ext-clk     : External clock input on XTAL2 pin
+      xtal        : External crystal on XTAL1 and XTAL2 pins
+
+    $ref: /schemas/types.yaml#/definitions/string
+    enum:
+      - int
+      - int-out
+      - ext-clk
+      - xtal
+    default: int  

I am not a fan of properties like this one, that in my view reimplement things that are supported by the regular clocks properties. I've got some questions for you so I can understand whether or not this custom property is required.

Whether or not the ext-clk or xtal is used is known based on clock-names - why is the custom property required to determine that?

Quoted 7 lines
Quoted 4 lines

If neither of those clocks are present, then the internal clock would be used. Choosing to use the internal clock if an external one is provided sounds to me like a software policy decision made by the operating system.

If there was no int-out, sure. I considered that the choice between int and int-out could be made here. So better for driver to choose int/int-out?

This part of my comments was specifically about choosing between use of the internal clock when ext-clk or xtal are provided, which I think excludes the possibility of using int-out, since the XTAL2 pin is an input.

There's 3 situations:
- no external clock provided
- ext-clk provided
- xtal provided

Quoted 5 lines

For the former, you know you're in that state when no "clocks" property is present. The latter two you can differentiate based on "clock-names".

Choosing to use the internal clock if an external clock is provided seems to be a software policy decision, unless I am mistaken.

Agreed, though it rarely makes sense as if someone put down a precision clock they normally wanted you to use it!

So as a general rule we don't both providing policy controls beyond if there is extra hardware (external clock source) then use that.

If someone has a good reason to want to do something else then we can probably figure out a reasonable way to control it.

Quoted 10 lines
Quoted 9 lines
Quoted 5 lines

Finally, if the ADC has a clock output, why can that not be represented by making the ADC a clock-controller?

Was not familiar with this/did not cross my mind. So if xtal/ext-clk is present, the driver should detect it and disable the option for clock output? (Common pin XTAL2)

Quoted 6 lines

Yeah, if those clocks are provided you would not register as a clock controller. If there is a user of the output clock, it should have its own "clocks" property that references the ADC's output.

Your dt-binding could also make clocks/clock-names & clock-controller mutually exclusive.

That would indeed be the nicest solution. How this has been done in drivers has somewhat 'evolved' over time, but this is the nicest option from point of view of standard bindings and clarity over what is going on.

Quoted 3 lines

Cheers,
Conor.

#9 lore raw
Quoted 52 lines · Jonathan Cameron
Quoted 44 lines · On Thu, 18 Jan 2024 16:06:29 +0000 Conor Dooley <[email protected]> wrote:
Quoted 25 lines · Ceclan Dumitru
Quoted 23 lines · Conor Dooley
Quoted 5 lines · Dumitru Ceclan
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +5 -0
+  adi,clock-select:
+    description: |
+      Select the ADC clock source. Valid values are:
+      int         : Internal oscillator
+      int-out     : Internal oscillator with output on XTAL2 pin

Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml line 119

Quoted 10 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +10 -0
+      ext-clk     : External clock input on XTAL2 pin
+      xtal        : External crystal on XTAL1 and XTAL2 pins
+
+    $ref: /schemas/types.yaml#/definitions/string
+    enum:
+      - int
+      - int-out
+      - ext-clk
+      - xtal
+    default: int  

I am not a fan of properties like this one, that in my view reimplement things that are supported by the regular clocks properties. I've got some questions for you so I can understand whether or not this custom property is required.

Whether or not the ext-clk or xtal is used is known based on clock-names - why is the custom property required to determine that?

Quoted 7 lines
Quoted 4 lines

If neither of those clocks are present, then the internal clock would be used. Choosing to use the internal clock if an external one is provided sounds to me like a software policy decision made by the operating system.

If there was no int-out, sure. I considered that the choice between int and int-out could be made here. So better for driver to choose int/int-out?

This part of my comments was specifically about choosing between use of the internal clock when ext-clk or xtal are provided, which I think excludes the possibility of using int-out, since the XTAL2 pin is an input.

There's 3 situations:
- no external clock provided
- ext-clk provided
- xtal provided

Quoted 5 lines

For the former, you know you're in that state when no "clocks" property is present. The latter two you can differentiate based on "clock-names".

Choosing to use the internal clock if an external clock is provided seems to be a software policy decision, unless I am mistaken.

Quoted 8 lines

Agreed, though it rarely makes sense as if someone put down a precision clock they normally wanted you to use it!

So as a general rule we don't both providing policy controls beyond if there is extra hardware (external clock source) then use that.

If someone has a good reason to want to do something else then we can probably figure out a reasonable way to control it.

Yah, I figured there'd be few situations, outside of maybe debugging hardware issues, where that internal clock is more desirable to use.

Quoted 12 lines
Quoted 12 lines
Quoted 7 lines
Quoted 3 lines

Finally, if the ADC has a clock output, why can that not be represented by making the ADC a clock-controller?

Was not familiar with this/did not cross my mind. So if xtal/ext-clk is present, the driver should detect it and disable the option for clock output? (Common pin XTAL2)

Yeah, if those clocks are provided you would not register as a clock controller. If there is a user of the output clock, it should have its own "clocks" property that references the ADC's output.

Quoted 7 lines
Quoted 2 lines

Your dt-binding could also make clocks/clock-names & clock-controller mutually exclusive.

That would indeed be the nicest solution. How this has been done in drivers has somewhat 'evolved' over time, but this is the nicest option from point of view of standard bindings and clarity over what is going on.

Yeah, I know that this has not really been normal thing to do in some corners of the kernel (ethernet PHYs in particular I think have been rolling their own clock controller stuff) and I've been trying to push back on these kinds of things for new devices.

Thanks,
Conor.

reviewer
#10 lore raw
In reply to Dumitru Ceclan
Quoted 132 lines · Dumitru Ceclan

The AD7173 family offer a complete integrated Sigma-Delta ADC solution which can be used in high precision, low noise single channel applications or higher speed multiplexed applications. The Sigma-Delta ADC is intended primarily for measurement of signals close to DC but also delivers outstanding performance with input bandwidths out to ~10kHz.

---

V11->V12
- Drop "binding", describe hardware in binding description
- Rename refin and refin2 to vref and vref2
- Add better description to external references to better show that the voltage value that needs to be specified is the difference between the positive and negative reference pins
- Add optional clocks properties
- Add optional adi,clock-select property
- Add option for second interrupt, error
- Add description to interrupts
V10->V11
- Fix example warning: '#gpio-cells' is a dependency of 'gpio-controller'
- Add description to #gpio-cells property
V9->V10
- Fix dt_binding_check type warning from adi,reference-select
V8->v9
- Add gpio-controller and "#gpio-cells" properties
- Add missing avdd2 and iovdd supplies
- Add string type to reference-select
V7->V8
- include missing fix from V6
V6->V7 <no changes>
V5->V6
- Moved global required property to proper placement
V4 -> V5
- Use string enum instead of integers for "adi,reference-select"
- Fix conditional checking in regards to compatible
V3 -> V4
- include supply attributes
- add channel attribute for selecting conversion reference
V2 -> V3
- remove redundant descriptions
- use referenced 'bipolar' property
- remove newlines from example
V1 -> V2 <no changes>

 .../bindings/iio/adc/adi,ad7173.yaml          | 242 ++++++++++++++++++
 1 file changed, 242 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +76 -0
new file mode 100644
index 000000000000..4d0870cc014c
@@ -0,0 +1,242 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2023 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7173.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7173 ADC
+
+maintainers:
+  - Ceclan Dumitru <[email protected]>
+
+description: |
+  Analog Devices AD717x ADC's:
+  The AD717x family offer a complete integrated Sigma-Delta ADC solution which
+  can be used in high precision, low noise single channel applications
+  (Life Science measurements) or higher speed multiplexed applications
+  (Factory Automation PLC Input modules). The Sigma-Delta ADC is intended
+  primarily for measurement of signals close to DC but also delivers
+  outstanding performance with input bandwidths out to ~10kHz.
+
+  Datasheets for supported chips:
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7172-2.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7173-8.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7175-2.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/AD7176-2.pdf
+
+properties:
+  compatible:
+    enum:
+      - adi,ad7172-2
+      - adi,ad7173-8
+      - adi,ad7175-2
+      - adi,ad7176-2
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    minItems: 1
+    description: |
+      Ready interrupt: multiplexed with SPI data out. While SPI CS is low,
+      can be used to indicate the completion of a conversion.
+
+      Error: The three error bits in the status register (ADC_ERROR, CRC_ERROR,
+      and REG_ERROR) are OR'ed, inverted, and mapped to the ERROR pin. Therefore,
+      the ERROR pin indicates that an error has occurred.
+
+  interrupt-names:
+    minItems: 1
+    items:
+      - const: rdy
+      - const: err
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0
+
+  spi-max-frequency:
+    maximum: 20000000
+
+  gpio-controller:
+    description: Marks the device node as a GPIO controller.
+
+  "#gpio-cells":
+    const: 2
+    description:
+      The first cell is the GPIO number and the second cell specifies
+      GPIO flags, as defined in <dt-bindings/gpio/gpio.h>.
+
+  vref-supply:
+    description: |
+      Differential external reference supply used for conversion. The reference
+      voltage (Vref) specified here must be the voltage difference between the

Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml line 86

Quoted 10 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +10 -0
+      REF+ and REF- pins: Vref = (REF+) - (REF-).
+
+  vref2-supply:
+    description: |
+      Differential external reference supply used for conversion. The reference
+      voltage (Vref2) specified here must be the voltage difference between the
+      REF2+ and REF2- pins: Vref2 = (REF2+) - (REF2-).
+
+  avdd-supply:
+    description: avdd supply, can be used as reference for conversion.

I think it would be helpful to have a description similar to vref-supply here. This is the voltage between AVDD and AVSS. So in both cases AVDD=5V, AVSS=0V and AVDD=+2.5V, AVSS=-2.5V, this supply should report 5V.

Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml line 89

Quoted 3 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +3 -0
+
+  avdd2-supply:
+    description: avdd2 supply, used as the input to the internal voltage regulator.

This supply is also referenced to AVSS.

Quoted 45 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +45 -0
+
+  iovdd-supply:
+    description: iovdd supply, used for the chip digital interface.
+
+  clocks:
+    maxItems: 1
+    description: |
+      Optional external clock source. Can include one clock source: external
+      clock or external crystal.
+
+  clock-names:
+    enum:
+      - ext-clk
+      - xtal
+
+  adi,clock-select:
+    description: |
+      Select the ADC clock source. Valid values are:
+      int         : Internal oscillator
+      int-out     : Internal oscillator with output on XTAL2 pin
+      ext-clk     : External clock input on XTAL2 pin
+      xtal        : External crystal on XTAL1 and XTAL2 pins
+
+    $ref: /schemas/types.yaml#/definitions/string
+    enum:
+      - int
+      - int-out
+      - ext-clk
+      - xtal
+    default: int
+
+patternProperties:
+  "^channel@[0-9a-f]$":
+    type: object
+    $ref: adc.yaml
+    unevaluatedProperties: false
+
+    properties:
+      reg:
+        minimum: 0
+        maximum: 15
+
+      diff-channels:
+        items:
+          minimum: 0

Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml line 144

Quoted 10 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +10 -0
+          maximum: 31
+
+      adi,reference-select:
+        description: |
+          Select the reference source to use when converting on
+          the specific channel. Valid values are:
+          vref       : REF+  /REF−
+          vref2      : REF2+ /REF2−
+          refout-avss: REFOUT/AVSS (Internal reference)
+          avdd       : AVDD

Could write this as AVDD/AVSS to be consistent with the other 3 options.

(Or if this is really AVDD to 0V, we may need to reconsider some of our other decisions.)

Quoted 101 lines
Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml new file +98 -1
+
+          External reference ref2 only available on ad7173-8.
+          If not specified, internal reference used.
+        $ref: /schemas/types.yaml#/definitions/string
+        enum:
+          - vref
+          - vref2
+          - refout-avss
+          - avdd
+        default: refout-avss
+
+    required:
+      - reg
+      - diff-channels
+
+required:
+  - compatible
+  - reg
+
+allOf:
+  - $ref: /schemas/spi/spi-peripheral-props.yaml#
+
+  - if:
+      properties:
+        compatible:
+          not:
+            contains:
+              const: adi,ad7173-8
+    then:
+      properties:
+        vref2-supply: false
+      patternProperties:
+        "^channel@[0-9a-f]$":
+          properties:
+            adi,reference-select:
+              enum:
+                - vref
+                - refout-avss
+                - avdd
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    spi {
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      adc@0 {
+        compatible = "adi,ad7173-8";
+        reg = <0>;
+
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+        interrupt-names = "rdy";
+        interrupt-parent = <&gpio>;
+        spi-max-frequency = <5000000>;
+        gpio-controller;
+        #gpio-cells = <2>;
+
+        vref-supply = <&dummy_regulator>;
+
+        channel@0 {
+          reg = <0>;
+          bipolar;
+          diff-channels = <0 1>;
+          adi,reference-select = "vref";
+        };
+
+        channel@1 {
+          reg = <1>;
+          diff-channels = <2 3>;
+        };
+
+        channel@2 {
+          reg = <2>;
+          bipolar;
+          diff-channels = <4 5>;
+        };
+
+        channel@3 {
+          reg = <3>;
+          bipolar;
+          diff-channels = <6 7>;
+        };
+
+        channel@4 {
+          reg = <4>;
+          diff-channels = <8 9>;
+          adi,reference-select = "avdd";
+        };
+      };
+    };
--

2.42.0