diff mbox series

[RESEND,v6,1/2] dt-bindings: iio: dac: Add adi,ad3552r.yaml

Message ID 20211206163529.3528-1-mihail.chindris@analog.com (mailing list archive)
State Superseded
Headers show
Series drivers:iio:dac: Add AD3552R driver support | expand

Commit Message

Chindris, Mihail Dec. 6, 2021, 4:35 p.m. UTC 
Add documentation for ad3552r

Signed-off-by: Mihail Chindris <mihail.chindris@analog.com>
---
 .../bindings/iio/dac/adi,ad3552r.yaml         | 190 ++++++++++++++++++
 1 file changed, 190 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml

Comments

Rob Herring (Arm) Dec. 6, 2021, 7:53 p.m. UTC | #1 
On Mon, 06 Dec 2021 16:35:29 +0000, Mihail Chindris wrote:
> Add documentation for ad3552r
> 
> Signed-off-by: Mihail Chindris <mihail.chindris@analog.com>
> ---
>  .../bindings/iio/dac/adi,ad3552r.yaml         | 190 ++++++++++++++++++
>  1 file changed, 190 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:
./Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml:64:11: [warning] wrong indentation: expected 8 but found 10 (indentation)
./Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml:102:9: [warning] wrong indentation: expected 10 but found 8 (indentation)
./Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml:104:9: [warning] wrong indentation: expected 10 but found 8 (indentation)

