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