1System Control and Management Interface (SCMI) Message Protocol
2----------------------------------------------------------
3
4The SCMI is intended to allow agents such as OSPM to manage various functions
5that are provided by the hardware platform it is running on, including power
6and performance functions.
7
8This binding is intended to define the interface the firmware implementing
9the SCMI as described in ARM document number ARM DEN 0056A ("ARM System Control
10and Management Interface Platform Design Document")[0] provide for OSPM in
11the device tree.
12
13Required properties:
14
15The scmi node with the following properties shall be under the /firmware/ node.
16
17- compatible : shall be "arm,scmi" or "arm,scmi-smc" for smc/hvc transports
18- mboxes: List of phandle and mailbox channel specifiers. It should contain
19	  exactly one or two mailboxes, one for transmitting messages("tx")
20	  and another optional for receiving the notifications("rx") if
21	  supported.
22- shmem : List of phandle pointing to the shared memory(SHM) area as per
23	  generic mailbox client binding.
24- #address-cells : should be '1' if the device has sub-nodes, maps to
25	  protocol identifier for a given sub-node.
26- #size-cells : should be '0' as 'reg' property doesn't have any size
27	  associated with it.
28- arm,smc-id : SMC id required when using smc or hvc transports
29
30Optional properties:
31
32- mbox-names: shall be "tx" or "rx" depending on mboxes entries.
33
34See Documentation/devicetree/bindings/mailbox/mailbox.txt for more details
35about the generic mailbox controller and client driver bindings.
36
37The mailbox is the only permitted method of calling the SCMI firmware.
38Mailbox doorbell is used as a mechanism to alert the presence of a
39messages and/or notification.
40
41Each protocol supported shall have a sub-node with corresponding compatible
42as described in the following sections. If the platform supports dedicated
43communication channel for a particular protocol, the 3 properties namely:
44mboxes, mbox-names and shmem shall be present in the sub-node corresponding
45to that protocol.
46
47Clock/Performance bindings for the clocks/OPPs based on SCMI Message Protocol
48------------------------------------------------------------
49
50This binding uses the common clock binding[1].
51
52Required properties:
53- #clock-cells : Should be 1. Contains the Clock ID value used by SCMI commands.
54
55Power domain bindings for the power domains based on SCMI Message Protocol
56------------------------------------------------------------
57
58This binding for the SCMI power domain providers uses the generic power
59domain binding[2].
60
61Required properties:
62 - #power-domain-cells : Should be 1. Contains the device or the power
63			 domain ID value used by SCMI commands.
64
65Sensor bindings for the sensors based on SCMI Message Protocol
66--------------------------------------------------------------
67SCMI provides an API to access the various sensors on the SoC.
68
69Required properties:
70- #thermal-sensor-cells: should be set to 1. This property follows the
71			 thermal device tree bindings[3].
72
73			 Valid cell values are raw identifiers (Sensor ID)
74			 as used by the firmware. Refer to  platform details
75			 for your implementation for the IDs to use.
76
77Reset signal bindings for the reset domains based on SCMI Message Protocol
78------------------------------------------------------------
79
80This binding for the SCMI reset domain providers uses the generic reset
81signal binding[5].
82
83Required properties:
84 - #reset-cells : Should be 1. Contains the reset domain ID value used
85		  by SCMI commands.
86
87SRAM and Shared Memory for SCMI
88-------------------------------
89
90A small area of SRAM is reserved for SCMI communication between application
91processors and SCP.
92
93The properties should follow the generic mmio-sram description found in [4]
94
95Each sub-node represents the reserved area for SCMI.
96
97Required sub-node properties:
98- reg : The base offset and size of the reserved area with the SRAM
99- compatible : should be "arm,scmi-shmem" for Non-secure SRAM based
100	       shared memory
101
102[0] http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/index.html
103[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
104[2] Documentation/devicetree/bindings/power/power-domain.yaml
105[3] Documentation/devicetree/bindings/thermal/thermal.txt
106[4] Documentation/devicetree/bindings/sram/sram.yaml
107[5] Documentation/devicetree/bindings/reset/reset.txt
108
109Example:
110
111sram@50000000 {
112	compatible = "mmio-sram";
113	reg = <0x0 0x50000000 0x0 0x10000>;
114
115	#address-cells = <1>;
116	#size-cells = <1>;
117	ranges = <0 0x0 0x50000000 0x10000>;
118
119	cpu_scp_lpri: scp-shmem@0 {
120		compatible = "arm,scmi-shmem";
121		reg = <0x0 0x200>;
122	};
123
124	cpu_scp_hpri: scp-shmem@200 {
125		compatible = "arm,scmi-shmem";
126		reg = <0x200 0x200>;
127	};
128};
129
130mailbox@40000000 {
131	....
132	#mbox-cells = <1>;
133	reg = <0x0 0x40000000 0x0 0x10000>;
134};
135
136firmware {
137
138	...
139
140	scmi {
141		compatible = "arm,scmi";
142		mboxes = <&mailbox 0 &mailbox 1>;
143		mbox-names = "tx", "rx";
144		shmem = <&cpu_scp_lpri &cpu_scp_hpri>;
145		#address-cells = <1>;
146		#size-cells = <0>;
147
148		scmi_devpd: protocol@11 {
149			reg = <0x11>;
150			#power-domain-cells = <1>;
151		};
152
153		scmi_dvfs: protocol@13 {
154			reg = <0x13>;
155			#clock-cells = <1>;
156		};
157
158		scmi_clk: protocol@14 {
159			reg = <0x14>;
160			#clock-cells = <1>;
161		};
162
163		scmi_sensors0: protocol@15 {
164			reg = <0x15>;
165			#thermal-sensor-cells = <1>;
166		};
167
168		scmi_reset: protocol@16 {
169			reg = <0x16>;
170			#reset-cells = <1>;
171		};
172	};
173};
174
175cpu@0 {
176	...
177	reg = <0 0>;
178	clocks = <&scmi_dvfs 0>;
179};
180
181hdlcd@7ff60000 {
182	...
183	reg = <0 0x7ff60000 0 0x1000>;
184	clocks = <&scmi_clk 4>;
185	power-domains = <&scmi_devpd 1>;
186	resets = <&scmi_reset 10>;
187};
188
189thermal-zones {
190	soc_thermal {
191		polling-delay-passive = <100>;
192		polling-delay = <1000>;
193					/* sensor ID */
194		thermal-sensors = <&scmi_sensors0 3>;
195		...
196	};
197};
198