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