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