Re: [PATCH v2 2/2] dt-bindings: clock: ad9545: Add documentation

From: Rob Herring
Date: Tue Jun 15 2021 - 18:51:20 EST

Next message: Rob Herring: "Re: [PATCH 1/4] dt-bindings: phy: rockchip: USB2: remove useless #phy-cells property"
Previous message: Kurt Manucredo: "Re: [PATCH v5] bpf: core: fix shift-out-of-bounds in ___bpf_prog_run"
In reply to: Rob Herring: "Re: [PATCH v2 2/2] dt-bindings: clock: ad9545: Add documentation"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

On Mon, Jun 14, 2021 at 10:07:18AM +0300, alexandru.tachici@xxxxxxxxxx wrote:
> From: Alexandru Tachici <alexandru.tachici@xxxxxxxxxx>
>
> Add dt bindings for ad9545.

Kind of a lot of properties, not really sure what to do about that...

>
> Signed-off-by: Alexandru Tachici <alexandru.tachici@xxxxxxxxxx>
> ---
> .../devicetree/bindings/clock/clk-ad9545.yaml | 556 ++++++++++++++++++
> include/dt-bindings/clock/ad9545.h | 69 +++
> 2 files changed, 625 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/clock/clk-ad9545.yaml
> create mode 100644 include/dt-bindings/clock/ad9545.h
>
> diff --git a/Documentation/devicetree/bindings/clock/clk-ad9545.yaml b/Documentation/devicetree/bindings/clock/clk-ad9545.yaml
> new file mode 100644
> index 000000000000..50553a88ab44
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/clock/clk-ad9545.yaml
> @@ -0,0 +1,556 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/clock/clk-ad9545.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices AD9545 Quad Input, 10-Output, Dual DPLL/IEEE 1588
> +
> +maintainers:
> + - Alexandru Tachici <alexandru.tachici@xxxxxxxxxx>
> +
> +description: |
> + Analog Devices AD9545 Quad Input, 10-Output, Dual DPLL/IEEE 1588,
> + 1 pps Synchronizer and Jitter Cleaner
> + https://www.analog.com/media/en/technical-documentation/data-sheets/ADM1266.pdf
> +
> +properties:
> + compatible:
> + enum:
> + - adi,ad9545
> +
> + "#clock-cells":
> + const: 2
> +
> + reg:
> + description: |

Don't need '|' if there's no formatting or anything that has to be
escaped.

Same applies elsewhere.

> + I2C address of the secondary device.
> + minimum: 0
> + maximum: 0xFF
> +
> + avcc-supply:
> + description: |
> + Phandle to the Avcc power supply.
> +
> + adi,freq-doubler:
> + description: |
> + The system clock PLL provides the user with the option of doubling the reference frequency.
> + type: boolean
> +
> + adi,ref-crystal:
> + description: |
> + At XOA,XOB there is a crystal connected that needs maintaining.
> + Otherwise it is assumed that there is a TCXO or OCXO connected.
> + type: boolean
> +
> + adi,ref-frequency-hz:
> + description: |
> + Reference input frequency at XOA,XOB. This is used for the system clock.
> +
> + clocks:
> + items:
> + - description: Ref A clock input
> + - description: Ref AA clock input
> + - description: Ref B clock input
> + - description: Ref BB clock input
> + - description: Ref M0 clock input
> + - description: Ref M1 clock input
> + - description: Ref M2 clock input
> + maxItems: 4

Looks like 7 is the max...