dtschema/dtc warnings/errors:
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dts:21.17-27: Warning (reg_format): /example-0/ad3552r:reg: property has invalid length (4 bytes) (#address-cells == 1, #size-cells == 1)
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dts:24.25-35: Warning (reg_format): /example-0/ad3552r/channel@0:reg: property has invalid length (4 bytes) (#address-cells == 2, #size-cells == 1)
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dts:28.25-35: Warning (reg_format): /example-0/ad3552r/channel@1:reg: property has invalid length (4 bytes) (#address-cells == 2, #size-cells == 1)
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dts:19.17-36.13: Warning (unit_address_vs_reg): /example-0/ad3552r: node has a reg or ranges property, but no unit name
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dt.yaml: Warning (pci_device_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dt.yaml: Warning (pci_device_bus_num): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dt.yaml: Warning (simple_bus_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dt.yaml: Warning (i2c_bus_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dt.yaml: Warning (spi_bus_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dts:23.27-26.19: Warning (avoid_default_addr_size): /example-0/ad3552r/channel@0: Relying on default #address-cells value
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dts:23.27-26.19: Warning (avoid_default_addr_size): /example-0/ad3552r/channel@0: Relying on default #size-cells value
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dts:27.27-35.17: Warning (avoid_default_addr_size): /example-0/ad3552r/channel@1: Relying on default #address-cells value
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dts:27.27-35.17: Warning (avoid_default_addr_size): /example-0/ad3552r/channel@1: Relying on default #size-cells value
Documentation/devicetree/bindings/iio/dac/adi,ad3552r.example.dt.yaml: Warning (unique_unit_address): Failed prerequisite 'avoid_default_addr_size'

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/patch/1564044

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.
Rob Herring (Arm) Dec. 6, 2021, 9:41 p.m. UTC | #2 
On Mon, Dec 06, 2021 at 04:35:29PM +0000, Mihail Chindris wrote:
> Add documentation for ad3552r
> 
> Signed-off-by: Mihail Chindris <mihail.chindris@analog.com>
> ---
>  .../bindings/iio/dac/adi,ad3552r.yaml         | 190 ++++++++++++++++++
>  1 file changed, 190 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
> new file mode 100644
> index 000000000000..c6999bb4c7a4
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
> @@ -0,0 +1,190 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +# Copyright 2020 Analog Devices Inc.
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/dac/adi,ad3552r.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices AD2552R DAC device driver
> +
> +maintainers:
> +  - Mihail Chindris <mihail.chindris@analog.com>
> +
> +description: |
> +  Bindings for the Analog Devices AD3552R DAC device and similar.
> +  Datasheet can be found here:
> +    https://www.analog.com/media/en/technical-documentation/data-sheets/ad3542r.pdf
> +    https://www.analog.com/media/en/technical-documentation/data-sheets/ad3552r.pdf

blank line

> +properties:
> +  compatible:
> +    enum:
> +      - adi,ad3542r
> +      - adi,ad3552r
> +
> +  reg:
> +    maxItems: 1
> +
> +  spi-max-frequency:
> +    maximum: 30000000
> +
> +  reset-gpios:
> +    maxItems: 1
> +
> +  ldac-gpios:
> +    description: |
> +      LDAC pin to be used as a hardware trigger to update the DAC channels.
> +    maxItems: 1
> +
> +  vref-supply:
> +    description:
> +      The regulator to use as an external reference. If it does not exists the
> +      internal reference will be used. External reference must be 2.5V
> +
> +  adi,vref-out-en:
> +    description: Vref I/O driven by internal vref to 2.5V. If not set, Vref pin
> +      will be floating.
> +    type: boolean
> +
> +  adi,sdo-drive-strength:
> +    description: |
> +      Configure SDIO0 and SDIO1 strength levels:
> +        - 0: low SDO drive strength.
> +        - 1: medium low SDO drive strength.
> +        - 2: medium high SDO drive strength.
> +        - 3: high SDO drive strength
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [0, 1, 2, 3]
> +
> +patternProperties:
> +  "^channel@([0-1])$":
> +    type: object
> +    description: Configurations of the DAC Channels

       additionalProperties: false

> +    properties:
> +      reg:
> +          description: Channel number
> +          enum: [0, 1]

With that, you will need:

         adi,output-range-microvolt: true

> +
> +      custom-output-range-config:
> +        type: object

Why does this need to be in a child node?

> +        description: Configuration of custom range when
> +          adi,output-range-microvolt is not present.
> +          The formulas for calculation the output voltages are
> +            Vout_fs = 2.5 + [(GainN + Offset/1024) * 2.5 * Rfbx * 1.03]
> +            Vout_zs = 2.5 - [(GainP + Offset/1024) * 2.5 * Rfbx * 1.03]

blank line

> +        properties:
> +          adi,gain-offset:
> +            description: Gain offset used in the above formula
> +            $ref: /schemas/types.yaml#/definitions/int32
> +            maximum: 511
> +            minimum: -511

blank line, and so on...

> +          adi,gain-scaling-p-inv-log2:
> +            description: GainP = 1 / ( 2 ^ adi,gain-scaling-p-inv-log2)
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            enum: [0, 1, 2, 3]
> +          adi,gain-scaling-n-inv-log2:
> +            description: GainN = 1 / ( 2 ^ adi,gain-scaling-n-inv-log2)
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            enum: [0, 1, 2, 3]
> +          adi,rfb-ohms:
> +            description: Feedback Resistor
> +        required:
> +          - adi,gain-offset
> +          - adi,gain-scaling-p-inv-log2
> +          - adi,gain-scaling-n-inv-log2
> +          - adi,rfb-ohms
> +    required:
> +      - reg
> +
> +    oneOf:
> +      # If adi,output-range-microvolt is missing,
> +      # custom-output-range-config must be used
> +      - required:
> +        - adi,output-range-microvolt
> +      - required:
> +        - custom-output-range-config
> +
> +allOf:
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: adi,ad3542r
> +    then:
> +      patternProperties:
> +        "^channel@([0-1])$":
> +          type: object
> +          properties:
> +            adi,output-range-microvolt:
> +              description: |
> +                Voltage output range of the channel as <minimum, maximum>
> +                Required connections:
> +                  Rfb1x for: 0 to 2.5 V; 0 to 3V; 0 to 5 V;
> +                  Rfb2x for: 0 to 10 V; 2.5 to 7.5V; -5 to 5 V;
> +              oneOf:
> +                - items:
> +                    - const: 0
> +                    - enum: [2500000, 3000000, 5000000, 10000000]
> +                - items:
> +                    - const: -2500000
> +                    - const: 7500000
> +                - items:
> +                    - const: -5000000
> +                    - const: 5000000
> +          required:
> +            - adi,output-range-microvolt
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: adi,ad3552r
> +    then:
> +      patternProperties:
> +        "^channel@([0-1])$":
> +          type: object
> +          properties:
> +            adi,output-range-microvolt:
> +              description: |
> +                Voltage output range of the channel as <minimum, maximum>
> +                Required connections:
> +                  Rfb1x for: 0 to 2.5 V; 0 to 5 V;
> +                  Rfb2x for: 0 to 10 V; -5 to 5 V;
> +                  Rfb4x for: -10 to 10V
> +              oneOf:
> +                - items:
> +                    - const: 0
> +                    - enum: [2500000, 5000000, 10000000]
> +                - items:
> +                    - const: -5000000
> +                    - const: 5000000
> +                - items:
> +                    - const: -10000000
> +                    - const: 10000000
> +
> +required:
> +  - compatible
> +  - reg
> +  - spi-max-frequency
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    ad3552r {
> +            compatible = "adi,ad3552r";
> +            reg = <0>;
> +            spi-max-frequency = <20000000>;
> +            channel@0 {
> +                    reg = <0>;
> +                    adi,output-range-microvolt = <0 10000000>;
> +            };
> +            channel@1 {
> +                    reg = <1>;
> +                    custom-output-range-config {
> +                            adi,gain-offset = <5>;
> +                            adi,gain-scaling-p-inv-log2 = <1>;
> +                            adi,gain-scaling-n-inv-log2 = <2>;
> +                            adi,rfb-ohms = <1>;
> +                    };
> +          };
> +      };
> +...
> -- 
> 2.27.0
> 
>
Chindris, Mihail Dec. 10, 2021, 9:05 a.m. UTC | #3 
Hi Rob

I will fix the build and update the patch.
I have a question below until then though.

Regards,
Mihail

...

> > +
> > +      custom-output-range-config:
> > +        type: object
> 
> Why does this need to be in a child node?

For an ad3552r or ad3542r you can setup a default output range and a custom one (only one of these options is possible). The custom range is configured with this child and the default can be choose with the adi,output-range-microvolt property below

The adi,output-range-microvolt is described bellow for each chip. I couldn't find a way to put it here.
Do you have any suggestion?

Mihail

> 
> > +        description: Configuration of custom range when
> > +          adi,output-range-microvolt is not present.
> > +          The formulas for calculation the output voltages are
> > +            Vout_fs = 2.5 + [(GainN + Offset/1024) * 2.5 * Rfbx * 1.03]
> > +            Vout_zs = 2.5 - [(GainP + Offset/1024) * 2.5 * Rfbx *

...
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
new file mode 100644
index 000000000000..c6999bb4c7a4
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/dac/adi,ad3552r.yaml
@@ -0,0 +1,190 @@ 
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2020 Analog Devices Inc.
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/dac/adi,ad3552r.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices AD2552R DAC device driver
+
+maintainers:
+  - Mihail Chindris <mihail.chindris@analog.com>
+
+description: |
+  Bindings for the Analog Devices AD3552R DAC device and similar.
+  Datasheet can be found here:
+    https://www.analog.com/media/en/technical-documentation/data-sheets/ad3542r.pdf
+    https://www.analog.com/media/en/technical-documentation/data-sheets/ad3552r.pdf
+properties:
+  compatible:
+    enum:
+      - adi,ad3542r
+      - adi,ad3552r
+
+  reg:
+    maxItems: 1
+
+  spi-max-frequency:
+    maximum: 30000000
+
+  reset-gpios:
+    maxItems: 1
+
+  ldac-gpios:
+    description: |
+      LDAC pin to be used as a hardware trigger to update the DAC channels.
+    maxItems: 1
+
+  vref-supply:
+    description:
+      The regulator to use as an external reference. If it does not exists the
+      internal reference will be used. External reference must be 2.5V
+
+  adi,vref-out-en:
+    description: Vref I/O driven by internal vref to 2.5V. If not set, Vref pin
+      will be floating.
+    type: boolean
+
+  adi,sdo-drive-strength:
+    description: |
+      Configure SDIO0 and SDIO1 strength levels:
+        - 0: low SDO drive strength.
+        - 1: medium low SDO drive strength.
+        - 2: medium high SDO drive strength.
+        - 3: high SDO drive strength
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [0, 1, 2, 3]
+
+patternProperties:
+  "^channel@([0-1])$":
+    type: object
+    description: Configurations of the DAC Channels
+    properties:
+      reg:
+          description: Channel number
+          enum: [0, 1]
+
+      custom-output-range-config:
+        type: object
+        description: Configuration of custom range when
+          adi,output-range-microvolt is not present.
+          The formulas for calculation the output voltages are
+            Vout_fs = 2.5 + [(GainN + Offset/1024) * 2.5 * Rfbx * 1.03]
+            Vout_zs = 2.5 - [(GainP + Offset/1024) * 2.5 * Rfbx * 1.03]
+        properties:
+          adi,gain-offset:
+            description: Gain offset used in the above formula
+            $ref: /schemas/types.yaml#/definitions/int32
+            maximum: 511
+            minimum: -511
+          adi,gain-scaling-p-inv-log2:
+            description: GainP = 1 / ( 2 ^ adi,gain-scaling-p-inv-log2)
+            $ref: /schemas/types.yaml#/definitions/uint32
+            enum: [0, 1, 2, 3]
+          adi,gain-scaling-n-inv-log2:
+            description: GainN = 1 / ( 2 ^ adi,gain-scaling-n-inv-log2)
+            $ref: /schemas/types.yaml#/definitions/uint32
+            enum: [0, 1, 2, 3]
+          adi,rfb-ohms:
+            description: Feedback Resistor
+        required:
+          - adi,gain-offset
+          - adi,gain-scaling-p-inv-log2
+          - adi,gain-scaling-n-inv-log2
+          - adi,rfb-ohms
+    required:
+      - reg
+
+    oneOf:
+      # If adi,output-range-microvolt is missing,
+      # custom-output-range-config must be used
+      - required:
+        - adi,output-range-microvolt
+      - required:
+        - custom-output-range-config
+
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: adi,ad3542r
+    then:
+      patternProperties:
+        "^channel@([0-1])$":
+          type: object
+          properties:
+            adi,output-range-microvolt:
+              description: |
+                Voltage output range of the channel as <minimum, maximum>
+                Required connections:
+                  Rfb1x for: 0 to 2.5 V; 0 to 3V; 0 to 5 V;
+                  Rfb2x for: 0 to 10 V; 2.5 to 7.5V; -5 to 5 V;
+              oneOf:
+                - items:
+                    - const: 0
+                    - enum: [2500000, 3000000, 5000000, 10000000]
+                - items:
+                    - const: -2500000
+                    - const: 7500000
+                - items:
+                    - const: -5000000
+                    - const: 5000000
+          required:
+            - adi,output-range-microvolt
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: adi,ad3552r
+    then:
+      patternProperties:
+        "^channel@([0-1])$":
+          type: object
+          properties:
+            adi,output-range-microvolt:
+              description: |
+                Voltage output range of the channel as <minimum, maximum>
+                Required connections:
+                  Rfb1x for: 0 to 2.5 V; 0 to 5 V;
+                  Rfb2x for: 0 to 10 V; -5 to 5 V;
+                  Rfb4x for: -10 to 10V
+              oneOf:
+                - items:
+                    - const: 0
+                    - enum: [2500000, 5000000, 10000000]
+                - items:
+                    - const: -5000000
+                    - const: 5000000
+                - items:
+                    - const: -10000000
+                    - const: 10000000
+
+required:
+  - compatible
+  - reg
+  - spi-max-frequency
+
+additionalProperties: false
+
+examples:
+  - |
+    ad3552r {
+            compatible = "adi,ad3552r";
+            reg = <0>;
+            spi-max-frequency = <20000000>;
+            channel@0 {
+                    reg = <0>;
+                    adi,output-range-microvolt = <0 10000000>;
+            };
+            channel@1 {
+                    reg = <1>;
+                    custom-output-range-config {
+                            adi,gain-offset = <5>;
+                            adi,gain-scaling-p-inv-log2 = <1>;
+                            adi,gain-scaling-n-inv-log2 = <2>;
+                            adi,rfb-ohms = <1>;
+                    };
+          };
+      };
+...