Document the Analog Devices AD7816, AD7817, and AD7818 digital
temperature sensor and ADC bindings in YAML format.

Please note that the driver for this device is currently in drivers/staging.
This patch is sent as an RFC to clean up and standardize the device tree
bindings prior to any major driver refactoring.

While reviewing the AD7816/7/8 datasheet to correctly document the properties,
it was noted that the current staging driver attempts to request a 'busy' GPIO
for both AD7816 and AD7817. However, the AD7816 is an 8-pin device and does
not possess a BUSY pin (only the 16-pin AD7817 has it). Therefore, in this
binding, busy-gpios is strictly limited to adi,ad7817.

This resolves the checkpatch.pl warnings regarding undocumented DT
compatible strings.

Signed-off-by: Taha Narimani <tahanarimani3443@gmail.com>
---
 .../bindings/iio/adc/adi,ad7816.yaml          | 105 ++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml

diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml
new file mode 100644
index 0000000..48563e4
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/adi,ad7816.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD7816/7/8 digital temperature sensor / ADC
+
+maintainers:
+  - Taha Narimani <tahanarimani3443@gmail.com>
+
+description: |
+  Analog Devices AD7816, AD7817, and AD7818 10-Bit general purpose ADC and
+  temperature sensor. The device communicates via an SPI interface.
+
+properties:
+  compatible:
+    enum:
+      - adi,ad7816
+      - adi,ad7817
+      - adi,ad7818
+
+  reg:
+    maxItems: 1
+
+  spi-max-frequency:
+    maximum: 12500000
+
+  vdd-supply:
+    description: Main power supply.
+
+  vref-supply:
+    description: |
+      Optional external reference voltage supply. If not provided, the
+      internal reference is used. Applicable for AD7816 and AD7817.
+
+  rdwr-gpios:
+    maxItems: 1
+    description: GPIO connected to the RD/WR pin.
+
+  convert-gpios:
+    maxItems: 1
+    description: GPIO connected to the CONVST (Convert Start) pin.
+
+  busy-gpios:
+    maxItems: 1
+    description: GPIO connected to the BUSY pin. Only applicable for AD7817.
+
+  interrupts:
+    maxItems: 1
+    description: OTI (Over Temperature Indicator) interrupt. Active low.
+
+required:
+  - compatible
+  - reg
+  - vdd-supply
+  - rdwr-gpios
+  - convert-gpios
+
+allOf:
+  - $ref: /schemas/spi/spi-peripheral-props.yaml#
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: adi,ad7817
+    then:
+      required:
+        - busy-gpios
+    else:
+      properties:
+        busy-gpios: false
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: adi,ad7818
+    then:
+      properties:
+        vref-supply: false
+
+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,ad7817";
+            reg = <0>;
+            spi-max-frequency = <1000000>;
+            vdd-supply = <&vcc>;
+            vref-supply = <&vref>;
+            rdwr-gpios = <&gpio 5 GPIO_ACTIVE_HIGH>;
+            convert-gpios = <&gpio 6 GPIO_ACTIVE_HIGH>;
+            busy-gpios = <&gpio 7 GPIO_ACTIVE_HIGH>;
+            interrupts = <20 IRQ_TYPE_LEVEL_LOW>;
+            interrupt-parent = <&gpio>;
+        };
+    };
-- 
2.53.0

On Sat, May 30, 2026 at 04:59:15PM +0000, Taha Narimani wrote:
> Document the Analog Devices AD7816, AD7817, and AD7818 digital
> temperature sensor and ADC bindings in YAML format.
> 
> Please note that the driver for this device is currently in drivers/staging.
> This patch is sent as an RFC to clean up and standardize the device tree
> bindings prior to any major driver refactoring.
> 
> While reviewing the AD7816/7/8 datasheet to correctly document the properties,
> it was noted that the current staging driver attempts to request a 'busy' GPIO
> for both AD7816 and AD7817. However, the AD7816 is an 8-pin device and does
> not possess a BUSY pin (only the 16-pin AD7817 has it). Therefore, in this
> binding, busy-gpios is strictly limited to adi,ad7817.
> 
> This resolves the checkpatch.pl warnings regarding undocumented DT
> compatible strings.
> 
> Signed-off-by: Taha Narimani <tahanarimani3443@gmail.com>

This seems probably okay, but I'm not willing to ack it as an RFC.

On Tue, 2 Jun 2026 18:05:44 +0100
Conor Dooley <conor@kernel.org> wrote:

> On Sat, May 30, 2026 at 04:59:15PM +0000, Taha Narimani wrote:
> > Document the Analog Devices AD7816, AD7817, and AD7818 digital
> > temperature sensor and ADC bindings in YAML format.
> > 
> > Please note that the driver for this device is currently in drivers/staging.
> > This patch is sent as an RFC to clean up and standardize the device tree
> > bindings prior to any major driver refactoring.
> > 
> > While reviewing the AD7816/7/8 datasheet to correctly document the properties,
> > it was noted that the current staging driver attempts to request a 'busy' GPIO
> > for both AD7816 and AD7817. However, the AD7816 is an 8-pin device and does
> > not possess a BUSY pin (only the 16-pin AD7817 has it). Therefore, in this
> > binding, busy-gpios is strictly limited to adi,ad7817.
> > 
> > This resolves the checkpatch.pl warnings regarding undocumented DT
> > compatible strings.
> > 
> > Signed-off-by: Taha Narimani <tahanarimani3443@gmail.com>  
> 
> This seems probably okay, but I'm not willing to ack it as an RFC.

