Re: [PATCH v2 2/3] dt-bindings: iio: frequency: Add docs for ADF4360 PLL

From: Ardelean, Alexandru
Date: Tue Jan 28 2020 - 01:41:12 EST

On Mon, 2020-01-27 at 15:35 -0600, Rob Herring wrote:
> On Wed, Jan 22, 2020 at 03:20:03PM +0200, Alexandru Ardelean wrote:
> > From: Edward Kigwana <ekigwana@xxxxxxxxx>
> >
> > This change adds the device-tree bindings documentation for the ADF4360
> > family of PLLs.
> >
> > Signed-off-by: Edward Kigwana <ekigwana@xxxxxxxxx>
> > Signed-off-by: Alexandru Ardelean <alexandru.ardelean@xxxxxxxxxx>
> > ---
> > .../bindings/iio/frequency/adf4371.yaml | 24 +--
> > .../bindings/iio/frequency/adi,adf4360.yaml | 158 ++++++++++++++++++
> > 2 files changed, 170 insertions(+), 12 deletions(-)
> > create mode 100644
> > Documentation/devicetree/bindings/iio/frequency/adi,adf4360.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml
> > b/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml
> > index 7ec3ec94356b..6edb68e8febf 100644
> > --- a/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml
> > +++ b/Documentation/devicetree/bindings/iio/frequency/adf4371.yaml
> > @@ -48,16 +48,16 @@ required:
> >
> > examples:
> > - |
> > - spi0 {
> > - #address-cells = <1>;
> > - #size-cells = <0>;
> > -
> > - frequency@0 {
> > - compatible = "adi,adf4371";
> > - reg = <0>;
> > - spi-max-frequency = <1000000>;
> > - clocks = <&adf4371_clkin>;
> > - clock-names = "clkin";
> > - };
> > - };
> > + spi0 {
> > + #address-cells = <1>;
> > + #size-cells = <0>;
> > +
> > + frequency@0 {
> > + compatible = "adi,adf4371";
> > + reg = <0>;
> > + spi-max-frequency = <1000000>;
> > + clocks = <&adf4371_clkin>;
> > + clock-names = "clkin";
> > + };
> > + };
>
> What's this change for?

Wait... what?

I'll drop this.
I'll implement the rest.

