Re: [PATCH v2 1/2] dt-bindings: iio: dac: add adi,ad5754.yaml

[Jonathan Cameron <jic23@kernel.org>]

On Fri, 4 Nov 2022 19:23:42 +0200
Ciprian Regus <ciprian.regus@analog.com> wrote:

> Add devicetree bindings documentation for the AD5754 DAC driver.
> 
> Signed-off-by: Ciprian Regus <ciprian.regus@analog.com>
Hi Ciprian,

To add to Krzysztof's detailed review, a request for a bit more
variation in the example.

> ---
> changes in v2:
>  - dropped "device driver" from the title.
>  - added the vendor prefix to the 'output-range-microvolt' property.
>  - fixed example indentation (4 spaces).
>  .../bindings/iio/dac/adi,ad5754.yaml          | 182 ++++++++++++++++++
>  1 file changed, 182 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/dac/adi,ad5754.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5754.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5754.yaml
> new file mode 100644
> index 000000000000..4c9c5ba90931
...

> +patternProperties:
> +  "^channel@([0-3])$":
> +    type: object
> +    description: Configurations for the DAC channels
> +
> +    properties:
> +      reg:
> +        description: Channel number
> +        maxItems: 1
> +
> +      adi,output-range-microvolt:
> +        description: |
> +          Voltage range of a channel as <minimum, maximum>.
> +        oneOf:
> +          - items:
> +              - const: 0
> +              - enum: [5000000, 10000000, 10800000]
> +          - items:
> +              - const: -5000000
> +              - const: 5000000
> +          - items:
> +              - const: -10000000
> +              - const: 10000000
> +          - items:
> +              - const: -10800000
> +              - const: 10800000
> +
> +    required:
> +      - reg
> +      - adi,output-range-microvolt
> +
...

> +examples:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    spi {
> +        status = "okay";
> +
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        dac@0 {
> +            compatible = "adi,ad5754r";
> +            reg = <0>;
> +            spi-max-frequency = <1000000>;
> +            spi-cpol;
> +
> +            clr-gpios = <&gpio 25 GPIO_ACTIVE_LOW>;
> +
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +
> +            channel@0 {
> +                reg = <0>;
> +                adi,output-range-microvolt = <0 5000000>;
> +            };
> +            channel@1 {
> +                reg = <1>;
> +                adi,output-range-microvolt = <0 5000000>;

Nice to have rather than necessary, but maybe the example could
include a few different options from those available for this
property?

> +            };
> +            channel@2 {
> +                reg = <2>;
> +                adi,output-range-microvolt = <0 5000000>;
> +            };
> +            channel@3 {
> +                reg = <3>;
> +                adi,output-range-microvolt = <0 5000000>;
> +            };
> +        };
> +    };