1System Control and Power Interface (SCPI) Message Protocol
2----------------------------------------------------------
3
4Firmware implementing the SCPI described in ARM document number ARM DUI 0922B
5("ARM Compute Subsystem SCP: Message Interface Protocols")[0] can be used
6by Linux to initiate various system control and power operations.
7
8Required 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
22See Documentation/devicetree/bindings/mailbox/mailbox.txt
23for more details about the generic mailbox controller and
24client driver bindings.
25
26Clock bindings for the clocks based on SCPI Message Protocol
27------------------------------------------------------------
28
29This binding uses the common clock binding[1].
30
31Container Node
32==============
33Required 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
38Sub-nodes
39=========
40Required 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
52Other 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
59SRAM and Shared Memory for SCPI
60-------------------------------
61
62A small area of SRAM is reserved for SCPI communication between application
63processors and SCP.
64
65The properties should follow the generic mmio-sram description found in [3]
66
67Each sub-node represents the reserved area for SCPI.
68
69Required 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
74Sensor bindings for the sensors based on SCPI Message Protocol
75--------------------------------------------------------------
76SCPI provides an API to access the various sensors on the SoC.
77
78Required 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
87Power domain bindings for the power domains based on SCPI Message Protocol
88------------------------------------------------------------
89
90This binding uses the generic power domain binding[4].
91
92PM domain providers
93===================
94
95Required 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
102PM domain consumers
103===================
104
105Required 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*.yaml
112[3] Documentation/devicetree/bindings/sram/sram.yaml
113[4] Documentation/devicetree/bindings/power/power-domain.yaml
114
115Example:
116
117sram: 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
136mailbox: mailbox0@40000000 {
137	....
138	#mbox-cells = <1>;
139};
140
141scpi_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
175cpu@0 {
176	...
177	reg = <0 0>;
178	clocks = <&scpi_dvfs 0>;
179};
180
181hdlcd@7ff60000 {
182	...
183	reg = <0 0x7ff60000 0 0x1000>;
184	clocks = <&scpi_clk 4>;
185	power-domains = <&scpi_devpd 1>;
186};
187
188thermal-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
199In the above example, the #clock-cells is set to 1 as required.
200scpi_dvfs has 3 output clocks namely: atlclk, aplclk, and gpuclk with 0,
2011 and 2 as clock-indices. scpi_clk has 2 output clocks namely: pxlclk0
202and pxlclk1 with 3 and 4 as clock-indices.
203
204The first consumer in the example is cpu@0 and it has '0' as the clock
205specifier which points to the first entry in the output clocks of
206scpi_dvfs i.e. "atlclk".
207
208Similarly the second example is hdlcd@7ff60000 and it has pxlclk1 as input
209clock. '4' in the clock specifier here points to the second entry
210in the output clocks of scpi_clocks  i.e. "pxlclk1"
211
212The thermal-sensors property in the soc_thermal node uses the
213temperature sensor provided by SCP firmware to setup a thermal
214zone. The ID "3" is the sensor identifier for the temperature sensor
215as used by the firmware.
216
217The num-domains property in scpi-power-domains domain specifies that
218SCPI provides 2 power domains. The hdlcd node uses the power domain with
219domain ID 1.
220