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 Sensor bindings for the sensors based on SCPI Message Protocol
  60 --------------------------------------------------------------
  61 SCPI provides an API to access the various sensors on the SoC.
  62
  63 Required properties:
  64 - compatible : should be "arm,scpi-sensors".
  65 - #thermal-sensor-cells: should be set to 1. This property follows the
  66                          thermal device tree bindings[2].
  67
  68                          Valid cell values are raw identifiers (Sensor ID)
  69                          as used by the firmware. Refer to  platform details
  70                          for your implementation for the IDs to use.
  71
  72 Power domain bindings for the power domains based on SCPI Message Protocol
  73 ------------------------------------------------------------
  74
  75 This binding uses the generic power domain binding[4].
  76
  77 PM domain providers
  78 ===================
  79
  80 Required properties:
  81  - #power-domain-cells : Should be 1. Contains the device or the power
  82                          domain ID value used by SCPI commands.
  83  - num-domains: Total number of power domains provided by SCPI. This is
  84                 needed as the SCPI message protocol lacks a mechanism to
  85                 query this information at runtime.
  86
  87 PM domain consumers
  88 ===================
  89
  90 Required properties:
  91  - power-domains : A phandle and PM domain specifier as defined by bindings of
  92                    the power controller specified by phandle.
  93
  94 [0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html
  95 [1] Documentation/devicetree/bindings/clock/clock-bindings.txt
  96 [2] Documentation/devicetree/bindings/thermal/thermal*.yaml
  97 [3] Documentation/devicetree/bindings/sram/sram.yaml
  98 [4] Documentation/devicetree/bindings/power/power-domain.yaml
  99
 100 Example:
 101
 102 sram: sram@50000000 {
 103         compatible = "arm,juno-sram-ns", "mmio-sram";
 104         reg = <0x0 0x50000000 0x0 0x10000>;
 105
 106         #address-cells = <1>;
 107         #size-cells = <1>;
 108         ranges = <0 0x0 0x50000000 0x10000>;
 109
 110         cpu_scp_lpri: scp-shmem@0 {
 111                 compatible = "arm,juno-scp-shmem";
 112                 reg = <0x0 0x200>;
 113         };
 114
 115         cpu_scp_hpri: scp-shmem@200 {
 116                 compatible = "arm,juno-scp-shmem";
 117                 reg = <0x200 0x200>;
 118         };
 119 };
 120
 121 mailbox: mailbox0@40000000 {
 122         ....
 123         #mbox-cells = <1>;
 124 };
 125
 126 scpi_protocol: scpi@2e000000 {
 127         compatible = "arm,scpi";
 128         mboxes = <&mailbox 0 &mailbox 1>;
 129         shmem = <&cpu_scp_lpri &cpu_scp_hpri>;
 130
 131         clocks {
 132                 compatible = "arm,scpi-clocks";
 133
 134                 scpi_dvfs: scpi_clocks@0 {
 135                         compatible = "arm,scpi-dvfs-clocks";
 136                         #clock-cells = <1>;
 137                         clock-indices = <0>, <1>, <2>;
 138                         clock-output-names = "atlclk", "aplclk","gpuclk";
 139                 };
 140                 scpi_clk: scpi_clocks@3 {
 141                         compatible = "arm,scpi-variable-clocks";
 142                         #clock-cells = <1>;
 143                         clock-indices = <3>, <4>;
 144                         clock-output-names = "pxlclk0", "pxlclk1";
 145                 };
 146         };
 147
 148         scpi_sensors0: sensors {
 149                 compatible = "arm,scpi-sensors";
 150                 #thermal-sensor-cells = <1>;
 151         };
 152
 153         scpi_devpd: scpi-power-domains {
 154                 compatible = "arm,scpi-power-domains";
 155                 num-domains = <2>;
 156                 #power-domain-cells = <1>;
 157         };
 158 };
 159
 160 cpu@0 {
 161         ...
 162         reg = <0 0>;
 163         clocks = <&scpi_dvfs 0>;
 164 };
 165
 166 hdlcd@7ff60000 {
 167         ...
 168         reg = <0 0x7ff60000 0 0x1000>;
 169         clocks = <&scpi_clk 4>;
 170         power-domains = <&scpi_devpd 1>;
 171 };
 172
 173 thermal-zones {
 174         soc_thermal {
 175                 polling-delay-passive = <100>;
 176                 polling-delay = <1000>;
 177
 178                                 /* sensor         ID */
 179                 thermal-sensors = <&scpi_sensors0 3>;
 180                 ...
 181         };
 182 };
 183
 184 In the above example, the #clock-cells is set to 1 as required.
 185 scpi_dvfs has 3 output clocks namely: atlclk, aplclk, and gpuclk with 0,
 186 1 and 2 as clock-indices. scpi_clk has 2 output clocks namely: pxlclk0
 187 and pxlclk1 with 3 and 4 as clock-indices.
 188
 189 The first consumer in the example is cpu@0 and it has '0' as the clock
 190 specifier which points to the first entry in the output clocks of
 191 scpi_dvfs i.e. "atlclk".
 192
 193 Similarly the second example is hdlcd@7ff60000 and it has pxlclk1 as input
 194 clock. '4' in the clock specifier here points to the second entry
 195 in the output clocks of scpi_clocks  i.e. "pxlclk1"
 196
 197 The thermal-sensors property in the soc_thermal node uses the
 198 temperature sensor provided by SCP firmware to setup a thermal
 199 zone. The ID "3" is the sensor identifier for the temperature sensor
 200 as used by the firmware.
 201
 202 The num-domains property in scpi-power-domains domain specifies that
 203 SCPI provides 2 power domains. The hdlcd node uses the power domain with
 204 domain ID 1.