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     $ref: /schemas/types.yaml#/definitions/string-array
  73     enum:
  74       - smc
  75       # HVC #0, with the register assignments specified in this binding.
  76       - hvc
  77
  78   cpu_suspend:
  79     $ref: /schemas/types.yaml#/definitions/uint32
  80     description: Function ID for CPU_SUSPEND operation
  81
  82   cpu_off:
  83     $ref: /schemas/types.yaml#/definitions/uint32
  84     description: Function ID for CPU_OFF operation
  85
  86   cpu_on:
  87     $ref: /schemas/types.yaml#/definitions/uint32
  88     description: Function ID for CPU_ON operation
  89
  90   migrate:
  91     $ref: /schemas/types.yaml#/definitions/uint32
  92     description: Function ID for MIGRATE operation
  93
  94   arm,psci-suspend-param:
  95     $ref: /schemas/types.yaml#/definitions/uint32
  96     description: |
  97       power_state parameter to pass to the PSCI suspend call.
  98
  99       Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie
 100       idle state nodes with entry-method property is set to "psci", as per
 101       bindings in [1]) must specify this property.
 102
 103       [1] Kernel documentation - ARM idle states bindings
 104         Documentation/devicetree/bindings/arm/idle-states.yaml
 105
 106 patternProperties:
 107   "^power-domain-":
 108     $ref: "../power/power-domain.yaml#"
 109
 110     type: object
 111     description: |
 112       ARM systems can have multiple cores, sometimes in an hierarchical
 113       arrangement. This often, but not always, maps directly to the processor
 114       power topology of the system. Individual nodes in a topology have their
 115       own specific power states and can be better represented hierarchically.
 116
 117       For these cases, the definitions of the idle states for the CPUs and the
 118       CPU topology, must conform to the binding in [3]. The idle states
 119       themselves must conform to the binding in [4] and must specify the
 120       arm,psci-suspend-param property.
 121
 122       It should also be noted that, in PSCI firmware v1.0 the OS-Initiated
 123       (OSI) CPU suspend mode is introduced. Using a hierarchical representation
 124       helps to implement support for OSI mode and OS implementations may choose
 125       to mandate it.
 126
 127       [3] Documentation/devicetree/bindings/power/power-domain.yaml
 128       [4] Documentation/devicetree/bindings/power/domain-idle-state.yaml
 129
 130 required:
 131   - compatible
 132   - method
 133
 134 allOf:
 135   - if:
 136       properties:
 137         compatible:
 138           contains:
 139             const: arm,psci
 140     then:
 141       required:
 142         - cpu_off
 143         - cpu_on
 144
 145 additionalProperties: false
 146
 147 examples:
 148   - |+
 149
 150     // Case 1: PSCI v0.1 only.
 151
 152     psci {
 153       compatible      = "arm,psci";
 154       method          = "smc";
 155       cpu_suspend     = <0x95c10000>;
 156       cpu_off         = <0x95c10001>;
 157       cpu_on          = <0x95c10002>;
 158       migrate         = <0x95c10003>;
 159     };
 160
 161   - |+
 162
 163     // Case 2: PSCI v0.2 only
 164
 165     psci {
 166       compatible      = "arm,psci-0.2";
 167       method          = "smc";
 168     };
 169
 170
 171   - |+
 172
 173     // Case 3: PSCI v0.2 and PSCI v0.1.
 174
 175     /*
 176      * A DTB may provide IDs for use by kernels without PSCI 0.2 support,
 177      * enabling firmware and hypervisors to support existing and new kernels.
 178      * These IDs will be ignored by kernels with PSCI 0.2 support, which will
 179      * use the standard PSCI 0.2 IDs exclusively.
 180      */
 181
 182     psci {
 183       compatible = "arm,psci-0.2", "arm,psci";
 184       method = "hvc";
 185
 186       cpu_on = <0x95c10002>;
 187       cpu_off = <0x95c10001>;
 188     };
 189
 190   - |+
 191
 192     // Case 4: CPUs and CPU idle states described using the hierarchical model.
 193
 194     cpus {
 195       #size-cells = <0>;
 196       #address-cells = <1>;
 197
 198       CPU0: cpu@0 {
 199         device_type = "cpu";
 200         compatible = "arm,cortex-a53";
 201         reg = <0x0>;
 202         enable-method = "psci";
 203         power-domains = <&CPU_PD0>;
 204         power-domain-names = "psci";
 205       };
 206
 207       CPU1: cpu@1 {
 208         device_type = "cpu";
 209         compatible = "arm,cortex-a53";
 210         reg = <0x100>;
 211         enable-method = "psci";
 212         power-domains = <&CPU_PD1>;
 213         power-domain-names = "psci";
 214       };
 215
 216       idle-states {
 217
 218         CPU_PWRDN: cpu-power-down {
 219           compatible = "arm,idle-state";
 220           arm,psci-suspend-param = <0x0000001>;
 221           entry-latency-us = <10>;
 222           exit-latency-us = <10>;
 223           min-residency-us = <100>;
 224         };
 225       };
 226
 227       domain-idle-states {
 228
 229         CLUSTER_RET: cluster-retention {
 230           compatible = "domain-idle-state";
 231           arm,psci-suspend-param = <0x1000011>;
 232           entry-latency-us = <500>;
 233           exit-latency-us = <500>;
 234           min-residency-us = <2000>;
 235         };
 236
 237         CLUSTER_PWRDN: cluster-power-down {
 238           compatible = "domain-idle-state";
 239           arm,psci-suspend-param = <0x1000031>;
 240           entry-latency-us = <2000>;
 241           exit-latency-us = <2000>;
 242           min-residency-us = <6000>;
 243         };
 244       };
 245     };
 246
 247     psci {
 248       compatible = "arm,psci-1.0";
 249       method = "smc";
 250
 251       CPU_PD0: power-domain-cpu0 {
 252         #power-domain-cells = <0>;
 253         domain-idle-states = <&CPU_PWRDN>;
 254         power-domains = <&CLUSTER_PD>;
 255       };
 256
 257       CPU_PD1: power-domain-cpu1 {
 258         #power-domain-cells = <0>;
 259         domain-idle-states =  <&CPU_PWRDN>;
 260         power-domains = <&CLUSTER_PD>;
 261       };
 262
 263       CLUSTER_PD: power-domain-cluster {
 264         #power-domain-cells = <0>;
 265         domain-idle-states = <&CLUSTER_RET>, <&CLUSTER_PWRDN>;
 266       };
 267     };
 268 ...