xref: /linux/Documentation/devicetree/bindings/firmware/arm,scmi.yaml (revision ed7171ff9fabc49ae6ed42fbd082a576473836fc) 
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 Qualcomm SMC/HVC transport
42        items:
43          - const: qcom,scmi-smc
44      - description: SCMI compliant firmware with SCMI Virtio transport.
45                     The virtio transport only supports a single device.
46        items:
47          - const: arm,scmi-virtio
48      - description: SCMI compliant firmware with OP-TEE transport
49        items:
50          - const: linaro,scmi-optee
51
52  interrupts:
53    description:
54      The interrupt that indicates message completion by the platform
55      rather than by the return of the smc call. This should not be used
56      except when the platform requires such behavior.
57    maxItems: 1
58
59  interrupt-names:
60    const: a2p
61
62  mbox-names:
63    description:
64      Specifies the mailboxes used to communicate with SCMI compliant
65      firmware.
66    oneOf:
67      - items:
68          - const: tx
69          - const: rx
70        minItems: 1
71      - items:
72          - const: tx
73          - const: tx_reply
74          - const: rx
75          - const: rx_reply
76        minItems: 2
77
78  mboxes:
79    description:
80      List of phandle and mailbox channel specifiers. It should contain
81      exactly one, two, three or four mailboxes; the first one or two for
82      transmitting messages ("tx") and another optional ("rx") for receiving
83      notifications and delayed responses, if supported by the platform.
84      The optional ("rx_reply") is for notifications completion interrupt,
85      if supported by the platform.
86      The number of mailboxes needed for transmitting messages depends on the
87      type of channels exposed by the specific underlying mailbox controller;
88      one single channel descriptor is enough if such channel is bidirectional,
89      while two channel descriptors are needed to represent the SCMI ("tx")
90      channel if the underlying mailbox channels are of unidirectional type.
91      The effective combination in numbers of mboxes and shmem descriptors let
92      the SCMI subsystem determine unambiguosly which type of SCMI channels are
93      made available by the underlying mailbox controller and how to use them.
94       1 mbox / 1 shmem => SCMI TX over 1 mailbox bidirectional channel
95       2 mbox / 2 shmem => SCMI TX and RX over 2 mailbox bidirectional channels
96       2 mbox / 1 shmem => SCMI TX over 2 mailbox unidirectional channels
97       3 mbox / 2 shmem => SCMI TX and RX over 3 mailbox unidirectional channels
98       4 mbox / 2 shmem => SCMI TX and RX over 4 mailbox unidirectional channels
99      Any other combination of mboxes and shmem is invalid.
100    minItems: 1
101    maxItems: 4
102
103  shmem:
104    description:
105      List of phandle pointing to the shared memory(SHM) area, for each
106      transport channel specified.
107    minItems: 1
108    maxItems: 2
109
110  '#address-cells':
111    const: 1
112
113  '#size-cells':
114    const: 0
115
116  atomic-threshold-us:
117    description:
118      An optional time value, expressed in microseconds, representing, on this
119      platform, the threshold above which any SCMI command, advertised to have
120      an higher-than-threshold execution latency, should not be considered for
121      atomic mode of operation, even if requested.
122    default: 0
123
124  arm,smc-id:
125    $ref: /schemas/types.yaml#/definitions/uint32
126    description:
127      SMC id required when using smc or hvc transports
128
129  linaro,optee-channel-id:
130    $ref: /schemas/types.yaml#/definitions/uint32
131    description:
132      Channel specifier required when using OP-TEE transport.
133
134  protocol@11:
135    $ref: '#/$defs/protocol-node'
136    unevaluatedProperties: false
137
138    properties:
139      reg:
140        const: 0x11
141
142      '#power-domain-cells':
143        const: 1
144
145    required:
146      - '#power-domain-cells'
147
148  protocol@13:
149    $ref: '#/$defs/protocol-node'
150    unevaluatedProperties: false
151
152    properties:
153      reg:
154        const: 0x13
155
156      '#clock-cells':
157        const: 1
158
159      '#power-domain-cells':
160        const: 1
161
162    oneOf:
163      - required:
164          - '#clock-cells'
165
166      - required:
167          - '#power-domain-cells'
168
169  protocol@14:
170    $ref: '#/$defs/protocol-node'
171    unevaluatedProperties: false
172
173    properties:
174      reg:
175        const: 0x14
176
177      '#clock-cells':
178        const: 1
179
180    required:
181      - '#clock-cells'
182
183  protocol@15:
184    $ref: '#/$defs/protocol-node'
185    unevaluatedProperties: false
186
187    properties:
188      reg:
189        const: 0x15
190
191      '#thermal-sensor-cells':
192        const: 1
193
194    required:
195      - '#thermal-sensor-cells'
196
197  protocol@16:
198    $ref: '#/$defs/protocol-node'
199    unevaluatedProperties: false
200
201    properties:
202      reg:
203        const: 0x16
204
205      '#reset-cells':
206        const: 1
207
208    required:
209      - '#reset-cells'
210
211  protocol@17:
212    $ref: '#/$defs/protocol-node'
213    unevaluatedProperties: false
214
215    properties:
216      reg:
217        const: 0x17
218
219      regulators:
220        type: object
221        additionalProperties: false
222        description:
223          The list of all regulators provided by this SCMI controller.
224
225        properties:
226          '#address-cells':
227            const: 1
228
229          '#size-cells':
230            const: 0
231
232        patternProperties:
233          '^regulator@[0-9a-f]+$':
234            type: object
235            $ref: /schemas/regulator/regulator.yaml#
236            unevaluatedProperties: false
237
238            properties:
239              reg:
240                maxItems: 1
241                description: Identifier for the voltage regulator.
242
243            required:
244              - reg
245
246  protocol@18:
247    $ref: '#/$defs/protocol-node'
248    unevaluatedProperties: false
249
250    properties:
251      reg:
252        const: 0x18
253
254  protocol@19:
255    type: object
256    allOf:
257      - $ref: '#/$defs/protocol-node'
258      - anyOf:
259          - $ref: /schemas/pinctrl/pinctrl.yaml
260          - $ref: /schemas/firmware/nxp,imx95-scmi-pinctrl.yaml
261
262    unevaluatedProperties: false
263
264    properties:
265      reg:
266        const: 0x19
267
268    patternProperties:
269      '-pins$':
270        type: object
271        allOf:
272          - $ref: /schemas/pinctrl/pincfg-node.yaml#
273          - $ref: /schemas/pinctrl/pinmux-node.yaml#
274        unevaluatedProperties: false
275
276        description:
277          A pin multiplexing sub-node describes how to configure a
278          set of pins in some desired function.
279          A single sub-node may define several pin configurations.
280          This sub-node is using the default pinctrl bindings to configure
281          pin multiplexing and using SCMI protocol to apply a specified
282          configuration.
283
284    required:
285      - reg
286
287additionalProperties: false
288
289$defs:
290  protocol-node:
291    type: object
292    description:
293      Each sub-node represents a protocol supported. If the platform
294      supports a dedicated communication channel for a particular protocol,
295      then the corresponding transport properties must be present.
296      The virtio transport does not support a dedicated communication channel.
297
298    properties:
299      reg:
300        maxItems: 1
301
302      mbox-names:
303        oneOf:
304          - items:
305              - const: tx
306              - const: rx
307            minItems: 1
308          - items:
309              - const: tx
310              - const: tx_reply
311              - const: rx
312            minItems: 2
313
314      mboxes:
315        minItems: 1
316        maxItems: 3
317
318      shmem:
319        minItems: 1
320        maxItems: 2
321
322      linaro,optee-channel-id:
323        $ref: /schemas/types.yaml#/definitions/uint32
324        description:
325          Channel specifier required when using OP-TEE transport and
326          protocol has a dedicated communication channel.
327
328    required:
329      - reg
330
331required:
332  - compatible
333
334if:
335  properties:
336    compatible:
337      contains:
338        const: arm,scmi
339then:
340  properties:
341    interrupts: false
342    interrupt-names: false
343
344  required:
345    - mboxes
346    - shmem
347
348else:
349  if:
350    properties:
351      compatible:
352        contains:
353          enum:
354            - arm,scmi-smc
355            - arm,scmi-smc-param
356            - qcom,scmi-smc
357  then:
358    required:
359      - arm,smc-id
360      - shmem
361
362  else:
363    if:
364      properties:
365        compatible:
366          contains:
367            const: linaro,scmi-optee
368    then:
369      required:
370        - linaro,optee-channel-id
371
372examples:
373  - |
374    firmware {
375        scmi {
376            compatible = "arm,scmi";
377            mboxes = <&mhuB 0 0>,
378                     <&mhuB 0 1>;
379            mbox-names = "tx", "rx";
380            shmem = <&cpu_scp_lpri0>,
381                    <&cpu_scp_lpri1>;
382
383            #address-cells = <1>;
384            #size-cells = <0>;
385
386            atomic-threshold-us = <10000>;
387
388            scmi_devpd: protocol@11 {
389                reg = <0x11>;
390                #power-domain-cells = <1>;
391            };
392
393            scmi_dvfs: protocol@13 {
394                reg = <0x13>;
395                #power-domain-cells = <1>;
396
397                mboxes = <&mhuB 1 0>,
398                         <&mhuB 1 1>;
399                mbox-names = "tx", "rx";
400                shmem = <&cpu_scp_hpri0>,
401                        <&cpu_scp_hpri1>;
402            };
403
404            scmi_clk: protocol@14 {
405                reg = <0x14>;
406                #clock-cells = <1>;
407            };
408
409            scmi_sensors: protocol@15 {
410                reg = <0x15>;
411                #thermal-sensor-cells = <1>;
412            };
413
414            scmi_reset: protocol@16 {
415                reg = <0x16>;
416                #reset-cells = <1>;
417            };
418
419            scmi_voltage: protocol@17 {
420                reg = <0x17>;
421                regulators {
422                    #address-cells = <1>;
423                    #size-cells = <0>;
424
425                    regulator_devX: regulator@0 {
426                        reg = <0x0>;
427                        regulator-max-microvolt = <3300000>;
428                    };
429
430                    regulator_devY: regulator@9 {
431                        reg = <0x9>;
432                        regulator-min-microvolt = <500000>;
433                        regulator-max-microvolt = <4200000>;
434                    };
435                };
436            };
437
438            scmi_powercap: protocol@18 {
439                reg = <0x18>;
440            };
441
442            scmi_pinctrl: protocol@19 {
443                reg = <0x19>;
444
445                i2c2-pins {
446                    groups = "g_i2c2_a", "g_i2c2_b";
447                    function = "f_i2c2";
448                };
449
450                mdio-pins {
451                    groups = "g_avb_mdio";
452                    drive-strength = <24>;
453                };
454
455                keys_pins: keys-pins {
456                    pins = "gpio_5_17", "gpio_5_20", "gpio_5_22", "gpio_2_1";
457                    bias-pull-up;
458                };
459            };
460        };
461    };
462
463    soc {
464        #address-cells = <2>;
465        #size-cells = <2>;
466
467        sram@50000000 {
468            compatible = "mmio-sram";
469            reg = <0x0 0x50000000 0x0 0x10000>;
470
471            #address-cells = <1>;
472            #size-cells = <1>;
473            ranges = <0 0x0 0x50000000 0x10000>;
474
475            cpu_scp_lpri0: scp-sram-section@0 {
476                compatible = "arm,scmi-shmem";
477                reg = <0x0 0x80>;
478            };
479
480            cpu_scp_lpri1: scp-sram-section@80 {
481                compatible = "arm,scmi-shmem";
482                reg = <0x80 0x80>;
483            };
484
485            cpu_scp_hpri0: scp-sram-section@100 {
486                compatible = "arm,scmi-shmem";
487                reg = <0x100 0x80>;
488            };
489
490            cpu_scp_hpri2: scp-sram-section@180 {
491                compatible = "arm,scmi-shmem";
492                reg = <0x180 0x80>;
493            };
494        };
495    };
496
497  - |
498    firmware {
499        scmi {
500            compatible = "arm,scmi-smc";
501            shmem = <&cpu_scp_lpri0>, <&cpu_scp_lpri1>;
502            arm,smc-id = <0xc3000001>;
503
504            #address-cells = <1>;
505            #size-cells = <0>;
506
507            scmi_devpd1: protocol@11 {
508                reg = <0x11>;
509                #power-domain-cells = <1>;
510            };
511        };
512    };
513
514  - |
515    firmware {
516        scmi {
517            compatible = "linaro,scmi-optee";
518            linaro,optee-channel-id = <0>;
519
520            #address-cells = <1>;
521            #size-cells = <0>;
522
523            scmi_dvfs1: protocol@13 {
524                reg = <0x13>;
525                linaro,optee-channel-id = <1>;
526                shmem = <&cpu_optee_lpri0>;
527                #power-domain-cells = <1>;
528            };
529
530            scmi_clk0: protocol@14 {
531                reg = <0x14>;
532                #clock-cells = <1>;
533            };
534        };
535    };
536
537    soc {
538        #address-cells = <2>;
539        #size-cells = <2>;
540
541        sram@51000000 {
542            compatible = "mmio-sram";
543            reg = <0x0 0x51000000 0x0 0x10000>;
544
545            #address-cells = <1>;
546            #size-cells = <1>;
547            ranges = <0 0x0 0x51000000 0x10000>;
548
549            cpu_optee_lpri0: optee-sram-section@0 {
550                compatible = "arm,scmi-shmem";
551                reg = <0x0 0x80>;
552            };
553        };
554    };
555
556...
557