> -----Original Message-----
> From: Krzysztof Kozlowski <krzk@xxxxxxxxxx>
> Sent: Tuesday, July 30, 2024 2:15 PM
> To: Tinaco, Mariel <Mariel.Tinaco@xxxxxxxxxx>; linux-iio@xxxxxxxxxxxxxxx;
> devicetree@xxxxxxxxxxxxxxx; linux-kernel@xxxxxxxxxxxxxxx; Jonathan Cameron
> <jic23@xxxxxxxxxx>; Lars-Peter Clausen <lars@xxxxxxxxxx>; Rob Herring
> <robh@xxxxxxxxxx>; Krzysztof Kozlowski <krzk+dt@xxxxxxxxxx>; Hennerich,
> Michael <Michael.Hennerich@xxxxxxxxxx>; Conor Dooley
> <conor+dt@xxxxxxxxxx>; Marcelo Schmitt <marcelo.schmitt1@xxxxxxxxx>;
> Dimitri Fedrau <dima.fedrau@xxxxxxxxx>; David Lechner
> <dlechner@xxxxxxxxxxxx>; Nuno Sá <noname.nuno@xxxxxxxxx>
> Subject: Re: [PATCH v2 1/2] dt-bindings: iio: dac: add docs for ad8460
>
> [External]
>
> On 30/07/2024 05:05, Mariel Tinaco wrote:
> > This adds the bindings documentation for the 14-bit
> > High Voltage, High Current, Waveform Generator
> > Digital-to-Analog converter.
> >
> > Signed-off-by: Mariel Tinaco <Mariel.Tinaco@xxxxxxxxxx>
>
> > +
> > + refio-1p2v-supply:
> > + description: Drive voltage in the range of 1.2V maximum to as low as
> > + low as 0.12V through the REF_IO pin to adjust full scale output span
> > +
> > + clocks:
>
> maxItems: 1
> and drop description (or use items: - description, but then do not
> repeat redundant parts)
>
Simplified the description for this item
refio-1p2v-supply:
description: Reference voltage to adjust full scale output span
maxItems: 1
Should I put, "maxItems: 1" in the other vrefs as well?
> > + description: The clock for the DAC. This is the sync clock
> > +
> > + adi,rset-ohms:
> > + description: Specify value of external resistor connected to FS_ADJ pin
> > + to establish internal HVDAC's reference current I_REF
> > + default: 2000
> > + minimum: 2000
> > + maximum: 20000
> > +
> > + adi,range-microvolt:
> > + description: |
> > + Voltage output range specified as <minimum, maximum>
> > + oneOf:
>
> Not an oneOf.
>
You're right. I should have put all the possible values. I populated it with common
Values found in the datasheet
adi,range-microvolt:
description: Voltage output range specified as <minimum, maximum>
oneOf:
- items:
- enum: [0, -10000000, -20000000, -30000000, -40000000, -55000000]
- enum: [10000000, 20000000, 30000000, 40000000, 55000000]
> > + - items:
> > + - const: -40000000
> > + - const: 40000000
>
> Why do you need this property if this cannot be anything else? Drop.
>
> > +
> > + adi,range-microamp:
> > + description: |
>
> Do not need '|' unless you need to preserve formatting.
>
> > + Current output range specified as <minimum, maximum>
> > + oneOf:
> > + - items:
> > + - const: 0
> > + - const: 50000
> > + - items:
> > + - const: -50000
> > + - const: 50000
> > +
> > + adi,temp-max-millicelsius:
> > + description: Overtemperature threshold
> > + default: 50000
> > + minimum: 20000
> > + maximum: 150000
> > +
> > + sdn-reset-gpios:
>
> reset-gpios or shutdown-gpios or anything from gpio-consumer-common
> which is not deprecated.
>
Lifted from gpio-consumer-common yaml. Mapped to corresponding pins
wakeup-gpios:
description: Corresponds to SDN_RESET pin. To exit shutdown
or sleep mode, pulse SDN_RESET HIGH, then leave LOW.
maxItems: 1
reset-gpios:
description: Manual Power On Reset (POR). Pull this GPIO pin
LOW and then HIGH to reset all digital registers to default
maxItems: 1
shutdown-gpios:
description: Corresponds to SDN_IO pin. Shutdown may be
initiated by the user, by pulsing SDN_IO high. To exit shutdown,
pulse SDN_IO low, then float.
maxItems: 1
Replaced description based on the datasheet
> > + description: GPIO spec for the SHUTDOWN RESET pin. As the line is active
> high,
>
> Do not repeat the obvious or redundant parts. There is no point in
> saying that "GPIO spec is a GPIO spec for ...". It cannot be anything
> else than GPIO spec. Instead say something useful. It's confusing to
> have two reset pins, so explain what is the purpose of this pin.
>
> > + it should be marked GPIO_ACTIVE_HIGH.
>
> Drop last part "it should be marked", because it is clearly incorrect.
> Different board designs can have it differently.
>
>
> > + maxItems: 1
> > +
> > + reset-gpios:
> > + description: GPIO spec for the RESET pin. As the line is active low, it
> > + should be marked GPIO_ACTIVE_LOW.
>
> Again, marking it always as active low is not correct. It is enough to
> say that line is active low.
>
> > + maxItems: 1
> > +
> > + sdn-io-gpios:
> > + description: GPIO spec for the SHUTDOWN INPUT/OUTPUT pin. As the
> line is
> > + active high, it should be marked GPIO_ACTIVE_HIGH.
>
> What's the purpose?
>
> > + maxItems: 1
> > +
> > +required:
> > + - compatible
> > + - reg
> > + - clocks
> > +
> > +allOf:
> > + - $ref: /schemas/spi/spi-peripheral-props.yaml#
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > + - |
> > + #include <dt-bindings/gpio/gpio.h>
> > +
> > + spi {
> > + #address-cells = <1>;
> > + #size-cells = <0>;
> > +
> > + dac@0 {
> > + compatible = "adi,ad8460";
> > + reg = <0>;
> > + spi-max-frequency = <8000000>;
> > + adi,rset-ohms = <2000>;
> > + adi,range-microvolt = <(-40000000) 40000000>;
> > + adi,range-microamp = <0 50000>;
> > + adi,temp-max-millicelsius = <50000>;
>
> Custom properties go to the end. See DTS coding style.
>
Moved custom attributes in the end
examples:
- |
#include <dt-bindings/gpio/gpio.h>
spi {
#address-cells = <1>;
#size-cells = <0>;
dac@0 {
compatible = "adi,ad8460";
reg = <0>;
spi-max-frequency = <8000000>;
dmas = <&tx_dma 0>;
dma-names = "tx";
wakeup-gpios = <&gpio 86 GPIO_ACTIVE_HIGH>;
reset-gpios = <&gpio 91 GPIO_ACTIVE_LOW>;
shutdown-gpios = <&gpio 88 GPIO_ACTIVE_HIGH>;
clocks = <&sync_ext_clk>;
hvcc-supply = <&hvcc>;
hvee-supply = <&hvee>;
vcc-5v-supply = <&vcc_5>;
vref-5v-supply = <&vref_5>;
dvdd-3p3v-supply = <&dvdd_3_3>;
avdd-3p3v-supply = <&avdd_3_3>;
refio-1p2v-supply = <&refio_1_2>;
adi,external-resistor-ohms = <2000>;
adi,range-microvolt = <(-40000000) 40000000>;
adi,range-microamp = <0 50000>;
adi,max-millicelsius = <50000>;
};
};
> > +
> > + dmas = <&tx_dma 0>;
> > + dma-names = "tx";
>
>
> Best regards,
> Krzysztof