You will get to see it again in the series moving the driver out of staging
so wait until then.

Looks fine to me as well.

On Sat, 30 May 2026 16:59:15 +0000
Taha Narimani <tahanarimani3443@gmail.com> wrote:

> Document the Analog Devices AD7816, AD7817, and AD7818 digital
> temperature sensor and ADC bindings in YAML format.
> 
> Please note that the driver for this device is currently in drivers/staging.
> This patch is sent as an RFC to clean up and standardize the device tree
> bindings prior to any major driver refactoring.
> 
> While reviewing the AD7816/7/8 datasheet to correctly document the properties,
> it was noted that the current staging driver attempts to request a 'busy' GPIO
> for both AD7816 and AD7817. However, the AD7816 is an 8-pin device and does
> not possess a BUSY pin (only the 16-pin AD7817 has it). Therefore, in this
> binding, busy-gpios is strictly limited to adi,ad7817.
> 
> This resolves the checkpatch.pl warnings regarding undocumented DT
> compatible strings.
> 
> Signed-off-by: Taha Narimani <tahanarimani3443@gmail.com>
> ---
Hi Taha,

There should be a change log here. Please reply to this thread with that for
this version.

Also, slow down.  For any patch allow at least 24 hours unless a maintainer
specifically requests it faster. For most stuff a week. That way any ongoing
discussion can finish and additional reviewers have time to take a look.


>  .../bindings/iio/adc/adi,ad7816.yaml          | 105 ++++++++++++++++++
>  1 file changed, 105 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml
> new file mode 100644
> index 0000000..48563e4
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml
> @@ -0,0 +1,105 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/adc/adi,ad7816.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices AD7816/7/8 digital temperature sensor / ADC
> +
> +maintainers:
> +  - Taha Narimani <tahanarimani3443@gmail.com>
> +
> +description: |
> +  Analog Devices AD7816, AD7817, and AD7818 10-Bit general purpose ADC and
> +  temperature sensor. The device communicates via an SPI interface.
> +
> +properties:
> +  compatible:
> +    enum:
> +      - adi,ad7816
> +      - adi,ad7817
> +      - adi,ad7818
> +
> +  reg:
> +    maxItems: 1
> +
> +  spi-max-frequency:
> +    maximum: 12500000
> +
> +  vdd-supply:
> +    description: Main power supply.
> +
> +  vref-supply:
> +    description: |
> +      Optional external reference voltage supply. If not provided, the
> +      internal reference is used. Applicable for AD7816 and AD7817.
> +
> +  rdwr-gpios:
> +    maxItems: 1
> +    description: GPIO connected to the RD/WR pin.
> +
> +  convert-gpios:
> +    maxItems: 1
> +    description: GPIO connected to the CONVST (Convert Start) pin.
> +
> +  busy-gpios:
> +    maxItems: 1
> +    description: GPIO connected to the BUSY pin. Only applicable for AD7817.
> +
> +  interrupts:
> +    maxItems: 1
> +    description: OTI (Over Temperature Indicator) interrupt. Active low.
> +
> +required:
> +  - compatible
> +  - reg
> +  - vdd-supply
> +  - rdwr-gpios
> +  - convert-gpios
> +
> +allOf:
> +  - $ref: /schemas/spi/spi-peripheral-props.yaml#
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: adi,ad7817
> +    then:
> +      required:
> +        - busy-gpios
> +    else:
> +      properties:
> +        busy-gpios: false
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: adi,ad7818
> +    then:
> +      properties:
> +        vref-supply: false
> +
> +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,ad7817";
> +            reg = <0>;
> +            spi-max-frequency = <1000000>;
> +            vdd-supply = <&vcc>;
> +            vref-supply = <&vref>;
> +            rdwr-gpios = <&gpio 5 GPIO_ACTIVE_HIGH>;
> +            convert-gpios = <&gpio 6 GPIO_ACTIVE_HIGH>;
> +            busy-gpios = <&gpio 7 GPIO_ACTIVE_HIGH>;
> +            interrupts = <20 IRQ_TYPE_LEVEL_LOW>;
> +            interrupt-parent = <&gpio>;
> +        };
> +    };

Hi Jonathan,

Thank you for your patience and the detailed review of v2. I apologize
for rushing the v3 submission and omitting the changelog. I am still
familiarizing myself with the kernel mailing list etiquette, and I
will certainly slow down and allow at least a week for future patch
revisions to ensure proper discussion time.

As you recommended, I took a step back and thoroughly read the
AD7816/7/8 datasheets. That was a great learning point—it helped me
realize that the AD7816 (8-pin) completely lacks a BUSY pin, which the
current staging driver incorrectly requests unconditionally. I also
mapped out the missing power supplies and OTI interrupts based on the
datasheet specifications to make the binding complete.

