Documentation/devicetree/bindings/power/mediatek,power-controller.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/power/mediatek,power-controller.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Mediatek Power Domains Controller

maintainers:
  - Weiyi Lu <weiyi.lu@mediatek.com>
  - Matthias Brugger <mbrugger@suse.com>

description: |
  Mediatek processors include support for multiple power domains which can be
  powered up/down by software based on different application scenes to save power.

  IP cores belonging to a power domain should contain a 'power-domains'
  property that is a phandle for SCPSYS node representing the domain.

properties:
  $nodename:
    const: power-controller

  compatible:
    enum:
      - mediatek,mt8173-power-controller
      - mediatek,mt8183-power-controller
      - mediatek,mt8192-power-controller

  '#power-domain-cells':
    const: 1

  '#address-cells':
    const: 1

  '#size-cells':
    const: 0

patternProperties:
  "^power-domain@[0-9a-f]+$":
    type: object
    description: |
      Represents the power domains within the power controller node as documented
      in Documentation/devicetree/bindings/power/power-domain.yaml.

    properties:

      '#power-domain-cells':
        description:
          Must be 0 for nodes representing a single PM domain and 1 for nodes
          providing multiple PM domains.

      '#address-cells':
        const: 1

      '#size-cells':
        const: 0

      reg:
        description: |
          Power domain index. Valid values are defined in:
              "include/dt-bindings/power/mt8173-power.h" - for MT8173 type power domain.
              "include/dt-bindings/power/mt8183-power.h" - for MT8183 type power domain.
              "include/dt-bindings/power/mt8192-power.h" - for MT8192 type power domain.
        maxItems: 1

      clocks:
        description: |
          A number of phandles to clocks that need to be enabled during domain
          power-up sequencing.

      clock-names:
        description: |
          List of names of clocks, in order to match the power-up sequencing
          for each power domain we need to group the clocks by name. BASIC
          clocks need to be enabled before enabling the corresponding power
          domain, and should not have a '-' in their name (i.e mm, mfg, venc).
          SUSBYS clocks need to be enabled before releasing the bus protection,
          and should contain a '-' in their name (i.e mm-0, isp-0, cam-0).

          In order to follow properly the power-up sequencing, the clocks must
          be specified by order, adding first the BASIC clocks followed by the
          SUSBSYS clocks.

      mediatek,infracfg:
        $ref: /schemas/types.yaml#/definitions/phandle
        description: phandle to the device containing the INFRACFG register range.

      mediatek,smi:
        $ref: /schemas/types.yaml#/definitions/phandle
        description: phandle to the device containing the SMI register range.

    patternProperties:
      "^power-domain@[0-9a-f]+$":
        type: object
        description: |
          Represents a power domain child within a power domain parent node.

        properties:

          '#power-domain-cells':
            description:
              Must be 0 for nodes representing a single PM domain and 1 for nodes
              providing multiple PM domains.

          '#address-cells':
            const: 1

          '#size-cells':
            const: 0

          reg:
            maxItems: 1

          clocks:
            description: |
              A number of phandles to clocks that need to be enabled during domain
              power-up sequencing.

          clock-names:
            description: |
              List of names of clocks, in order to match the power-up sequencing
              for each power domain we need to group the clocks by name. BASIC
              clocks need to be enabled before enabling the corresponding power
              domain, and should not have a '-' in their name (i.e mm, mfg, venc).
              SUSBYS clocks need to be enabled before releasing the bus protection,
              and should contain a '-' in their name (i.e mm-0, isp-0, cam-0).

              In order to follow properly the power-up sequencing, the clocks must
              be specified by order, adding first the BASIC clocks followed by the
              SUSBSYS clocks.

          mediatek,infracfg:
            $ref: /schemas/types.yaml#/definitions/phandle
            description: phandle to the device containing the INFRACFG register range.

          mediatek,smi:
            $ref: /schemas/types.yaml#/definitions/phandle
            description: phandle to the device containing the SMI register range.

        patternProperties:
          "^power-domain@[0-9a-f]+$":
            type: object
            description: |
              Represents a power domain child within a power domain parent node.

            properties:

              '#power-domain-cells':
                description:
                  Must be 0 for nodes representing a single PM domain and 1 for nodes
                  providing multiple PM domains.

              '#address-cells':
                const: 1

              '#size-cells':
                const: 0

              reg:
                maxItems: 1

              clocks:
                description: |
                  A number of phandles to clocks that need to be enabled during domain
                  power-up sequencing.

              clock-names:
                description: |
                  List of names of clocks, in order to match the power-up sequencing
                  for each power domain we need to group the clocks by name. BASIC
                  clocks need to be enabled before enabling the corresponding power
                  domain, and should not have a '-' in their name (i.e mm, mfg, venc).
                  SUSBYS clocks need to be enabled before releasing the bus protection,
                  and should contain a '-' in their name (i.e mm-0, isp-0, cam-0).

                  In order to follow properly the power-up sequencing, the clocks must
                  be specified by order, adding first the BASIC clocks followed by the
                  SUSBSYS clocks.

              mediatek,infracfg:
                $ref: /schemas/types.yaml#/definitions/phandle
                description: phandle to the device containing the INFRACFG register range.

              mediatek,smi:
                $ref: /schemas/types.yaml#/definitions/phandle
                description: phandle to the device containing the SMI register range.

            required:
              - reg

            additionalProperties: false

        required:
          - reg

        additionalProperties: false

    required:
      - reg

    additionalProperties: false

