Documentation/devicetree/bindings/firmware/arm,scmi.yaml

   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
   8 title: System Control and Management Interface (SCMI) Message Protocol bindings
   9
  10 maintainers:
  11   - Sudeep Holla <sudeep.holla@arm.com>
  12
  13 description: |
  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
  25 properties:
  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 SCMI Virtio transport.
  38                      The virtio transport only supports a single device.
  39         items:
  40           - const: arm,scmi-virtio
  41       - description: SCMI compliant firmware with OP-TEE transport
  42         items:
  43           - const: linaro,scmi-optee
  44
  45   interrupts:
  46     description:
  47       The interrupt that indicates message completion by the platform
  48       rather than by the return of the smc call. This should not be used
  49       except when the platform requires such behavior.
  50     maxItems: 1
  51
  52   interrupt-names:
  53     const: a2p
  54
  55   mbox-names:
  56     description:
  57       Specifies the mailboxes used to communicate with SCMI compliant
  58       firmware.
  59     items:
  60       - const: tx
  61       - const: rx
  62
  63   mboxes:
  64     description:
  65       List of phandle and mailbox channel specifiers. It should contain
  66       exactly one or two mailboxes, one for transmitting messages("tx")
  67       and another optional for receiving the notifications("rx") if supported.
  68     minItems: 1
  69     maxItems: 2
  70
  71   shmem:
  72     description:
  73       List of phandle pointing to the shared memory(SHM) area, for each
  74       transport channel specified.
  75     minItems: 1
  76     maxItems: 2
  77
  78   '#address-cells':
  79     const: 1
  80
  81   '#size-cells':
  82     const: 0
  83
  84   atomic-threshold-us:
  85     description:
  86       An optional time value, expressed in microseconds, representing, on this
  87       platform, the threshold above which any SCMI command, advertised to have
  88       an higher-than-threshold execution latency, should not be considered for
  89       atomic mode of operation, even if requested.
  90     default: 0
  91
  92   arm,smc-id:
  93     $ref: /schemas/types.yaml#/definitions/uint32
  94     description:
  95       SMC id required when using smc or hvc transports
  96
  97   linaro,optee-channel-id:
  98     $ref: /schemas/types.yaml#/definitions/uint32
  99     description:
 100       Channel specifier required when using OP-TEE transport.
 101
 102   protocol@11:
 103     type: object
 104     properties:
 105       reg:
 106         const: 0x11
 107
 108       '#power-domain-cells':
 109         const: 1
 110
 111     required:
 112       - '#power-domain-cells'
 113
 114   protocol@13:
 115     type: object
 116     properties:
 117       reg:
 118         const: 0x13
 119
 120       '#clock-cells':
 121         const: 1
 122
 123     required:
 124       - '#clock-cells'
 125
 126   protocol@14:
 127     type: object
 128     properties:
 129       reg:
 130         const: 0x14
 131
 132       '#clock-cells':
 133         const: 1
 134
 135     required:
 136       - '#clock-cells'
 137
 138   protocol@15:
 139     type: object
 140     properties:
 141       reg:
 142         const: 0x15
 143
 144       '#thermal-sensor-cells':
 145         const: 1
 146
 147     required:
 148       - '#thermal-sensor-cells'
 149
 150   protocol@16:
 151     type: object
 152     properties:
 153       reg:
 154         const: 0x16
 155
 156       '#reset-cells':
 157         const: 1
 158
 159     required:
 160       - '#reset-cells'
 161
 162   protocol@17:
 163     type: object
 164     properties:
 165       reg:
 166         const: 0x17
 167
 168       regulators:
 169         type: object
 170         description:
 171           The list of all regulators provided by this SCMI controller.
 172
 173         patternProperties:
 174           '^regulators@[0-9a-f]+$':
 175             type: object
 176             $ref: "../regulator/regulator.yaml#"
 177
 178             properties:
 179               reg:
 180                 maxItems: 1
 181                 description: Identifier for the voltage regulator.
 182
 183             required:
 184               - reg
 185
 186 additionalProperties: false
 187
 188 patternProperties:
 189   '^protocol@[0-9a-f]+$':
 190     type: object
 191     description:
 192       Each sub-node represents a protocol supported. If the platform
 193       supports a dedicated communication channel for a particular protocol,
 194       then the corresponding transport properties must be present.
 195       The virtio transport does not support a dedicated communication channel.
 196
 197     properties:
 198       reg:
 199         maxItems: 1
 200
 201       mbox-names:
 202         items:
 203           - const: tx
 204           - const: rx
 205
 206       mboxes:
 207         minItems: 1
 208         maxItems: 2
 209
 210       shmem:
 211         minItems: 1
 212         maxItems: 2
 213
 214       linaro,optee-channel-id:
 215         $ref: /schemas/types.yaml#/definitions/uint32
 216         description:
 217           Channel specifier required when using OP-TEE transport and
 218           protocol has a dedicated communication channel.
 219
 220     required:
 221       - reg
 222
 223 required:
 224   - compatible
 225
 226 if:
 227   properties:
 228     compatible:
 229       contains:
 230         const: arm,scmi
 231 then:
 232   properties:
 233     interrupts: false
 234     interrupt-names: false
 235
 236   required:
 237     - mboxes
 238     - shmem
 239
 240 else:
 241   if:
 242     properties:
 243       compatible:
 244         contains:
 245           const: arm,scmi-smc
 246   then:
 247     required:
 248       - arm,smc-id
 249       - shmem
 250
 251   else:
 252     if:
 253       properties:
 254         compatible:
 255           contains:
 256             const: linaro,scmi-optee
 257     then:
 258       required:
 259         - linaro,optee-channel-id
 260
 261 examples:
 262   - |
 263     firmware {
 264         scmi {
 265             compatible = "arm,scmi";
 266             mboxes = <&mhuB 0 0>,
 267                      <&mhuB 0 1>;
 268             mbox-names = "tx", "rx";
 269             shmem = <&cpu_scp_lpri0>,
 270                     <&cpu_scp_lpri1>;
 271
 272             #address-cells = <1>;
 273             #size-cells = <0>;
 274
 275             atomic-threshold-us = <10000>;
 276
 277             scmi_devpd: protocol@11 {
 278                 reg = <0x11>;
 279                 #power-domain-cells = <1>;
 280             };
 281
 282             scmi_dvfs: protocol@13 {
 283                 reg = <0x13>;
 284                 #clock-cells = <1>;
 285
 286                 mboxes = <&mhuB 1 0>,
 287                          <&mhuB 1 1>;
 288                 mbox-names = "tx", "rx";
 289                 shmem = <&cpu_scp_hpri0>,
 290                         <&cpu_scp_hpri1>;
 291             };
 292
 293             scmi_clk: protocol@14 {
 294                 reg = <0x14>;
 295                 #clock-cells = <1>;
 296             };
 297
 298             scmi_sensors: protocol@15 {
 299                 reg = <0x15>;
 300                 #thermal-sensor-cells = <1>;
 301             };
 302
 303             scmi_reset: protocol@16 {
 304                 reg = <0x16>;
 305                 #reset-cells = <1>;
 306             };
 307
 308             scmi_voltage: protocol@17 {
 309                 reg = <0x17>;
 310                 regulators {
 311                     #address-cells = <1>;
 312                     #size-cells = <0>;
 313
 314                     regulator_devX: regulator@0 {
 315                         reg = <0x0>;
 316                         regulator-max-microvolt = <3300000>;
 317                     };
 318
 319                     regulator_devY: regulator@9 {
 320                         reg = <0x9>;
 321                         regulator-min-microvolt = <500000>;
 322                         regulator-max-microvolt = <4200000>;
 323                     };
 324                 };
 325             };
 326         };
 327     };
 328
 329     soc {
 330         #address-cells = <2>;
 331         #size-cells = <2>;
 332
 333         sram@50000000 {
 334             compatible = "mmio-sram";
 335             reg = <0x0 0x50000000 0x0 0x10000>;
 336
 337             #address-cells = <1>;
 338             #size-cells = <1>;
 339             ranges = <0 0x0 0x50000000 0x10000>;
 340
 341             cpu_scp_lpri0: scp-sram-section@0 {
 342                 compatible = "arm,scmi-shmem";
 343                 reg = <0x0 0x80>;
 344             };
 345
 346             cpu_scp_lpri1: scp-sram-section@80 {
 347                 compatible = "arm,scmi-shmem";
 348                 reg = <0x80 0x80>;
 349             };
 350
 351             cpu_scp_hpri0: scp-sram-section@100 {
 352                 compatible = "arm,scmi-shmem";
 353                 reg = <0x100 0x80>;
 354             };
 355
 356             cpu_scp_hpri2: scp-sram-section@180 {
 357                 compatible = "arm,scmi-shmem";
 358                 reg = <0x180 0x80>;
 359             };
 360         };
 361     };
 362
 363   - |
 364     firmware {
 365         scmi {
 366             compatible = "arm,scmi-smc";
 367             shmem = <&cpu_scp_lpri0 &cpu_scp_lpri1>;
 368             arm,smc-id = <0xc3000001>;
 369
 370             #address-cells = <1>;
 371             #size-cells = <0>;
 372
 373             scmi_devpd1: protocol@11 {
 374                 reg = <0x11>;
 375                 #power-domain-cells = <1>;
 376             };
 377         };
 378     };
 379
 380   - |
 381     firmware {
 382         scmi {
 383             compatible = "linaro,scmi-optee";
 384             linaro,optee-channel-id = <0>;
 385
 386             #address-cells = <1>;
 387             #size-cells = <0>;
 388
 389             scmi_dvfs1: protocol@13 {
 390                 reg = <0x13>;
 391                 linaro,optee-channel-id = <1>;
 392                 shmem = <&cpu_optee_lpri0>;
 393                 #clock-cells = <1>;
 394             };
 395
 396             scmi_clk0: protocol@14 {
 397                 reg = <0x14>;
 398                 #clock-cells = <1>;
 399             };
 400         };
 401     };
 402
 403     soc {
 404         #address-cells = <2>;
 405         #size-cells = <2>;
 406
 407         sram@51000000 {
 408             compatible = "mmio-sram";
 409             reg = <0x0 0x51000000 0x0 0x10000>;
 410
 411             #address-cells = <1>;
 412             #size-cells = <1>;
 413             ranges = <0 0x0 0x51000000 0x10000>;
 414
 415             cpu_optee_lpri0: optee-sram-section@0 {
 416                 compatible = "arm,scmi-shmem";
 417                 reg = <0x0 0x80>;
 418             };
 419         };
 420     };
 421
 422 ...