xref: /freebsd/sys/contrib/device-tree/Bindings/firmware/arm,scmi.yaml (revision 5ca8e32633c4ffbbcd6762e5888b6a4ba0708c6c) 
1# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
2# Copyright 2021 ARM Ltd.
3%YAML 1.2
4---
5$id: http://devicetree.org/schemas/firmware/arm,scmi.yaml#
6$schema: http://devicetree.org/meta-schemas/core.yaml#
7
8title: System Control and Management Interface (SCMI) Message Protocol
9
10maintainers:
11  - Sudeep Holla <sudeep.holla@arm.com>
12
13description: |
14  The SCMI is intended to allow agents such as OSPM to manage various functions
15  that are provided by the hardware platform it is running on, including power
16  and performance functions.
17
18  This binding is intended to define the interface the firmware implementing
19  the SCMI as described in ARM document number ARM DEN 0056 ("ARM System Control
20  and Management Interface Platform Design Document")[0] provide for OSPM in
21  the device tree.
22
23  [0] https://developer.arm.com/documentation/den0056/latest
24
25properties:
26  $nodename:
27    const: scmi
28
29  compatible:
30    oneOf:
31      - description: SCMI compliant firmware with mailbox transport
32        items:
33          - const: arm,scmi
34      - description: SCMI compliant firmware with ARM SMC/HVC transport
35        items:
36          - const: arm,scmi-smc
37      - description: SCMI compliant firmware with ARM SMC/HVC transport
38                     with shmem address(4KB-page, offset) as parameters
39        items:
40          - const: arm,scmi-smc-param
41      - description: SCMI compliant firmware with SCMI Virtio transport.
42                     The virtio transport only supports a single device.
43        items:
44          - const: arm,scmi-virtio
45      - description: SCMI compliant firmware with OP-TEE transport
46        items:
47          - const: linaro,scmi-optee
48
49  interrupts:
50    description:
51      The interrupt that indicates message completion by the platform
52      rather than by the return of the smc call. This should not be used
53      except when the platform requires such behavior.
54    maxItems: 1
55
56  interrupt-names:
57    const: a2p
58
59  mbox-names:
60    description:
61      Specifies the mailboxes used to communicate with SCMI compliant
62      firmware.
63    oneOf:
64      - items:
65          - const: tx
66          - const: rx
67        minItems: 1
68      - items:
69          - const: tx
70          - const: tx_reply
71          - const: rx
72        minItems: 2
73
74  mboxes:
75    description:
76      List of phandle and mailbox channel specifiers. It should contain
77      exactly one, two or three mailboxes; the first one or two for transmitting
78      messages ("tx") and another optional ("rx") for receiving notifications
79      and delayed responses, if supported by the platform.
80      The number of mailboxes needed for transmitting messages depends on the
81      type of channels exposed by the specific underlying mailbox controller;
82      one single channel descriptor is enough if such channel is bidirectional,
83      while two channel descriptors are needed to represent the SCMI ("tx")
84      channel if the underlying mailbox channels are of unidirectional type.
85      The effective combination in numbers of mboxes and shmem descriptors let
86      the SCMI subsystem determine unambiguosly which type of SCMI channels are
87      made available by the underlying mailbox controller and how to use them.
88       1 mbox / 1 shmem => SCMI TX over 1 mailbox bidirectional channel
89       2 mbox / 2 shmem => SCMI TX and RX over 2 mailbox bidirectional channels
90       2 mbox / 1 shmem => SCMI TX over 2 mailbox unidirectional channels
91       3 mbox / 2 shmem => SCMI TX and RX over 3 mailbox unidirectional channels
92      Any other combination of mboxes and shmem is invalid.
93    minItems: 1
94    maxItems: 3
95
96  shmem:
97    description:
98      List of phandle pointing to the shared memory(SHM) area, for each
99      transport channel specified.
100    minItems: 1
101    maxItems: 2
102
103  '#address-cells':
104    const: 1
105
106  '#size-cells':
107    const: 0
108
109  atomic-threshold-us:
110    description:
111      An optional time value, expressed in microseconds, representing, on this
112      platform, the threshold above which any SCMI command, advertised to have
113      an higher-than-threshold execution latency, should not be considered for
114      atomic mode of operation, even if requested.
115    default: 0
116
117  arm,smc-id:
118    $ref: /schemas/types.yaml#/definitions/uint32
119    description:
120      SMC id required when using smc or hvc transports
121
122  linaro,optee-channel-id:
123    $ref: /schemas/types.yaml#/definitions/uint32
124    description:
125      Channel specifier required when using OP-TEE transport.
126
127  protocol@11:
128    $ref: '#/$defs/protocol-node'
129    unevaluatedProperties: false
130
131    properties:
132      reg:
133        const: 0x11
134
135      '#power-domain-cells':
136        const: 1
137
138    required:
139      - '#power-domain-cells'
140
141  protocol@13:
142    $ref: '#/$defs/protocol-node'
143    unevaluatedProperties: false
144
145    properties:
146      reg:
147        const: 0x13
148
149      '#clock-cells':
150        const: 1
151
152    required:
153      - '#clock-cells'
154
155  protocol@14:
156    $ref: '#/$defs/protocol-node'
157    unevaluatedProperties: false
158
159    properties:
160      reg:
161        const: 0x14
162
163      '#clock-cells':
164        const: 1
165
166    required:
167      - '#clock-cells'
168
169  protocol@15:
170    $ref: '#/$defs/protocol-node'
171    unevaluatedProperties: false
172
173    properties:
174      reg:
175        const: 0x15
176
177      '#thermal-sensor-cells':
178        const: 1
179
180    required:
181      - '#thermal-sensor-cells'
182
183  protocol@16:
184    $ref: '#/$defs/protocol-node'
185    unevaluatedProperties: false
186
187    properties:
188      reg:
189        const: 0x16
190
191      '#reset-cells':
192        const: 1
193
194    required:
195      - '#reset-cells'
196
197  protocol@17:
198    $ref: '#/$defs/protocol-node'
199    unevaluatedProperties: false
200
201    properties:
202      reg:
203        const: 0x17
204
205      regulators:
206        type: object
207        additionalProperties: false
208        description:
209          The list of all regulators provided by this SCMI controller.
210
211        properties:
212          '#address-cells':
213            const: 1
214
215          '#size-cells':
216            const: 0
217
218        patternProperties:
219          '^regulator@[0-9a-f]+$':
220            type: object
221            $ref: /schemas/regulator/regulator.yaml#
222            unevaluatedProperties: false
223
224            properties:
225              reg:
226                maxItems: 1
227                description: Identifier for the voltage regulator.
228
229            required:
230              - reg
231
232  protocol@18:
233    $ref: '#/$defs/protocol-node'
234    unevaluatedProperties: false
235
236    properties:
237      reg:
238        const: 0x18
239
240additionalProperties: false
241
242$defs:
243  protocol-node:
244    type: object
245    description:
246      Each sub-node represents a protocol supported. If the platform
247      supports a dedicated communication channel for a particular protocol,
248      then the corresponding transport properties must be present.
249      The virtio transport does not support a dedicated communication channel.
250
251    properties:
252      reg:
253        maxItems: 1
254
255      mbox-names:
256        oneOf:
257          - items:
258              - const: tx
259              - const: rx
260            minItems: 1
261          - items:
262              - const: tx
263              - const: tx_reply
264              - const: rx
265            minItems: 2
266
267      mboxes:
268        minItems: 1
269        maxItems: 3
270
271      shmem:
272        minItems: 1
273        maxItems: 2
274
275      linaro,optee-channel-id:
276        $ref: /schemas/types.yaml#/definitions/uint32
277        description:
278          Channel specifier required when using OP-TEE transport and
279          protocol has a dedicated communication channel.
280
281    required:
282      - reg
283
284required:
285  - compatible
286
287if:
288  properties:
289    compatible:
290      contains:
291        const: arm,scmi
292then:
293  properties:
294    interrupts: false
295    interrupt-names: false
296
297  required:
298    - mboxes
299    - shmem
300
301else:
302  if:
303    properties:
304      compatible:
305        contains:
306          enum:
307            - arm,scmi-smc
308            - arm,scmi-smc-param
309  then:
310    required:
311      - arm,smc-id
312      - shmem
313
314  else:
315    if:
316      properties:
317        compatible:
318          contains:
319            const: linaro,scmi-optee
320    then:
321      required:
322        - linaro,optee-channel-id
323
324examples:
325  - |
326    firmware {
327        scmi {
328            compatible = "arm,scmi";
329            mboxes = <&mhuB 0 0>,
330                     <&mhuB 0 1>;
331            mbox-names = "tx", "rx";
332            shmem = <&cpu_scp_lpri0>,
333                    <&cpu_scp_lpri1>;
334
335            #address-cells = <1>;
336            #size-cells = <0>;
337
338            atomic-threshold-us = <10000>;
339
340            scmi_devpd: protocol@11 {
341                reg = <0x11>;
342                #power-domain-cells = <1>;
343            };
344
345            scmi_dvfs: protocol@13 {
346                reg = <0x13>;
347                #clock-cells = <1>;
348
349                mboxes = <&mhuB 1 0>,
350                         <&mhuB 1 1>;
351                mbox-names = "tx", "rx";
352                shmem = <&cpu_scp_hpri0>,
353                        <&cpu_scp_hpri1>;
354            };
355
356            scmi_clk: protocol@14 {
357                reg = <0x14>;
358                #clock-cells = <1>;
359            };
360
361            scmi_sensors: protocol@15 {
362                reg = <0x15>;
363                #thermal-sensor-cells = <1>;
364            };
365
366            scmi_reset: protocol@16 {
367                reg = <0x16>;
368                #reset-cells = <1>;
369            };
370
371            scmi_voltage: protocol@17 {
372                reg = <0x17>;
373                regulators {
374                    #address-cells = <1>;
375                    #size-cells = <0>;
376
377                    regulator_devX: regulator@0 {
378                        reg = <0x0>;
379                        regulator-max-microvolt = <3300000>;
380                    };
381
382                    regulator_devY: regulator@9 {
383                        reg = <0x9>;
384                        regulator-min-microvolt = <500000>;
385                        regulator-max-microvolt = <4200000>;
386                    };
387                };
388            };
389
390            scmi_powercap: protocol@18 {
391                reg = <0x18>;
392            };
393        };
394    };
395
396    soc {
397        #address-cells = <2>;
398        #size-cells = <2>;
399
400        sram@50000000 {
401            compatible = "mmio-sram";
402            reg = <0x0 0x50000000 0x0 0x10000>;
403
404            #address-cells = <1>;
405            #size-cells = <1>;
406            ranges = <0 0x0 0x50000000 0x10000>;
407
408            cpu_scp_lpri0: scp-sram-section@0 {
409                compatible = "arm,scmi-shmem";
410                reg = <0x0 0x80>;
411            };
412
413            cpu_scp_lpri1: scp-sram-section@80 {
414                compatible = "arm,scmi-shmem";
415                reg = <0x80 0x80>;
416            };
417
418            cpu_scp_hpri0: scp-sram-section@100 {
419                compatible = "arm,scmi-shmem";
420                reg = <0x100 0x80>;
421            };
422
423            cpu_scp_hpri2: scp-sram-section@180 {
424                compatible = "arm,scmi-shmem";
425                reg = <0x180 0x80>;
426            };
427        };
428    };
429
430  - |
431    firmware {
432        scmi {
433            compatible = "arm,scmi-smc";
434            shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
435            arm,smc-id = <0xc3000001>;
436
437            #address-cells = <1>;
438            #size-cells = <0>;
439
440            scmi_devpd1: protocol@11 {
441                reg = <0x11>;
442                #power-domain-cells = <1>;
443            };
444        };
445    };
446
447  - |
448    firmware {
449        scmi {
450            compatible = "linaro,scmi-optee";
451            linaro,optee-channel-id = <0>;
452
453            #address-cells = <1>;
454            #size-cells = <0>;
455
456            scmi_dvfs1: protocol@13 {
457                reg = <0x13>;
458                linaro,optee-channel-id = <1>;
459                shmem = <&cpu_optee_lpri0>;
460                #clock-cells = <1>;
461            };
462
463            scmi_clk0: protocol@14 {
464                reg = <0x14>;
465                #clock-cells = <1>;
466            };
467        };
468    };
469
470    soc {
471        #address-cells = <2>;
472        #size-cells = <2>;
473
474        sram@51000000 {
475            compatible = "mmio-sram";
476            reg = <0x0 0x51000000 0x0 0x10000>;
477
478            #address-cells = <1>;
479            #size-cells = <1>;
480            ranges = <0 0x0 0x51000000 0x10000>;
481
482            cpu_optee_lpri0: optee-sram-section@0 {
483                compatible = "arm,scmi-shmem";
484                reg = <0x0 0x80>;
485            };
486        };
487    };
488
489...
490