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 ../../misc/sysram.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 [0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html
  91 [1] Documentation/devicetree/bindings/clock/clock-bindings.txt
  92 [2] Documentation/devicetree/bindings/thermal/thermal.txt
  93 [3] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0922b/apas03s22.html
  94
  95 Example:
  96
  97 sram: sram@50000000 {
  98         compatible = "arm,juno-sram-ns", "mmio-sram";
  99         reg = <0x0 0x50000000 0x0 0x10000>;
 100
 101         #address-cells = <1>;
 102         #size-cells = <1>;
 103         ranges = <0 0x0 0x50000000 0x10000>;
 104
 105         cpu_scp_lpri: scp-shmem@0 {
 106                 compatible = "arm,juno-scp-shmem";
 107                 reg = <0x0 0x200>;
 108         };
 109
 110         cpu_scp_hpri: scp-shmem@200 {
 111                 compatible = "arm,juno-scp-shmem";
 112                 reg = <0x200 0x200>;
 113         };
 114 };
 115
 116 mailbox: mailbox0@40000000 {
 117         ....
 118         #mbox-cells = <1>;
 119 };
 120
 121 scpi_protocol: scpi@2e000000 {
 122         compatible = "arm,scpi";
 123         mboxes = <&mailbox 0 &mailbox 1>;
 124         shmem = <&cpu_scp_lpri &cpu_scp_hpri>;
 125
 126         clocks {
 127                 compatible = "arm,scpi-clocks";
 128
 129                 scpi_dvfs: scpi_clocks@0 {
 130                         compatible = "arm,scpi-dvfs-clocks";
 131                         #clock-cells = <1>;
 132                         clock-indices = <0>, <1>, <2>;
 133                         clock-output-names = "atlclk", "aplclk","gpuclk";
 134                 };
 135                 scpi_clk: scpi_clocks@3 {
 136                         compatible = "arm,scpi-variable-clocks";
 137                         #clock-cells = <1>;
 138                         clock-indices = <3>, <4>;
 139                         clock-output-names = "pxlclk0", "pxlclk1";
 140                 };
 141         };
 142
 143         scpi_sensors0: sensors {
 144                 compatible = "arm,scpi-sensors";
 145                 #thermal-sensor-cells = <1>;
 146         };
 147 };
 148
 149 cpu@0 {
 150         ...
 151         reg = <0 0>;
 152         clocks = <&scpi_dvfs 0>;
 153 };
 154
 155 hdlcd@7ff60000 {
 156         ...
 157         reg = <0 0x7ff60000 0 0x1000>;
 158         clocks = <&scpi_clk 4>;
 159 };
 160
 161 thermal-zones {
 162         soc_thermal {
 163                 polling-delay-passive = <100>;
 164                 polling-delay = <1000>;
 165
 166                                 /* sensor         ID */
 167                 thermal-sensors = <&scpi_sensors0 3>;
 168                 ...
 169         };
 170 };
 171
 172 In the above example, the #clock-cells is set to 1 as required.
 173 scpi_dvfs has 3 output clocks namely: atlclk, aplclk, and gpuclk with 0,
 174 1 and 2 as clock-indices. scpi_clk has 2 output clocks namely: pxlclk0
 175 and pxlclk1 with 3 and 4 as clock-indices.
 176
 177 The first consumer in the example is cpu@0 and it has '0' as the clock
 178 specifier which points to the first entry in the output clocks of
 179 scpi_dvfs i.e. "atlclk".
 180
 181 Similarly the second example is hdlcd@7ff60000 and it has pxlclk1 as input
 182 clock. '4' in the clock specifier here points to the second entry
 183 in the output clocks of scpi_clocks  i.e. "pxlclk1"
 184
 185 The thermal-sensors property in the soc_thermal node uses the
 186 temperature sensor provided by SCP firmware to setup a thermal
 187 zone. The ID "3" is the sensor identifier for the temperature sensor
 188 as used by the firmware.