Documentation/devicetree/bindings/clock/baikal,bt1-ccu-div.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-div.yaml#
   6 $schema: http://devicetree.org/meta-schemas/core.yaml#
   7
   8 title: Baikal-T1 Clock Control Unit Dividers
   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 an embedded into CCU PLLs and gateable/non-gateable dividers. The
  20   later ones are described in this binding. Each clock domain can be also
  21   individually reset by using the domain clocks divider configuration
  22   registers. Baikal-T1 CCU is logically divided into the next components:
  23   1) External oscillator (normally XTAL's 25 MHz crystal oscillator, but
  24      in general can provide any frequency supported by the CCU PLLs).
  25   2) PLLs clocks generators (PLLs).
  26   3) AXI-bus clock dividers (AXI) - described in this binding file.
  27   4) System devices reference clock dividers (SYS) - described in this binding
  28      file.
  29   which are connected with each other as shown on the next figure:
  30
  31           +---------------+
  32           | Baikal-T1 CCU |
  33           |   +----+------|- MIPS P5600 cores
  34           | +-|PLLs|------|- DDR controller
  35           | | +----+      |
  36   +----+  | |  |  |       |
  37   |XTAL|--|-+  |  | +---+-|
  38   +----+  | |  |  +-|AXI|-|- AXI-bus
  39           | |  |    +---+-|
  40           | |  |          |
  41           | |  +----+---+-|- APB-bus
  42           | +-------|SYS|-|- Low-speed Devices
  43           |         +---+-|- High-speed Devices
  44           +---------------+
  45
  46   Each sub-block is represented as a separate DT node and has an individual
  47   driver to be bound with.
  48
  49   In order to create signals of wide range frequencies the external oscillator
  50   output is primarily connected to a set of CCU PLLs. Some of PLLs CLKOUT are
  51   then passed over CCU dividers to create signals required for the target clock
  52   domain (like AXI-bus or System Device consumers). The dividers have the
  53   following structure:
  54
  55           +--------------+
  56   CLKIN --|->+----+ 1|\  |
  57   SETCLK--|--|/DIV|->| | |
  58   CLKDIV--|--|    |  | |-|->CLKLOUT
  59   LOCK----|--+----+  | | |
  60           |          |/  |
  61           |           |  |
  62   EN------|-----------+  |
  63   RST-----|--------------|->RSTOUT
  64           +--------------+
  65
  66   where CLKIN is the reference clock coming either from CCU PLLs or from an
  67   external clock oscillator, SETCLK - a command to update the output clock in
  68   accordance with a set divider, CLKDIV - clocks divider, LOCK - a signal of
  69   the output clock stabilization, EN - enable/disable the divider block,
  70   RST/RSTOUT - reset clocks domain signal. Depending on the consumer IP-core
  71   peculiarities the dividers may lack of some functionality depicted on the
  72   figure above (like EN, CLKDIV/LOCK/SETCLK). In this case the corresponding
  73   clock provider just doesn't expose either switching functions, or the rate
  74   configuration, or both of them.
  75
  76   The clock dividers, which output clock is then consumed by the SoC individual
  77   devices, are united into a single clocks provider called System Devices CCU.
  78   Similarly the dividers with output clocks utilized as AXI-bus reference clocks
  79   are called AXI-bus CCU. Both of them use the common clock bindings with no
  80   custom properties. The list of exported clocks and reset signals can be found
  81   in the files: 'include/dt-bindings/clock/bt1-ccu.h' and
  82   'include/dt-bindings/reset/bt1-ccu.h'. Since System Devices and AXI-bus CCU
  83   are a part of the Baikal-T1 SoC System Controller their DT nodes are supposed
  84   to be a children of later one.
  85
  86 if:
  87   properties:
  88     compatible:
  89       contains:
  90         const: baikal,bt1-ccu-axi
  91
  92 then:
  93   properties:
  94     clocks:
  95       items:
  96         - description: CCU SATA PLL output clock
  97         - description: CCU PCIe PLL output clock
  98         - description: CCU Ethernet PLL output clock
  99
 100     clock-names:
 101       items:
 102         - const: sata_clk
 103         - const: pcie_clk
 104         - const: eth_clk
 105
 106 else:
 107   properties:
 108     clocks:
 109       items:
 110         - description: External reference clock
 111         - description: CCU SATA PLL output clock
 112         - description: CCU PCIe PLL output clock
 113         - description: CCU Ethernet PLL output clock
 114
 115     clock-names:
 116       items:
 117         - const: ref_clk
 118         - const: sata_clk
 119         - const: pcie_clk
 120         - const: eth_clk
 121
 122 properties:
 123   compatible:
 124     enum:
 125       - baikal,bt1-ccu-axi
 126       - baikal,bt1-ccu-sys
 127
 128   reg:
 129     maxItems: 1
 130
 131   "#clock-cells":
 132     const: 1
 133
 134   "#reset-cells":
 135     const: 1
 136
 137   clocks: true
 138
 139   clock-names: true
 140
 141 additionalProperties: false
 142
 143 required:
 144   - compatible
 145   - "#clock-cells"
 146   - clocks
 147   - clock-names
 148
 149 examples:
 150   # AXI-bus Clock Control Unit node:
 151   - |
 152     #include <dt-bindings/clock/bt1-ccu.h>
 153
 154     clock-controller@1f04d030 {
 155       compatible = "baikal,bt1-ccu-axi";
 156       reg = <0x1f04d030 0x030>;
 157       #clock-cells = <1>;
 158       #reset-cells = <1>;
 159
 160       clocks = <&ccu_pll CCU_SATA_PLL>,
 161                <&ccu_pll CCU_PCIE_PLL>,
 162                <&ccu_pll CCU_ETH_PLL>;
 163       clock-names = "sata_clk", "pcie_clk", "eth_clk";
 164     };
 165   # System Devices Clock Control Unit node:
 166   - |
 167     #include <dt-bindings/clock/bt1-ccu.h>
 168
 169     clock-controller@1f04d060 {
 170       compatible = "baikal,bt1-ccu-sys";
 171       reg = <0x1f04d060 0x0a0>;
 172       #clock-cells = <1>;
 173       #reset-cells = <1>;
 174
 175       clocks = <&clk25m>,
 176                <&ccu_pll CCU_SATA_PLL>,
 177                <&ccu_pll CCU_PCIE_PLL>,
 178                <&ccu_pll CCU_ETH_PLL>;
 179       clock-names = "ref_clk", "sata_clk", "pcie_clk",
 180                     "eth_clk";
 181     };
 182   # Required Clock Control Unit PLL node:
 183   - |
 184     ccu_pll: clock-controller@1f04d000 {
 185       compatible = "baikal,bt1-ccu-pll";
 186       reg = <0x1f04d000 0x028>;
 187       #clock-cells = <1>;
 188
 189       clocks = <&clk25m>;
 190       clock-names = "ref_clk";
 191     };
 192 ...