> +
> + assigned-clocks:
> + description:
> + Clocks are identified using two cells <&ad9545 clock_type clock_address>.
> + minItems: 1
> + maxItems: 14
> +
> + assigned-clock-rates:
> + minItems: 1
> + maxItems: 14
> +
> + assigned-clock-phases:
> + minItems: 1
> + maxItems: 14
> +
> + clock-output-names:
> + maxItems: 10
> +
> + aux-dpll:
> + description: |
> + Auxiliary DPLL used for Closed-Loop method of system clock compensation.
> + type: object
> +
> + properties:
> + adi,compensation-source:
> + description: |
> + System clock closed loop compensation source.
> + Choose from Ref-A to Ref-BB [0-3] or aux TDCs [4-5].
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [0, 1, 2, 3, 4, 5]
> +
> + adi,aux-dpll-bw-mhz:
> + description: |
> + Auxiliary DPLL bandwidth.
> + minimum: 100
> + maximum: 2000000
> +
> + adi,rate-change-limit:
> + description: |
> + Error compensation rate change limiting expressed in ppb/s. Disabled if property is
> + missing.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [715, 1430, 2860, 5720, 11440, 22880, 45760]
> +
> + required:
> + - adi,compensation-source
> + - adi,aux-dpll-bw-mhz
> +
> + aux-tdc-clks:
> + description: |
> + Child nodes represent Mx pin reference clock inputs.
> + type: object
> +
> + properties:
> + '#address-cells':
> + const: 1
> +
> + '#size-cells':
> + const: 0
> +
> + patternProperties:
> + "^aux-tdc-clk@[0-3]$":
> +
> + description: |
> + Represents a Mx pin reference clock input.
> + type: object
> +
> + properties:
> + reg:
> + description: |
> + Address of the Auxiliary TDC.
> + maximum: 1

0-3 as the unit-address says or only 1?

> +
> + adi,pin-nr:
> + description: |
> + Pin number to be the source of this TDC.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 0
> + maximum: 6
> +
> + required:
> + - reg
> + - adi,pin-nr
> +
> + additionalProperties: false
> +
> + ref-input-clks:
> + description: |
> + Child nodes represent reference clock inputs.
> + type: object
> +
> + properties:
> + '#address-cells':
> + const: 1
> +
> + '#size-cells':
> + const: 0
> +
> + patternProperties:
> + "^ref-input-clk@[0-3]$":
> + description: |
> + Represents a reference clock input.
> + type: object
> +
> + properties:
> + reg:
> + description: |
> + The reference input number. It can have up to 4 input clocks numbered from 0 to 3.
> + (mapped: [refa, refaa, refb, refbb] -> [0, 1, 2, 3])
> + maxItems: 1
> +
> + adi,single-ended-mode:
> + description: |
> + Single-ended configuration mode.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [0, 1, 2, 3]
> +
> + adi,differential-mode:
> + description: |
> + Differential configuration mode.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [0, 1, 2]
> +
> + adi,r-divider-ratio:
> + description: |
> + Each reference input has a dedicated divider.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 1073741824
> +
> + adi,ref-dtol-pbb:
> + description: |
> + REFx offset limit. Constitutes a fractional portion of the corresponding nominal period.
> + The 24-bit number represents fractional units of parts per billion (ppb) up to a
> + maximum of approximately 17 million ppb (1.7%).
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 0
> + maximum: 16777215
> + default: 100000
> +
> + adi,ref-monitor-hysteresis-pbb:
> + description: |
> + Basis points of the offset limit representing per ten thousand of REFx offset limit.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [0, 3125, 6250, 12500, 25000, 50000, 75000, 87500]
> + default: 12500
> +
> + adi,ref-validation-timer-ms:
> + description: |
> + Time required for a reference to remain in tolerance condition before being
> + available to be used.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 1048574
> + default: 10
> +
> + adi,freq-lock-threshold-ps:
> + description: |
> + Phase lock detector threshold (in picoseconds).
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 16777215
> +
> + adi,phase-lock-threshold-ps:
> + description: |
> + Profile 0 frequency lock threshold. Frequency lock detector threshold (in picoseconds).
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 16777215
> +
> + adi,phase-lock-fill-rate:
> + description: |
> + Parameter used by the DPLL Phase Lock Detector.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 255
> + default: 10
> +
> + adi,phase-lock-drain-rate:
> + description: |
> + Parameter used by the DPLL Phase Lock Detector.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 255
> + default: 10
> +
> + adi,freq-lock-fill-rate:
> + description: |
> + Parameter used by the DPLL Frequency Lock Detector.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 255
> + default: 10
> +
> + adi,freq-lock-drain-rate:
> + description: |
> + Parameter used by the DPLL Frequency Lock Detector.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 255
> + default: 10
> +
> + required:
> + - reg
> + - adi,r-divider-ratio
> + - adi,ref-dtol-pbb
> + - adi,ref-monitor-hysteresis-pbb
> + - adi,ref-validation-timer-ms
> + - adi,freq-lock-threshold-ps
> + - adi,phase-lock-threshold-ps
> +
> + additionalProperties: false
> +
> + pll-clks:
> + description: |
> + Child nodes represent PLLs.
> + type: object
> +
> + properties:
> + '#address-cells':
> + const: 1
> +
> + '#size-cells':
> + const: 0
> +
> + patternProperties:
> + "^pll-clk@[0-1]$":
> + description: |
> + Represents a PLL.
> + type: object
> +
> + properties:
> + reg:
> + description: |
> + PLL number. AD9545 has two PLLs.
> + maxItems: 1
> +
> + '#address-cells':
> + const: 1
> +
> + '#size-cells':
> + const: 0
> +
> + adi,fast-acq-trigger-mode:
> + description: |
> + If this is not specified Fast Acquisition will be used every time. See reg 0x2106
> + for constraints on Fast Acquisition trigger.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 0
> + maximum: 15
> + default: 0
> +
> + patternProperties:
> + "^profile@[0-5]$":
> + description: |
> + Represents a DPLL profile. Each DPLL can have up to 6 specified sources
> + wih priorities assigned.
> + type: object
> +
> + properties:
> + reg:
> + description: |
> + Profile number. A DPLL can have up to 6 translation profiles.
> + maxItems: 1