>
> > ...
> > diff --git
> > a/Documentation/devicetree/bindings/iio/frequency/adi,adf4360.yaml
> > b/Documentation/devicetree/bindings/iio/frequency/adi,adf4360.yaml
> > new file mode 100644
> > index 000000000000..1a7f166d2a3f
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/frequency/adi,adf4360.yaml
> > @@ -0,0 +1,158 @@
> > +# SPDX-License-Identifier: GPL-2.0
> > +# Copyright 2019-2020 Edward Kigwana
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/frequency/adi,adf4360.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Analog Devices ADF4360 PLL device driver
> > +
> > +maintainers:
> > + - Lars-Peter Clausen <lars@xxxxxxxxxx>
> > + - Edward Kigwana <ekigwana@xxxxxxxxx>
> > +
> > +description: |
> > + Bindings for the Analog Devices ADF4360 family of clock generator phase-
> > locked
> > + loop (PLL) devices with an integrated voltage-controlled oscillator
> > (VCO).
> > + Each of the parts in the family supports a specific frequency range.
> > + Datasheets can be found here:
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-0.pdf
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-1.pdf
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-2.pdf
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-3.pdf
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-4.pdf
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-5.pdf
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-6.pdf
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-7.pdf
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-8.pdf
> > +
> > https://www.analog.com/media/en/technical-documentation/data-sheets/ADF4360-9.pdf
> > +
> > +properties:
> > + compatible:
> > + enum:
> > + - adi,adf4360-0
> > + - adi,adf4360-1
> > + - adi,adf4360-2
> > + - adi,adf4360-3
> > + - adi,adf4360-4
> > + - adi,adf4360-5
> > + - adi,adf4360-6
> > + - adi,adf4360-7
> > + - adi,adf4360-8
> > + - adi,adf4360-9
>
> The enum can be just:
>
> pattern: '^adi,adf4360-[0-9]$'
>
>
> > +
> > + reg:
> > + maxItems: 1
> > +
> > + clocks:
> > + description: phandle to external reference clock.
>
> Not all that specific to this define, so drop.
>
> > + maxItems: 1
> > +
> > + clock-names:
> > + items:
> > + - const: clkin
> > +
> > + '#clock-cells':
> > + const: 0
> > +
> > + adi,loop-filter-pfd-frequency-hz:
> > + description: |
> > + The phase-frequency-detector frequency that the external loop filter
> > was
> > + designed for.
> > + allOf:
> > + - $ref: /schemas/types.yaml#/definitions/uint32
>
> Standard type suffixes have a type already, so you can drop this.
>
> > + maxItems: 1
>
> Any constraints in the value?
>
> > +
> > + adi,loop-filter-charger-pump-current-microamp:
> > + description: |
> > + The charge pump current that the external loop filter was designed
> > for.
> > + The provided value is clamped to the closest enumerated value.
> > + allOf:
> > + - $ref: /schemas/types.yaml#/definitions/uint32
>
> Can be dropped. Same goes for the rest.
>
> > + - enum: [310, 620, 930, 1250, 1560, 1870, 2180, 2500]
> > + maxItems: 1
> > +
> > + adi,vco-minimum-frequency-hz:
> > + description: |
> > + Required for ADF4360-7, ADF4360-8 and ADF4360-9. Minimum VCO
> > frequency
> > + that can be supported by the tuning range set by the external
> > inductor.
> > + allOf:
> > + - $ref: /schemas/types.yaml#/definitions/uint32
> > + maxItems: 1
> > +
> > + adi,vco-maximum-frequency-hz:
> > + description: |
> > + Required for ADF4360-7, ADF4360-8 and ADF4360-9. Maximum VCO
> > frequency
> > + that can be supported by the tuning range set by the external
> > inductor.
> > + allOf:
> > + - $ref: /schemas/types.yaml#/definitions/uint32
> > + maxItems: 1
> > +
> > + adi,loop-filter-inverting:
> > + description: Indicates that the external loop filter is an inverting
> > filter.
> > + type: boolean
> > +
> > + adi,power-up-frequency-hz:
> > + description: |
> > + PLL tunes to the set frequency on probe or defaults to either the
> > minimum
> > + for the part or value set using adi,vco-minimum-frequency-hz.
> > + allOf:
> > + - $ref: /schemas/types.yaml#/definitions/uint32
> > + maxItems: 1
> > +
> > + adi,vdd-supply:
> > + description: |
> > + vdd supply is used to enable or disable chip when regulator power
> > down
> > + mode is set. Other power down modes are used to mitigate the case of
> > a
> > + shared regulator.
> > + maxItems: 1
>
> -supply is always 1 item, so drop.
>
> > +
> > + adi,enable-gpios:
>
> enable-gpios is a standard name, so drop the vendor prefix.
>
> > + description: |
> > + Chip enable gpio is used to enable or disable chip when chip enable
> > power
> > + down mode is set.
> > + maxItems: 1
> > +
> > + adi,muxout-gpios:
> > + description: |
> > + MUX out gpio is used to detect chip and test pll lock state on read
> > when
> > + muxout control is set to lock detect.
> > + maxItems: 1
> > +
> > + adi,power-out-level-microamp:
> > + description: |
> > + Chip support setting of output power level. This property is
> > optional.
> > + If it is not provided by default 11000 uA will be set.
> > + allOf:
> > + - enum: [3500, 5000, 7500, 11000]
>
> Don't need the 'allOf'.
>
> > +
> > +required:
> > + - compatible
> > + - reg
> > + - clocks
> > + - clock-names
> > + - adi,loop-filter-charge-pump-current
> > + - adi,loop-filter-pfd-frequency-hz
> > +
> > +examples:
> > + - |
> > + spi0 {
> > + #address-cells = <1>;
> > + #size-cells = <0>;
> > +
> > + pll@0 {
> > + compatible = "adi,adf4360-7";
> > + reg = <0>;
> > + spi-max-frequency = <2000000>;
> > + clocks = <&ref_clock>;
> > + #clock-cells = <0>;
> > + clock-names = "clkin";
> > + clock-output-names = "adf4360-7";
> > +
> > + adi,loop-filter-charge-pump-current = <5>;
> > + adi,loop-filter-pfd-frequency-hz = <2500000>;
> > + adi,vco-minimum-frequency-hz = <700000000>;
> > + adi,vco-maximum-frequency-hz = <840000000>;
> > + };
> > + };
> > +...
> > --
> > 2.20.1
> >