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.txt
 104
 105
 106 required:
 107   - compatible
 108   - method
 109
 110 allOf:
 111   - if:
 112       properties:
 113         compatible:
 114           contains:
 115             const: arm,psci
 116     then:
 117       required:
 118         - cpu_off
 119         - cpu_on
 120
 121 examples:
 122   - |+
 123
 124     // Case 1: PSCI v0.1 only.
 125
 126     psci {
 127       compatible      = "arm,psci";
 128       method          = "smc";
 129       cpu_suspend     = <0x95c10000>;
 130       cpu_off         = <0x95c10001>;
 131       cpu_on          = <0x95c10002>;
 132       migrate         = <0x95c10003>;
 133     };
 134
 135   - |+
 136
 137     // Case 2: PSCI v0.2 only
 138
 139     psci {
 140       compatible      = "arm,psci-0.2";
 141       method          = "smc";
 142     };
 143
 144
 145   - |+
 146
 147     // Case 3: PSCI v0.2 and PSCI v0.1.
 148
 149     /*
 150      * A DTB may provide IDs for use by kernels without PSCI 0.2 support,
 151      * enabling firmware and hypervisors to support existing and new kernels.
 152      * These IDs will be ignored by kernels with PSCI 0.2 support, which will
 153      * use the standard PSCI 0.2 IDs exclusively.
 154      */
 155
 156     psci {
 157       compatible = "arm,psci-0.2", "arm,psci";
 158       method = "hvc";
 159
 160       cpu_on = <0x95c10002>;
 161       cpu_off = <0x95c10001>;
 162     };
 163 ...