Here is the requested changelog for this version:

Changes in v3:
- Updated the patch title and marked it explicitly as an RFC, noting
the driver's staging status.
- Added `spi-max-frequency` with a maximum limit of 12.5MHz based on
the datasheet.
- Added `vdd-supply` and `vref-supply` properties (making vref-supply
optional where an internal reference exists).
- Implemented conditional schema logic: restricted `busy-gpios`
exclusively to the `adi,ad7817` variant and disallowed `vref-supply`
for `adi,ad7818`.
- Documented the `interrupts` property for the OTI pin (Active low) to
resolve the validation error in the v2 example.
- Modified the example block to use `adi,ad7817` to correctly align
with the `busy-gpios` requirement.

Best regards,
Taha Narimani


On Sun, May 31, 2026 at 6:12 PM Jonathan Cameron <jic23@kernel.org> wrote:
>
> On Sat, 30 May 2026 16:59:15 +0000
> Taha Narimani <tahanarimani3443@gmail.com> wrote:
>
> > Document the Analog Devices AD7816, AD7817, and AD7818 digital
> > temperature sensor and ADC bindings in YAML format.
> >
> > Please note that the driver for this device is currently in drivers/staging.
> > This patch is sent as an RFC to clean up and standardize the device tree
> > bindings prior to any major driver refactoring.
> >
> > While reviewing the AD7816/7/8 datasheet to correctly document the properties,
> > it was noted that the current staging driver attempts to request a 'busy' GPIO
> > for both AD7816 and AD7817. However, the AD7816 is an 8-pin device and does
> > not possess a BUSY pin (only the 16-pin AD7817 has it). Therefore, in this
> > binding, busy-gpios is strictly limited to adi,ad7817.
> >
> > This resolves the checkpatch.pl warnings regarding undocumented DT
> > compatible strings.
> >
> > Signed-off-by: Taha Narimani <tahanarimani3443@gmail.com>
> > ---
> Hi Taha,
>
> There should be a change log here. Please reply to this thread with that for
> this version.
>
> Also, slow down.  For any patch allow at least 24 hours unless a maintainer
> specifically requests it faster. For most stuff a week. That way any ongoing
> discussion can finish and additional reviewers have time to take a look.
>
>
> >  .../bindings/iio/adc/adi,ad7816.yaml          | 105 ++++++++++++++++++
> >  1 file changed, 105 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml
> > new file mode 100644
> > index 0000000..48563e4
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7816.yaml
> > @@ -0,0 +1,105 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/adc/adi,ad7816.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Analog Devices AD7816/7/8 digital temperature sensor / ADC
> > +
> > +maintainers:
> > +  - Taha Narimani <tahanarimani3443@gmail.com>
> > +
> > +description: |
> > +  Analog Devices AD7816, AD7817, and AD7818 10-Bit general purpose ADC and
> > +  temperature sensor. The device communicates via an SPI interface.
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - adi,ad7816
> > +      - adi,ad7817
> > +      - adi,ad7818
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  spi-max-frequency:
> > +    maximum: 12500000
> > +
> > +  vdd-supply:
> > +    description: Main power supply.
> > +
> > +  vref-supply:
> > +    description: |
> > +      Optional external reference voltage supply. If not provided, the
> > +      internal reference is used. Applicable for AD7816 and AD7817.
> > +
> > +  rdwr-gpios:
> > +    maxItems: 1
> > +    description: GPIO connected to the RD/WR pin.
> > +
> > +  convert-gpios:
> > +    maxItems: 1
> > +    description: GPIO connected to the CONVST (Convert Start) pin.
> > +
> > +  busy-gpios:
> > +    maxItems: 1
> > +    description: GPIO connected to the BUSY pin. Only applicable for AD7817.
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +    description: OTI (Over Temperature Indicator) interrupt. Active low.
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - vdd-supply
> > +  - rdwr-gpios
> > +  - convert-gpios
> > +
> > +allOf:
> > +  - $ref: /schemas/spi/spi-peripheral-props.yaml#
> > +  - if:
> > +      properties:
> > +        compatible:
> > +          contains:
> > +            const: adi,ad7817
> > +    then:
> > +      required:
> > +        - busy-gpios
> > +    else:
> > +      properties:
> > +        busy-gpios: false
> > +  - if:
> > +      properties:
> > +        compatible:
> > +          contains:
> > +            const: adi,ad7818
> > +    then:
> > +      properties:
> > +        vref-supply: false
> > +
> > +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,ad7817";
> > +            reg = <0>;
> > +            spi-max-frequency = <1000000>;
> > +            vdd-supply = <&vcc>;
> > +            vref-supply = <&vref>;
> > +            rdwr-gpios = <&gpio 5 GPIO_ACTIVE_HIGH>;
> > +            convert-gpios = <&gpio 6 GPIO_ACTIVE_HIGH>;
> > +            busy-gpios = <&gpio 7 GPIO_ACTIVE_HIGH>;
> > +            interrupts = <20 IRQ_TYPE_LEVEL_LOW>;
> > +            interrupt-parent = <&gpio>;
> > +        };
> > +    };
>