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