Documentation/devicetree/bindings/arm/arm,scpi.txt

   1 System Control and Power Interface (SCPI) Message Protocol
   2 ----------------------------------------------------------
   3
   4 Firmware implementing the SCPI described in ARM document number ARM DUI 0922B
   5 ("ARM Compute Subsystem SCP: Message Interface Protocols")[0] can be used
   6 by Linux to initiate various system control and power operations.
   7
   8 Required properties:
   9
  10 - compatible : should be
  11         * "arm,scpi" : For implementations complying to SCPI v1.0 or above
  12         * "arm,scpi-pre-1.0" : For implementations complying to all
  13                 unversioned releases prior to SCPI v1.0
  14 - mboxes: List of phandle and mailbox channel specifiers
  15           All the channels reserved by remote SCP firmware for use by
  16           SCPI message protocol should be specified in any order
  17 - shmem : List of phandle pointing to the shared memory(SHM) area between the
  18           processors using these mailboxes for IPC, one for each mailbox
  19           SHM can be any memory reserved for the purpose of this communication
  20           between the processors.
  21
  22 See Documentation/devicetree/bindings/mailbox/mailbox.txt
  23 for more details about the generic mailbox controller and
  24 client driver bindings.
  25
  26 Clock bindings for the clocks based on SCPI Message Protocol
  27 ------------------------------------------------------------
  28
  29 This binding uses the common clock binding[1].
  30
  31 Container Node
  32 ==============
  33 Required properties:
  34 - compatible : should be "arm,scpi-clocks"
  35                All the clocks provided by SCP firmware via SCPI message
  36                protocol much be listed as sub-nodes under this node.
  37
  38 Sub-nodes
  39 =========
  40 Required properties:
  41 - compatible : shall include one of the following
  42         "arm,scpi-dvfs-clocks" - all the clocks that are variable and index based.
  43                 These clocks don't provide an entire range of values between the
  44                 limits but only discrete points within the range. The firmware
  45                 provides the mapping for each such operating frequency and the
  46                 index associated with it. The firmware also manages the
  47                 voltage scaling appropriately with the clock scaling.
  48         "arm,scpi-variable-clocks" - all the clocks that are variable and provide full
  49                 range within the specified range. The firmware provides the
  50                 range of values within a specified range.
  51
  52 Other required properties for all clocks(all from common clock binding):
  53 - #clock-cells : Should be 1. Contains the Clock ID value used by SCPI commands.
  54 - clock-output-names : shall be the corresponding names of the outputs.
  55 - clock-indices: The identifying number for the clocks(i.e.clock_id) in the
  56         node. It can be non linear and hence provide the mapping of identifiers
  57         into the clock-output-names array.
  58
  59 SRAM and Shared Memory for SCPI
  60 -------------------------------
  61
  62 A small area of SRAM is reserved for SCPI communication between application
  63 processors and SCP.
  64
  65 The properties should follow the generic mmio-sram description found in [3]
  66
  67 Each sub-node represents the reserved area for SCPI.
  68
  69 Required sub-node properties:
  70 - reg : The base offset and size of the reserved area with the SRAM
  71 - compatible : should be "arm,scp-shmem" for Non-secure SRAM based
  72                shared memory
  73
  74 Sensor bindings for the sensors based on SCPI Message Protocol
  75 --------------------------------------------------------------
  76 SCPI provides an API to access the various sensors on the SoC.
  77
  78 Required properties:
  79 - compatible : should be "arm,scpi-sensors".
  80 - #thermal-sensor-cells: should be set to 1. This property follows the
  81                          thermal device tree bindings[2].
  82
  83                          Valid cell values are raw identifiers (Sensor ID)
  84                          as used by the firmware. Refer to  platform details
  85                          for your implementation for the IDs to use.
  86
  87 Power domain bindings for the power domains based on SCPI Message Protocol
  88 ------------------------------------------------------------
  89
  90 This binding uses the generic power domain binding[4].
  91
  92 PM domain providers
  93 ===================
  94
  95 Required properties:
  96  - #power-domain-cells : Should be 1. Contains the device or the power
  97                          domain ID value used by SCPI commands.
  98  - num-domains: Total number of power domains provided by SCPI. This is
  99                 needed as the SCPI message protocol lacks a mechanism to
 100                 query this information at runtime.
 101
 102 PM domain consumers
 103 ===================
 104
 105 Required properties:
 106  - power-domains : A phandle and PM domain specifier as defined by bindings of
 107                    the power controller specified by phandle.
 108
 109 [0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html
 110 [1] Documentation/devicetree/bindings/clock/clock-bindings.txt
 111 [2] Documentation/devicetree/bindings/thermal/thermal.txt
 112 [3] Documentation/devicetree/bindings/sram/sram.txt
 113 [4] Documentation/devicetree/bindings/power/power_domain.txt
 114
 115 Example:
 116
 117 sram: sram@50000000 {
 118         compatible = "arm,juno-sram-ns", "mmio-sram";
 119         reg = <0x0 0x50000000 0x0 0x10000>;
 120
 121         #address-cells = <1>;
 122         #size-cells = <1>;
 123         ranges = <0 0x0 0x50000000 0x10000>;
 124
 125         cpu_scp_lpri: scp-shmem@0 {
 126                 compatible = "arm,juno-scp-shmem";
 127                 reg = <0x0 0x200>;
 128         };
 129
 130         cpu_scp_hpri: scp-shmem@200 {
 131                 compatible = "arm,juno-scp-shmem";
 132                 reg = <0x200 0x200>;
 133         };
 134 };
 135
 136 mailbox: mailbox0@40000000 {
 137         ....
 138         #mbox-cells = <1>;
 139 };
 140
 141 scpi_protocol: scpi@2e000000 {
 142         compatible = "arm,scpi";
 143         mboxes = <&mailbox 0 &mailbox 1>;
 144         shmem = <&cpu_scp_lpri &cpu_scp_hpri>;
 145
 146         clocks {
 147                 compatible = "arm,scpi-clocks";
 148
 149                 scpi_dvfs: scpi_clocks@0 {
 150                         compatible = "arm,scpi-dvfs-clocks";
 151                         #clock-cells = <1>;
 152                         clock-indices = <0>, <1>, <2>;
 153                         clock-output-names = "atlclk", "aplclk","gpuclk";
 154                 };
 155                 scpi_clk: scpi_clocks@3 {
 156                         compatible = "arm,scpi-variable-clocks";
 157                         #clock-cells = <1>;
 158                         clock-indices = <3>, <4>;
 159                         clock-output-names = "pxlclk0", "pxlclk1";
 160                 };
 161         };
 162
 163         scpi_sensors0: sensors {
 164                 compatible = "arm,scpi-sensors";
 165                 #thermal-sensor-cells = <1>;
 166         };
 167
 168         scpi_devpd: scpi-power-domains {
 169                 compatible = "arm,scpi-power-domains";
 170                 num-domains = <2>;
 171                 #power-domain-cells = <1>;
 172         };
 173 };
 174
 175 cpu@0 {
 176         ...
 177         reg = <0 0>;
 178         clocks = <&scpi_dvfs 0>;
 179 };
 180
 181 hdlcd@7ff60000 {
 182         ...
 183         reg = <0 0x7ff60000 0 0x1000>;
 184         clocks = <&scpi_clk 4>;
 185         power-domains = <&scpi_devpd 1>;
 186 };
 187
 188 thermal-zones {
 189         soc_thermal {
 190                 polling-delay-passive = <100>;
 191                 polling-delay = <1000>;
 192
 193                                 /* sensor         ID */
 194                 thermal-sensors = <&scpi_sensors0 3>;
 195                 ...
 196         };
 197 };
 198
 199 In the above example, the #clock-cells is set to 1 as required.
 200 scpi_dvfs has 3 output clocks namely: atlclk, aplclk, and gpuclk with 0,
 201 1 and 2 as clock-indices. scpi_clk has 2 output clocks namely: pxlclk0
 202 and pxlclk1 with 3 and 4 as clock-indices.
 203
 204 The first consumer in the example is cpu@0 and it has '0' as the clock
 205 specifier which points to the first entry in the output clocks of
 206 scpi_dvfs i.e. "atlclk".
 207
 208 Similarly the second example is hdlcd@7ff60000 and it has pxlclk1 as input
 209 clock. '4' in the clock specifier here points to the second entry
 210 in the output clocks of scpi_clocks  i.e. "pxlclk1"
 211
 212 The thermal-sensors property in the soc_thermal node uses the
 213 temperature sensor provided by SCP firmware to setup a thermal
 214 zone. The ID "3" is the sensor identifier for the temperature sensor
 215 as used by the firmware.
 216
 217 The num-domains property in scpi-power-domains domain specifies that
 218 SCPI provides 2 power domains. The hdlcd node uses the power domain with
 219 domain ID 1.