Blank line

> + adi,profile-priority:
> + description: |
> + Profile selection priority. 0 is the highest, 31 is the lowest. For revertive
> + reference switching, ensure that priority difference is > 7.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 0
> + maximum: 31
> +
> + adi,pll-source:
> + description: |
> + Each PLL can have 1 signal source. Choose from Ref-A to Ref-BB [0-3] or aux NCOs [4-5].
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [0, 1, 2, 3, 4, 5]
> +
> + adi,pll-loop-bandwidth-uhz:
> + description: |
> + PLL loop bandwidth in microhertz.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 1850000000
> + default: 200000000
> +
> + adi,fast-acq-excess-bw:
> + description: |
> + Controls the DPLL loop bandwidth scaling factor while in fast acquisition mode.
> + 0 means this feature is disabled.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [0, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024]
> + default: 0
> +
> + adi,fast-acq-timeout-ms:
> + description: |
> + Fast acquisition timeout controls the maximum amount of time that DPLL waits to
> + achieve phase lock before reducing the loop bandwidth by a factor of two.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [1, 10, 50, 100, 500, 1000, 10000, 50000]
> + default: 1
> +
> + adi,fast-acq-lock-settle-ms:
> + description: |
> + Controls how long DPLL must wait after achieving phase lock before reducing
> + the loop bandwidth by a factor of 2.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [1, 10, 50, 100, 500, 1000, 10000, 50000]
> + default: 1
> +
> + required:
> + - reg
> + - adi,pll-source
> + - adi,pll-loop-bandwidth-uhz
> +
> + additionalProperties: false
> +
> + required:
> + - reg
> +
> + additionalProperties: false
> +
> + aux-ncos:
> + description: |
> + Child nodes represent auxiliary Numerical Controlled Oscilators.
> + type: object
> +
> + properties:
> + '#address-cells':
> + const: 1
> +
> + '#size-cells':
> + const: 0
> +
> + patternProperties:
> + "^aux-nco-clk@[0-1]$":
> + description: |
> + Represents an auxiliary Numerical Controlled Oscilator. Generates timestamps that
> + can be sent to the DPLL0 or DPLL1.
> + type: object
> +
> + properties:
> + reg:
> + description: |
> + Auxiliary NCO address mapped: [NCO0, NCO1] -> [0, 1].
> + maxItems: 1
> +
> + adi,freq-lock-threshold-ps:
> + description: |
> + Phase lock detector threshold (in picoseconds).
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 16777215
> +
> + adi,phase-lock-threshold-ps:
> + description: |
> + Profile 0 frequency lock threshold. Frequency lock detector threshold (in picoseconds).
> + $ref: /schemas/types.yaml#/definitions/uint32
> + minimum: 1
> + maximum: 16777215
> +
> + required:
> + - reg
> + - adi,freq-lock-threshold-ps
> + - adi,phase-lock-threshold-ps
> +
> + additionalProperties: false
> +
> + output-clks:
> + description: |
> + Child nodes represent clock outputs.
> + type: object
> +
> + properties:
> + '#address-cells':
> + const: 1
> +
> + '#size-cells':
> + const: 0
> +
> + patternProperties:
> + "^output-clk@([0-9]|1[0-3])$":
> + description: |
> + Represents a clock output.
> + type: object
> +
> + properties:
> + reg:
> + description: |
> + The reference input number. It can have up to 10 output clocks mapped:
> + (OUT0AP OUT0AN OUT0BP OUT0BN OUT0CP OUT0CN OUT1AP OUT1AN OUT1BP OUT1BN) ->
> + (0, 1, 2, 3, 4, 5, 6, 7, 8, 9)

