]>
Commit | Line | Data |
---|---|---|
80f390ea SH |
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 | ||
bc24108b SH |
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 | |
80f390ea SH |
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 | SRAM and Shared Memory for SCPI | |
60 | ------------------------------- | |
61 | ||
62 | A small area of SRAM is reserved for SCPI communication between application | |
63 | processors and SCP. | |
64 | ||
a90b15e0 | 65 | The properties should follow the generic mmio-sram description found in [3] |
80f390ea SH |
66 | |
67 | Each sub-node represents the reserved area for SCPI. | |
68 | ||
69 | Required sub-node properties: | |
70 | - reg : The base offset and size of the reserved area with the SRAM | |
a90b15e0 SH |
71 | - compatible : should be "arm,scp-shmem" for Non-secure SRAM based |
72 | shared memory | |
80f390ea | 73 | |
d8a44fe7 PA |
74 | Sensor bindings for the sensors based on SCPI Message Protocol |
75 | -------------------------------------------------------------- | |
76 | SCPI provides an API to access the various sensors on the SoC. | |
77 | ||
78 | Required 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 | ||
a90b15e0 SH |
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. | |
d8a44fe7 | 86 | |
43752b8d SH |
87 | Power domain bindings for the power domains based on SCPI Message Protocol |
88 | ------------------------------------------------------------ | |
89 | ||
90 | This binding uses the generic power domain binding[4]. | |
91 | ||
92 | PM domain providers | |
93 | =================== | |
94 | ||
95 | Required 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 | ||
102 | PM domain consumers | |
103 | =================== | |
104 | ||
105 | Required properties: | |
106 | - power-domains : A phandle and PM domain specifier as defined by bindings of | |
107 | the power controller specified by phandle. | |
108 | ||
80f390ea SH |
109 | [0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html |
110 | [1] Documentation/devicetree/bindings/clock/clock-bindings.txt | |
d8a44fe7 | 111 | [2] Documentation/devicetree/bindings/thermal/thermal.txt |
54b3719d | 112 | [3] Documentation/devicetree/bindings/sram/sram.yaml |
5279a3d8 | 113 | [4] Documentation/devicetree/bindings/power/power-domain.yaml |
80f390ea SH |
114 | |
115 | Example: | |
116 | ||
117 | sram: 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 | ||
136 | mailbox: mailbox0@40000000 { | |
137 | .... | |
138 | #mbox-cells = <1>; | |
139 | }; | |
140 | ||
141 | scpi_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 | }; | |
d8a44fe7 PA |
162 | |
163 | scpi_sensors0: sensors { | |
164 | compatible = "arm,scpi-sensors"; | |
165 | #thermal-sensor-cells = <1>; | |
166 | }; | |
43752b8d SH |
167 | |
168 | scpi_devpd: scpi-power-domains { | |
169 | compatible = "arm,scpi-power-domains"; | |
170 | num-domains = <2>; | |
171 | #power-domain-cells = <1>; | |
172 | }; | |
80f390ea SH |
173 | }; |
174 | ||
175 | cpu@0 { | |
176 | ... | |
177 | reg = <0 0>; | |
178 | clocks = <&scpi_dvfs 0>; | |
179 | }; | |
180 | ||
181 | hdlcd@7ff60000 { | |
182 | ... | |
183 | reg = <0 0x7ff60000 0 0x1000>; | |
184 | clocks = <&scpi_clk 4>; | |
43752b8d | 185 | power-domains = <&scpi_devpd 1>; |
80f390ea SH |
186 | }; |
187 | ||
d8a44fe7 PA |
188 | thermal-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 | ||
80f390ea SH |
199 | In the above example, the #clock-cells is set to 1 as required. |
200 | scpi_dvfs has 3 output clocks namely: atlclk, aplclk, and gpuclk with 0, | |
201 | 1 and 2 as clock-indices. scpi_clk has 2 output clocks namely: pxlclk0 | |
202 | and pxlclk1 with 3 and 4 as clock-indices. | |
203 | ||
204 | The first consumer in the example is cpu@0 and it has '0' as the clock | |
205 | specifier which points to the first entry in the output clocks of | |
206 | scpi_dvfs i.e. "atlclk". | |
207 | ||
208 | Similarly the second example is hdlcd@7ff60000 and it has pxlclk1 as input | |
209 | clock. '4' in the clock specifier here points to the second entry | |
210 | in the output clocks of scpi_clocks i.e. "pxlclk1" | |
d8a44fe7 PA |
211 | |
212 | The thermal-sensors property in the soc_thermal node uses the | |
213 | temperature sensor provided by SCP firmware to setup a thermal | |
214 | zone. The ID "3" is the sensor identifier for the temperature sensor | |
215 | as used by the firmware. | |
43752b8d SH |
216 | |
217 | The num-domains property in scpi-power-domains domain specifies that | |
218 | SCPI provides 2 power domains. The hdlcd node uses the power domain with | |
219 | domain ID 1. |