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