Looks like constraints (maximum: 9).

> + maxItems: 1
> +
> + adi,current-source:
> + description: |
> + If specified output is set as current source.
> + type: boolean
> +
> + adi,current-source-microamp:
> + description: |
> + The magnitude of the driver current.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [7500, 12500, 15000]
> +
> + adi,output-mode:
> + description: |
> + Output driver mode.
> + $ref: /schemas/types.yaml#/definitions/uint32
> + enum: [0, 1, 2]
> +
> + required:
> + - reg
> + - adi,current-source-microamp
> + - adi,output-mode
> +
> + additionalProperties: false
> +
> +required:
> + - compatible
> + - reg
> + - adi,ref-frequency-hz
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + #include <dt-bindings/clock/ad9545.h>
> +
> + i2c1 {

i2c {

> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + ad9545_clock: ad9545@4A {

clock-controller@4a

> + compatible = "adi,ad9545";
> + reg = <0x4A>;
> +
> + adi,ref-crystal;
> + adi,ref-frequency-hz = <52000000>;
> +
> + #clock-cells = <2>;
> + assigned-clocks = <&ad9545_clock AD9545_CLK_NCO AD9545_NCO0>,
> + <&ad9545_clock AD9545_CLK_PLL AD9545_PLL1>,
> + <&ad9545_clock AD9545_CLK_OUT AD9545_Q1A>,
> + <&ad9545_clock AD9545_CLK_OUT AD9545_Q1B>;
> + assigned-clock-rates = <10000>, <1875000000>, <156250000>, <156250000>;
> + assigned-clock-phases = <0>, <0>, <0>, <180>;
> +
> + aux-ncos {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + aux-nco-clk@AD9545_NCO0 {

Can't have defines in unit addresses. We generally don't have defines
for 'reg' values.

> + reg = <AD9545_NCO0>;
> + adi,freq-lock-threshold-ps = <16000000>;
> + adi,phase-lock-threshold-ps = <16000000>;
> + };
> + };
> +
> + pll-clks {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + ad9545_apll1: pll-clk@AD9545_PLL1 {
> + reg = <AD9545_PLL1>;
> +
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + profile@0 {
> + reg = <0>;
> + adi,pll-source = <4>;
> + adi,profile-priority = <0>;
> + adi,pll-loop-bandwidth-uhz = <200000000>;
> + };
> + };
> + };
> +
> + output-clks {
> + #address-cells = <1>;
> + #size-cells = <0>;
> +
> + output-clk@AD9545_Q1A {
> + reg = <AD9545_Q1A>;
> + adi,output-mode = <DRIVER_MODE_DUAL_DIV>;
> + adi,current-source-microamp = <15000>;
> + };
> +
> + output-clk@AD9545_Q1B {
> + reg = <AD9545_Q1B>;
> + adi,output-mode = <DRIVER_MODE_DUAL_DIV>;
> + adi,current-source-microamp = <15000>;
> + };
> + };
> + };
> + };
> +...
> diff --git a/include/dt-bindings/clock/ad9545.h b/include/dt-bindings/clock/ad9545.h
> new file mode 100644
> index 000000000000..857d50e5715b
> --- /dev/null
> +++ b/include/dt-bindings/clock/ad9545.h
> @@ -0,0 +1,69 @@
> +/* SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause */
> +/*
> + * AD9545 Network Clock Generator/Synchronizer
> + *
> + * Copyright 2020 Analog Devices Inc.
> + */
> +
> +#ifndef _DT_BINDINGS_CLOCK_AD9545_H_
> +#define _DT_BINDINGS_CLOCK_AD9545_H_
> +
> +/* Input Driver Mode
> + * Use for adi,single-ended-mode:
> + */
> +#define DRIVER_MODE_AC_COUPLED_IF 0
> +#define DRIVER_MODE_DC_COUPLED_1V2 1
> +#define DRIVER_MODE_DC_COUPLED_1V8 2
> +#define DRIVER_MODE_IN_PULL_UP 3
> +
> +/* Input Driver Mode
> + * Use for adi,differential-mode:
> + */
> +#define DRIVER_MODE_AC_COUPLED 0
> +#define DRIVER_MODE_DC_COUPLED 1
> +#define DRIVER_MODE_DC_COUPLED_LVDS 2
> +
> +/* Output Driver Mode
> + * Use for adi,output-mode:
> + */
> +#define DRIVER_MODE_SINGLE_DIV_DIF 0
> +#define DRIVER_MODE_SINGLE_DIV 1
> +#define DRIVER_MODE_DUAL_DIV 2
> +
> +/* Clock types */
> +#define AD9545_CLK_OUT 0
> +#define AD9545_CLK_PLL 1
> +#define AD9545_CLK_NCO 2
> +#define AD9545_CLK_AUX_TDC 3
> +
> +/* PLL addresses */
> +#define AD9545_PLL0 0
> +#define AD9545_PLL1 1
> +
> +/* Outputs addresses */
> +#define AD9545_Q0A 0
> +#define AD9545_Q0AA 1
> +#define AD9545_Q0B 2
> +#define AD9545_Q0BB 3
> +#define AD9545_Q0C 4
> +#define AD9545_Q0CC 5
> +#define AD9545_Q1A 6
> +#define AD9545_Q1AA 7
> +#define AD9545_Q1B 8
> +#define AD9545_Q1BB 9
> +
> +/* NCO addresses */
> +#define AD9545_NCO0 0
> +#define AD9545_NCO1 1
> +
> +/* TDC addresses */
> +#define AD9545_CLK_AUX_TDC0 0
> +#define AD9545_CLK_AUX_TDC1 1
> +
> +/* Ex:
> + * Output Q0C clock: <&ad9545_clock AD9545_CLK_OUT AD9545_Q0C>;
> + * PLL0 clock: <&ad9545_clock AD9545_CLK_PLL AD9545_PLL0>;
> + * NCO1 clock: <&ad9545_clock AD9545_CLK_NCO AD9545_NCO1>;
> + */
> +
> +#endif /* _DT_BINDINGS_CLOCK_AD9545_H_ */
> --
> 2.25.1

Next message: Rob Herring: "Re: [PATCH 1/4] dt-bindings: phy: rockchip: USB2: remove useless #phy-cells property"
Previous message: Kurt Manucredo: "Re: [PATCH v5] bpf: core: fix shift-out-of-bounds in ___bpf_prog_run"
In reply to: Rob Herring: "Re: [PATCH v2 2/2] dt-bindings: clock: ad9545: Add documentation"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]