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