required:
  - compatible

additionalProperties: false

examples:
  - |
    #include <dt-bindings/clock/mt8173-clk.h>
    #include <dt-bindings/power/mt8173-power.h>

    soc {
        #address-cells = <2>;
        #size-cells = <2>;

        scpsys: syscon@10006000 {
            compatible = "syscon", "simple-mfd";
            reg = <0 0x10006000 0 0x1000>;

            spm: power-controller {
                compatible = "mediatek,mt8173-power-controller";
                #address-cells = <1>;
                #size-cells = <0>;
                #power-domain-cells = <1>;

                /* power domains of the SoC */
                power-domain@MT8173_POWER_DOMAIN_VDEC {
                    reg = <MT8173_POWER_DOMAIN_VDEC>;
                    clocks = <&topckgen CLK_TOP_MM_SEL>;
                    clock-names = "mm";
                    #power-domain-cells = <0>;
                };
                power-domain@MT8173_POWER_DOMAIN_VENC {
                    reg = <MT8173_POWER_DOMAIN_VENC>;
                    clocks = <&topckgen CLK_TOP_MM_SEL>,
                             <&topckgen CLK_TOP_VENC_SEL>;
                    clock-names = "mm", "venc";
                    #power-domain-cells = <0>;
                };
                power-domain@MT8173_POWER_DOMAIN_ISP {
                    reg = <MT8173_POWER_DOMAIN_ISP>;
                    clocks = <&topckgen CLK_TOP_MM_SEL>;
                    clock-names = "mm";
                    #power-domain-cells = <0>;
                };
                power-domain@MT8173_POWER_DOMAIN_MM {
                    reg = <MT8173_POWER_DOMAIN_MM>;
                    clocks = <&topckgen CLK_TOP_MM_SEL>;
                    clock-names = "mm";
                    #power-domain-cells = <0>;
                    mediatek,infracfg = <&infracfg>;
                };
                power-domain@MT8173_POWER_DOMAIN_VENC_LT {
                    reg = <MT8173_POWER_DOMAIN_VENC_LT>;
                    clocks = <&topckgen CLK_TOP_MM_SEL>,
                             <&topckgen CLK_TOP_VENC_LT_SEL>;
                    clock-names = "mm", "venclt";
                    #power-domain-cells = <0>;
                };
                power-domain@MT8173_POWER_DOMAIN_AUDIO {
                    reg = <MT8173_POWER_DOMAIN_AUDIO>;
                    #power-domain-cells = <0>;
                };
                power-domain@MT8173_POWER_DOMAIN_USB {
                    reg = <MT8173_POWER_DOMAIN_USB>;
                    #power-domain-cells = <0>;
                };
                power-domain@MT8173_POWER_DOMAIN_MFG_ASYNC {
                    reg = <MT8173_POWER_DOMAIN_MFG_ASYNC>;
                    clocks = <&clk26m>;
                    clock-names = "mfg";
                    #address-cells = <1>;
                    #size-cells = <0>;
                    #power-domain-cells = <1>;

                    power-domain@MT8173_POWER_DOMAIN_MFG_2D {
                        reg = <MT8173_POWER_DOMAIN_MFG_2D>;
                        #address-cells = <1>;
                        #size-cells = <0>;
                        #power-domain-cells = <1>;

                        power-domain@MT8173_POWER_DOMAIN_MFG {
                            reg = <MT8173_POWER_DOMAIN_MFG>;
                            #power-domain-cells = <0>;
                            mediatek,infracfg = <&infracfg>;
                        };
                    };
                };
            };
        };
    };