Re: [PATCH 2/3] dt-bindings: iio: frequency: add adf41513

[Krzysztof Kozlowski <krzk@kernel.org>]

On Mon, Nov 10, 2025 at 03:44:45PM +0000, Rodrigo Alencar wrote:
> ultralow noise PLL frequency synthesizer that can be used to
> implement local oscillators (LOs) as high as 26.5 GHz
> 
> Signed-off-by: Rodrigo Alencar <rodrigo.alencar@analog.com>
> ---

Please organize the patch documenting compatible (DT bindings) before their user.
See also: https://elixir.bootlin.com/linux/v6.14-rc6/source/Documentation/devicetree/bindings/submitting-patches.rst#L46

...

> +  clocks:
> +    maxItems: 1
> +    description: Clock that provides the reference input frequency.
> +
> +  '#clock-cells':
> +    const: 0
> +
> +  clock-output-names:
> +    maxItems: 1
> +
> +  vcc-supply:
> +    description: Power supply for the device (3.3V)
> +
> +  chip-enable-gpios:

enable-gpios

> +    description:
> +      GPIO that controls the chip enable pin. A logic low on this pin
> +      powers down the device and puts the charge pump output into
> +      three-state mode.
> +    maxItems: 1
> +
> +  lock-detect-gpios:
> +    description:
> +      GPIO for lock detect functionality. When configured for digital lock
> +      detect, this pin will output a logic high when the PLL is locked.
> +    maxItems: 1
> +
> +  adi,power-up-frequency:
> +    $ref: /schemas/types.yaml#/definitions/uint64

Use standard unit suffixes. Frequency is in Hz for example.

> +    minimum: 1000000000
> +    maximum: 26500000000
> +    default: 10000000000
> +    description:
> +      The PLL tunes to this frequency (in Hz) on driver probe.
> +      Range is 1 GHz to 26.5 GHz for ADF41513, and 1 GHz to 10 GHz for ADF41510.
> +
> +  adi,reference-div-factor:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    minimum: 1
> +    maximum: 32
> +    description:
> +      Reference division factor (R Counter). If not specified, the driver
> +      will calculate the optimal value automatically.

Then why do you need this property? If driver calculates the optimal,
why anyone would put wrong or sub-optimal value to DT?

Drop.

