Documentation/devicetree/bindings/clock/baikal,bt1-ccu-pll.yaml

   1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2 # Copyright (C) 2020 BAIKAL ELECTRONICS, JSC
   3 %YAML 1.2
   4 ---
   5 $id: http://devicetree.org/schemas/clock/baikal,bt1-ccu-pll.yaml#
   6 $schema: http://devicetree.org/meta-schemas/core.yaml#
   7
   8 title: Baikal-T1 Clock Control Unit PLL
   9
  10 maintainers:
  11   - Serge Semin <fancer.lancer@gmail.com>
  12
  13 description: |
  14   Clocks Control Unit is the core of Baikal-T1 SoC System Controller
  15   responsible for the chip subsystems clocking and resetting. The CCU is
  16   connected with an external fixed rate oscillator, which signal is transformed
  17   into clocks of various frequencies and then propagated to either individual
  18   IP-blocks or to groups of blocks (clock domains). The transformation is done
  19   by means of PLLs and gateable/non-gateable dividers embedded into the CCU.
  20   It's logically divided into the next components:
  21   1) External oscillator (normally XTAL's 25 MHz crystal oscillator, but
  22      in general can provide any frequency supported by the CCU PLLs).
  23   2) PLLs clocks generators (PLLs) - described in this binding file.
  24   3) AXI-bus clock dividers (AXI).
  25   4) System devices reference clock dividers (SYS).
  26   which are connected with each other as shown on the next figure:
  27
  28           +---------------+
  29           | Baikal-T1 CCU |
  30           |   +----+------|- MIPS P5600 cores
  31           | +-|PLLs|------|- DDR controller
  32           | | +----+      |
  33   +----+  | |  |  |       |
  34   |XTAL|--|-+  |  | +---+-|
  35   +----+  | |  |  +-|AXI|-|- AXI-bus
  36           | |  |    +---+-|
  37           | |  |          |
  38           | |  +----+---+-|- APB-bus
  39           | +-------|SYS|-|- Low-speed Devices
  40           |         +---+-|- High-speed Devices
  41           +---------------+
  42
  43   Each CCU sub-block is represented as a separate dts-node and has an
  44   individual driver to be bound with.
  45
  46   In order to create signals of wide range frequencies the external oscillator
  47   output is primarily connected to a set of CCU PLLs. There are five PLLs
  48   to create a clock for the MIPS P5600 cores, the embedded DDR controller,
  49   SATA, Ethernet and PCIe domains. The last three domains though named by the
  50   biggest system interfaces in fact include nearly all of the rest SoC
  51   peripherals. Each of the PLLs is based on True Circuits TSMC CLN28HPM core
  52   with an interface wrapper (so called safe PLL' clocks switcher) to simplify
  53   the PLL configuration procedure. The PLLs work as depicted on the next
  54   diagram:
  55
  56       +--------------------------+
  57       |                          |
  58       +-->+---+    +---+   +---+ |  +---+   0|\
  59   CLKF--->|/NF|--->|PFD|...|VCO|-+->|/OD|--->| |
  60           +---+ +->+---+   +---+ /->+---+    | |--->CLKOUT
  61   CLKOD---------C----------------+          1| |
  62        +--------C--------------------------->|/
  63        |        |                             ^
  64   Rclk-+->+---+ |                             |
  65   CLKR--->|/NR|-+                             |
  66           +---+                               |
  67   BYPASS--------------------------------------+
  68   BWADJ--->
  69
  70   where Rclk is the reference clock coming  from XTAL, NR - reference clock
  71   divider, NF - PLL clock multiplier, OD - VCO output clock divider, CLKOUT -
  72   output clock, BWADJ is the PLL bandwidth adjustment parameter. At this moment
  73   the binding supports the PLL dividers configuration in accordance with a
  74   requested rate, while bypassing and bandwidth adjustment settings can be
  75   added in future if it gets to be necessary.
  76
  77   The PLLs CLKOUT is then either directly connected with the corresponding
  78   clocks consumer (like P5600 cores or DDR controller) or passed over a CCU
  79   divider to create a signal required for the clock domain.
  80
  81   The CCU PLL dts-node uses the common clock bindings with no custom
  82   parameters. The list of exported clocks can be found in
  83   'include/dt-bindings/clock/bt1-ccu.h'. Since CCU PLL is a part of the
  84   Baikal-T1 SoC System Controller its DT node is supposed to be a child of
  85   later one.
  86
  87 properties:
  88   compatible:
  89     const: baikal,bt1-ccu-pll
  90
  91   reg:
  92     maxItems: 1
  93
  94   "#clock-cells":
  95     const: 1
  96
  97   clocks:
  98     description: External reference clock
  99     maxItems: 1
 100
 101   clock-names:
 102     const: ref_clk
 103
 104 additionalProperties: false
 105
 106 required:
 107   - compatible
 108   - "#clock-cells"
 109   - clocks
 110   - clock-names
 111
 112 examples:
 113   # Clock Control Unit PLL node:
 114   - |
 115     clock-controller@1f04d000 {
 116       compatible = "baikal,bt1-ccu-pll";
 117       reg = <0x1f04d000 0x028>;
 118       #clock-cells = <1>;
 119
 120       clocks = <&clk25m>;
 121       clock-names = "ref_clk";
 122     };
 123   # Required external oscillator:
 124   - |
 125     clk25m: clock-oscillator-25m {
 126       compatible = "fixed-clock";
 127       #clock-cells = <0>;
 128       clock-frequency  = <25000000>;
 129       clock-output-names = "clk25m";
 130     };
 131 ...