Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   David Yang <mmyangfl@gmail.com>
To:     linux-clk@vger.kernel.org
Cc:     David Yang <mmyangfl@gmail.com>,
        Michael Turquette <mturquette@baylibre.com>,
        Stephen Boyd <sboyd@kernel.org>,
        Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        devicetree@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH 1/2] dt-bindings: clock: Add reg-clock-controller
Date:   Sat, 15 Apr 2023 02:12:59 +0800
Message-Id: <20230414181302.986271-2-mmyangfl@gmail.com>
In-Reply-To: <20230414181302.986271-1-mmyangfl@gmail.com>
References: <20230414181302.986271-1-mmyangfl@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

Add DT bindings documentation for reg-clock-controller, collection of
basic clocks common to many platforms.

Signed-off-by: David Yang <mmyangfl@gmail.com>
---
 .../bindings/clock/reg-clock-controller.yaml  | 245 ++++++++++++++++++
 1 file changed, 245 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/clock/reg-clock-controller.yaml

diff --git a/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
new file mode 100644
index 000000000000..a6a7e0b05821
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/reg-clock-controller.yaml
@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/reg-clock-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Simple straight-forward register-based clocks
+
+maintainers:
+  - David Yang <mmyangfl@gmail.com>
+
+description: |
+  Basic clocks common to many platforms.
+
+  If your clocks don't fit into these catagories, simply create your clock
+  controller. This driver normally work well with other controllers as long as
+  they operate on different registers.
+
+  See linux/clk-provider.h for details about properties for each type of clock.
+
+properties:
+  compatible:
+    enum:
+      - reg-clock-controller
+
+  ranges: true
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 1
+
+required:
+  - compatible
+  - ranges
+  - '#address-cells'
+  - '#size-cells'
+
+patternProperties:
+  ".*gate-clock@.*":
+    type: object
+
+    description: |
+      Clock which can gate its output.
+
+    properties:
+      compatible:
+        const: gate-clock
+
+      reg:
+        maxItems: 1
+
+      '#clock-cells':
+        const: 0
+
+      clocks:
+        maxItems: 1
+        description:
+          Parent clock.
+
+      clock-output-name:
+        maxItems: 1
+
+      bit-index:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Bit index which controls the output.
+
+    required:
+      - compatible
+      - reg
+      - '#clock-cells'
+      - bit-index
+
+    additionalProperties: false
+
+  ".*divider-clock@.*":
+    type: object
+
+    description: |
+      Clock with an adjustable divider affecting its output frequency.
+
+    properties:
+      compatible:
+        const: divider-clock
+
+      reg:
+        maxItems: 1
+
+      '#clock-cells':
+        const: 0
+
+      clocks:
+        description:
+          Parent clocks.
+
+      clock-output-name:
+        maxItems: 1
+
+      shift:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Shift to the divider bit field.
+
+      width:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Width of the divider bit field.
+
+      dividers:
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+        description:
+          Array of value/divider pairs.
+
+    required:
+      - compatible
+      - reg
+      - '#clock-cells'
+      - shift
+      - width
+
+    additionalProperties: false
+
+  ".*mux-clock@.*":
+    type: object
+
+    description: |
+      Clock with multiple selectable parents.
+
+    properties:
+      compatible:
+        const: mux-clock
+
+      reg:
+        maxItems: 1
+
+      '#clock-cells':
+        const: 0
+
+      clocks:
+        minItems: 1
+        description:
+          Parent clock.
+
+      clock-output-name:
+        maxItems: 1
+
+      shift:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Shift to multiplexer bit field.
+
+      mask:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Mask of mutliplexer bit field.
+
+      table:
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+        description:
+          Array of register values corresponding to the parent index.
+
+    required:
+      - compatible
+      - reg
+      - '#clock-cells'
+      - shift
+      - mask
+
+    additionalProperties: false
+
+  ".*fractional-divider-clock@.*":
+    type: object
+
+    description: |
+      Clock with adjustable fractional divider affecting its output frequency.
+
+    properties:
+      compatible:
+        const: fractional_divider-clock
+
+      reg:
+        maxItems: 1
+
+      '#clock-cells':
+        const: 0
+
+      clocks:
+        maxItems: 1
+        description:
+          Parent clock.
+
+      clock-output-name:
+        maxItems: 1
+
+      numerator-shift:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Shift to the numerator bit field.
+
+      numerator-width:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Width of the numerator bit field.
+
+      denominator-shift:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Shift to the denominator bit field.
+
+      denominator-width:
+        $ref: /schemas/types.yaml#/definitions/uint32
+        description:
+          Width of the denominator bit field.
+
+    required:
+      - compatible
+      - reg
+      - '#clock-cells'
+      - numerator-shift
+      - numerator-width
+      - denominator-shift
+      - denominator-width
+
+    additionalProperties: false
+
+additionalProperties: true
+
+examples:
+  - |
+    clks: reg-clk-ctrl@ffff0000 {
+      compatible = "reg-clock-controller";
+      #address-cells = <1>;
+      #size-cells = <1>;
+      ranges = <0 0xffff0000 0x1000>;
+
+      my_clk: gate-clock@cc-3 {
+        compatible = "gate-clock";
+        #clock-cells = <0>;
+        reg = <0xcc 4>;
+        bit-index = <3>;
+        clock-output-name = "my-clk";
+      };
+    };
-- 
2.39.2