> +
> +  adi,reference-doubler-enable:
> +    description:
> +      Enables the reference doubler. The maximum reference frequency when
> +      the doubler is enabled is 225 MHz.
> +    type: boolean
> +
> +  adi,reference-div2-enable:
> +    description:
> +      Enables the reference divide-by-2 function. This provides a 50%
> +      duty cycle signal to the PFD.
> +    type: boolean
> +
> +  adi,charge-pump-current-microamp:
> +    minimum: 450
> +    maximum: 7200
> +    default: 2400
> +    description:
> +      Charge pump current in microamps. The value will be rounded to the
> +      nearest supported value.
> +
> +  adi,charge-pump-resistor-ohms:
> +    minimum: 1800
> +    maximum: 10000
> +    default: 2700
> +    description:
> +      External charge pump resistor value in ohms. This sets the maximum
> +      charge pump current along with the charge pump current setting.
> +
> +  adi,muxout-select:
> +    description:
> +      On chip multiplexer output selection.
> +      high_z - MUXOUT Pin set to high-Z. (default)
> +      muxout_high - MUXOUT Pin set to high.
> +      muxout_low - MUXOUT Pin set to low.
> +      f_div_rclk - MUXOUT Pin set to R divider output
> +      f_div_nclk - MUXOUT Pin set to N divider output
> +      lock_detect - MUXOUT Pin set to Digital lock detect
> +      serial_data - MUXOUT Pin set to Serial data output
> +      readback - MUXOUT Pin set to Readback mode
> +      f_div_clk1 - MUXOUT Pin set to CLK1 divider output
> +      f_div_rclk_2 - MUXOUT Pin set to R divider/2 output
> +      f_div_nclk_2 - MUXOUT Pin set to N divider/2 output
> +    enum: [high_z, muxout_high, muxout_low, f_div_rclk, f_div_nclk, lock_detect,
> +           serial_data, readback, f_div_clk1, f_div_rclk_2, f_div_nclk_2]
> +
> +  adi,muxout-level-1v8-enable:
> +    description:
> +      Set MUXOUT and DLD logic levels to 1.8V. Default is 3.3V.
> +    type: boolean
> +
> +  adi,phase-detector-polarity-positive-enable:
> +    description:
> +      Set phase detector polarity to positive. Default is negative.
> +      Use positive polarity with non-inverting loop filter and VCO with
> +      positive tuning slope, or with inverting loop filter and VCO with
> +      negative tuning slope.
> +    type: boolean
> +
> +  adi,lock-detect-precision:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    minimum: 0
> +    maximum: 3
> +    description:
> +      Lock detector precision setting. Controls the sensitivity of the
> +      lock detector. Lower values of precision increases the lock detector
> +      window size.
> +
> +  adi,lock-detect-count:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    minimum: 0
> +    maximum: 7
> +    description: |
> +      Lock detector count setting (3-bit value). Determines the number of
> +      consecutive phase detector cycles that must be within the lock detector
> +      window before lock is declared. The count grows in powers of two of the
> +      programmed value:
> +      - if adi,fast-lock-enable is set count = 2 * 2^value
> +      - if adi,fast-lock-enable is not set count = 64 * 2^value
> +
> +  adi,lock-detect-bias-microamp:
> +    description:
> +      Lock detector bias current. Controls the lock detector window size
> +      along with the lock detector precision setting. Lower bias current
> +      increases the window size.
> +    enum: [10, 20, 30, 40]
> +
> +  adi,fast-lock-enable:
> +    description:
> +      Enable fast lock mode. This changes the lock detector clock selection
> +      for faster lock indication.
> +    type: boolean
> +
> +  adi,phase-resync-enable:
> +    description:
> +      Enable phase resync functionality. This produces a consistent output
> +      phase offset with respect to the input reference.
> +    type: boolean
> +
> +  adi,12bit-clk-divider:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    minimum: 0
> +    maximum: 4095
> +    description:
> +      CLK1 divider value used when adi,phase-resync-enable is set
> +
> +  adi,12bit-clk2-divider:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    minimum: 0
> +    maximum: 4095
> +    description:
> +      CLK2 divider value used when adi,phase-resync-enable is set
> +
> +  adi,le-sync-enable:
> +    description:
> +      Synchronize the rising edge of LE on an SPI write with the falling
> +      edge of the reference signal to prevent glitches.
> +    type: boolean
> +
> +  adi,freq-resolution:
> +    $ref: /schemas/types.yaml#/definitions/uint64
> +    minimum: 1
> +    default: 1000000
> +    description:
> +      Initial frequency resolution in micro-Hz (µHz) for the algorithm to achieve.
> +      This influences the choice between fixed and variable modulus modes.
> +      Default is 1000000 µHz (1 Hz).
> +
> +required:
> +  - compatible
> +  - reg
> +  - clocks
> +  - vcc-supply
> +
> +allOf:
> +  - $ref: /schemas/spi/spi-peripheral-props.yaml#
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    spi {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        pll@0 {
> +            compatible = "adi,adf41513";
> +            reg = <0>;
> +            spi-max-frequency = <10000000>;
> +            clocks = <&ref_clk>;
> +            vcc-supply = <&vcc_3v3>;
> +            #clock-cells = <0>;
> +
> +            adi,power-up-frequency = /bits/ 64 <12000000000>;
> +            adi,charge-pump-current-microamp = <2400>;
> +            adi,phase-detector-polarity-positive-enable;
> +        };
> +    };
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +    spi {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        /* Example with advanced features enabled */
> +        pll_advanced@0 {

pll@

> +            compatible = "adi,adf41513";
> +            reg = <0>;
> +            spi-max-frequency = <25000000>;
> +            clocks = <&ref_clk>;
> +            vcc-supply = <&vcc_3v3>;
> +            chip-enable-gpios = <&gpio0 10 GPIO_ACTIVE_HIGH>;
> +            lock-detect-gpios = <&gpio0 11 GPIO_ACTIVE_HIGH>;
> +            #clock-cells = <0>;
> +            clock-output-names = "adf41513_clk";
> +
> +            adi,power-up-frequency = /bits/ 64 <15500000000>;
> +            adi,charge-pump-current-microamp = <3600>;
> +            adi,charge-pump-resistor-ohms = <2700>;
> +            adi,reference-doubler-enable;
> +            adi,muxout-select = "lock_detect";
> +            adi,lock-detect-precision = <1>;
> +            adi,lock-detect-count = <4>;
> +            adi,lock-detect-bias-microamp = <40>;
> +            adi,fast-lock-enable;
> +            adi,phase-resync-enable;
> +            adi,12bit-clk-divider = <1>;
> +            adi,12bit-clk2-divider = <200>;
> +            adi,le-sync-enable;
> +            adi,freq-resolution = /bits/ 64 <1000000>;
> +            adi,phase-detector-polarity-positive-enable;
> +        };
> +    };
> +...
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 8df4a0d216c8..1bbcff826238 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1606,6 +1606,7 @@ M:	Rodrigo Alencar <rodrigo.alencar@analog.com>
>  L:	linux-iio@vger.kernel.org
>  S:	Supported
>  W:	https://ez.analog.com/linux-software-drivers
> +F:	Documentation/devicetree/bindings/iio/frequency/adi,adf41513.yaml
>  F:	drivers/iio/frequency/adf41513.c
>  
>  ANALOG DEVICES INC ADF4377 DRIVER
> 
> -- 
> 2.43.0
>