Documentation/devicetree/bindings/arm/psci.yaml

   1 # SPDX-License-Identifier: GPL-2.0
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/arm/psci.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: Power State Coordination Interface (PSCI)
   8
   9 maintainers:
  10   - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
  11
  12 description: |+
  13   Firmware implementing the PSCI functions described in ARM document number
  14   ARM DEN 0022A ("Power State Coordination Interface System Software on ARM
  15   processors") can be used by Linux to initiate various CPU-centric power
  16   operations.
  17
  18   Issue A of the specification describes functions for CPU suspend, hotplug
  19   and migration of secure software.
  20
  21   Functions are invoked by trapping to the privilege level of the PSCI
  22   firmware (specified as part of the binding below) and passing arguments
  23   in a manner similar to that specified by AAPCS:
  24
  25      r0       => 32-bit Function ID / return value
  26     {r1 - r3}   => Parameters
  27
  28   Note that the immediate field of the trapping instruction must be set
  29   to #0.
  30
  31   [2] Power State Coordination Interface (PSCI) specification
  32     http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
  33
  34 properties:
  35   $nodename:
  36     const: psci
  37
  38   compatible:
  39     oneOf:
  40       - description:
  41           For implementations complying to PSCI versions prior to 0.2.
  42         const: arm,psci
  43
  44       - description:
  45           For implementations complying to PSCI 0.2.
  46         const: arm,psci-0.2
  47
  48       - description:
  49           For implementations complying to PSCI 0.2.
  50           Function IDs are not required and should be ignored by an OS with
  51           PSCI 0.2 support, but are permitted to be present for compatibility
  52           with existing software when "arm,psci" is later in the compatible
  53           list.
  54         items:
  55           - const: arm,psci-0.2
  56           - const: arm,psci
  57
  58       - description:
  59           For implementations complying to PSCI 1.0.
  60         const: arm,psci-1.0
  61
  62       - description:
  63           For implementations complying to PSCI 1.0.
  64           PSCI 1.0 is backward compatible with PSCI 0.2 with minor
  65           specification updates, as defined in the PSCI specification[2].
  66         items:
  67           - const: arm,psci-1.0
  68           - const: arm,psci-0.2
  69
  70   method:
  71     description: The method of calling the PSCI firmware.
  72     allOf:
  73       - $ref: /schemas/types.yaml#/definitions/string-array
  74       - enum:
  75           # SMC #0, with the register assignments specified in this binding.
  76           - smc
  77           # HVC #0, with the register assignments specified in this binding.
  78           - hvc
  79
  80   cpu_suspend:
  81     $ref: /schemas/types.yaml#/definitions/uint32
  82     description: Function ID for CPU_SUSPEND operation
  83
  84   cpu_off:
  85     $ref: /schemas/types.yaml#/definitions/uint32
  86     description: Function ID for CPU_OFF operation
  87
  88   cpu_on:
  89     $ref: /schemas/types.yaml#/definitions/uint32
  90     description: Function ID for CPU_ON operation
  91
  92   migrate:
  93     $ref: /schemas/types.yaml#/definitions/uint32
  94     description: Function ID for MIGRATE operation
  95
  96   arm,psci-suspend-param:
  97     $ref: /schemas/types.yaml#/definitions/uint32
  98     description: |
  99       power_state parameter to pass to the PSCI suspend call.
 100
 101       Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie
 102       idle state nodes with entry-method property is set to "psci", as per
 103       bindings in [1]) must specify this property.
 104
 105       [1] Kernel documentation - ARM idle states bindings
 106         Documentation/devicetree/bindings/arm/idle-states.yaml
 107
 108 patternProperties:
 109   "^power-domain-":
 110     allOf:
 111       - $ref: "../power/power-domain.yaml#"
 112     type: object
 113     description: |
 114       ARM systems can have multiple cores, sometimes in an hierarchical
 115       arrangement. This often, but not always, maps directly to the processor
 116       power topology of the system. Individual nodes in a topology have their
 117       own specific power states and can be better represented hierarchically.
 118
 119       For these cases, the definitions of the idle states for the CPUs and the
 120       CPU topology, must conform to the binding in [3]. The idle states
 121       themselves must conform to the binding in [4] and must specify the
 122       arm,psci-suspend-param property.
 123
 124       It should also be noted that, in PSCI firmware v1.0 the OS-Initiated
 125       (OSI) CPU suspend mode is introduced. Using a hierarchical representation
 126       helps to implement support for OSI mode and OS implementations may choose
 127       to mandate it.
 128
 129       [3] Documentation/devicetree/bindings/power/power-domain.yaml
 130       [4] Documentation/devicetree/bindings/power/domain-idle-state.yaml
 131
 132 required:
 133   - compatible
 134   - method
 135
 136 allOf:
 137   - if:
 138       properties:
 139         compatible:
 140           contains:
 141             const: arm,psci
 142     then:
 143       required:
 144         - cpu_off
 145         - cpu_on
 146
 147 additionalProperties: false
 148
 149 examples:
 150   - |+
 151
 152     // Case 1: PSCI v0.1 only.
 153
 154     psci {
 155       compatible      = "arm,psci";
 156       method          = "smc";
 157       cpu_suspend     = <0x95c10000>;
 158       cpu_off         = <0x95c10001>;
 159       cpu_on          = <0x95c10002>;
 160       migrate         = <0x95c10003>;
 161     };
 162
 163   - |+
 164
 165     // Case 2: PSCI v0.2 only
 166
 167     psci {
 168       compatible      = "arm,psci-0.2";
 169       method          = "smc";
 170     };
 171
 172
 173   - |+
 174
 175     // Case 3: PSCI v0.2 and PSCI v0.1.
 176
 177     /*
 178      * A DTB may provide IDs for use by kernels without PSCI 0.2 support,
 179      * enabling firmware and hypervisors to support existing and new kernels.
 180      * These IDs will be ignored by kernels with PSCI 0.2 support, which will
 181      * use the standard PSCI 0.2 IDs exclusively.
 182      */
 183
 184     psci {
 185       compatible = "arm,psci-0.2", "arm,psci";
 186       method = "hvc";
 187
 188       cpu_on = <0x95c10002>;
 189       cpu_off = <0x95c10001>;
 190     };
 191
 192   - |+
 193
 194     // Case 4: CPUs and CPU idle states described using the hierarchical model.
 195
 196     cpus {
 197       #size-cells = <0>;
 198       #address-cells = <1>;
 199
 200       CPU0: cpu@0 {
 201         device_type = "cpu";
 202         compatible = "arm,cortex-a53";
 203         reg = <0x0>;
 204         enable-method = "psci";
 205         power-domains = <&CPU_PD0>;
 206         power-domain-names = "psci";
 207       };
 208
 209       CPU1: cpu@1 {
 210         device_type = "cpu";
 211         compatible = "arm,cortex-a53";
 212         reg = <0x100>;
 213         enable-method = "psci";
 214         power-domains = <&CPU_PD1>;
 215         power-domain-names = "psci";
 216       };
 217
 218       idle-states {
 219
 220         CPU_PWRDN: cpu-power-down {
 221           compatible = "arm,idle-state";
 222           arm,psci-suspend-param = <0x0000001>;
 223           entry-latency-us = <10>;
 224           exit-latency-us = <10>;
 225           min-residency-us = <100>;
 226         };
 227       };
 228
 229       domain-idle-states {
 230
 231         CLUSTER_RET: cluster-retention {
 232           compatible = "domain-idle-state";
 233           arm,psci-suspend-param = <0x1000011>;
 234           entry-latency-us = <500>;
 235           exit-latency-us = <500>;
 236           min-residency-us = <2000>;
 237         };
 238
 239         CLUSTER_PWRDN: cluster-power-down {
 240           compatible = "domain-idle-state";
 241           arm,psci-suspend-param = <0x1000031>;
 242           entry-latency-us = <2000>;
 243           exit-latency-us = <2000>;
 244           min-residency-us = <6000>;
 245         };
 246       };
 247     };
 248
 249     psci {
 250       compatible = "arm,psci-1.0";
 251       method = "smc";
 252
 253       CPU_PD0: power-domain-cpu0 {
 254         #power-domain-cells = <0>;
 255         domain-idle-states = <&CPU_PWRDN>;
 256         power-domains = <&CLUSTER_PD>;
 257       };
 258
 259       CPU_PD1: power-domain-cpu1 {
 260         #power-domain-cells = <0>;
 261         domain-idle-states =  <&CPU_PWRDN>;
 262         power-domains = <&CLUSTER_PD>;
 263       };
 264
 265       CLUSTER_PD: power-domain-cluster {
 266         #power-domain-cells = <0>;
 267         domain-idle-states = <&CLUSTER_RET>, <&CLUSTER_PWRDN>;
 268       };
 269     };
 270 ...