All of lore.kernel.org
 help / color / mirror / Atom feed
From: <alexandru.tachici@analog.com>
To: <linux-clk@vger.kernel.org>, <linux-kernel@vger.kernel.org>,
	<devicetree@vger.kernel.org>
Cc: <robh+dt@kernel.org>, <sboyd@kernel.org>,
	<mturquette@baylibre.com>, <petre.minciunescu@analog.com>,
	Alexandru Tachici <alexandru.tachici@analog.com>
Subject: [PATCH v2 2/2] dt-bindings: clock: ad9545: Add documentation
Date: Mon, 14 Jun 2021 10:07:18 +0300	[thread overview]
Message-ID: <20210614070718.78041-3-alexandru.tachici@analog.com> (raw)
In-Reply-To: <20210614070718.78041-1-alexandru.tachici@analog.com>

From: Alexandru Tachici <alexandru.tachici@analog.com>

Add dt bindings for ad9545.

Signed-off-by: Alexandru Tachici <alexandru.tachici@analog.com>
---
 .../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@analog.com>
+
+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: |
+      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
+
+  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
+
+          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
+              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)
+            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 {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ad9545_clock: ad9545@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 {
+                                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


  parent reply	other threads:[~2021-06-14  6:59 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-06-14  7:07 [PATCH v2 0/2] clk: ad9545: Add support alexandru.tachici
2021-06-14  7:07 ` [PATCH v2 1/2] " alexandru.tachici
2021-06-14  7:07 ` alexandru.tachici [this message]
2021-06-14 13:39   ` [PATCH v2 2/2] dt-bindings: clock: ad9545: Add documentation Rob Herring
2021-06-15 22:50   ` Rob Herring
2021-06-16 18:53   ` kernel test robot
2021-06-16 18:53     ` kernel test robot
2021-06-17  7:55   ` kernel test robot
2021-06-17  7:55     ` kernel test robot
2021-06-18  4:17   ` kernel test robot
2021-06-18  4:17     ` kernel test robot
2021-06-22  7:02   ` kernel test robot
2021-06-22  7:02     ` kernel test robot

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210614070718.78041-3-alexandru.tachici@analog.com \
    --to=alexandru.tachici@analog.com \
    --cc=devicetree@vger.kernel.org \
    --cc=linux-clk@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mturquette@baylibre.com \
    --cc=petre.minciunescu@analog.com \
    --cc=robh+dt@kernel.org \
    --cc=sboyd@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.