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
  42   interrupts:
  43     description:
  44       The interrupt that indicates message completion by the platform
  45       rather than by the return of the smc call. This should not be used
  46       except when the platform requires such behavior.
  47     maxItems: 1
  48
  49   interrupt-names:
  50     const: a2p
  51
  52   mbox-names:
  53     description:
  54       Specifies the mailboxes used to communicate with SCMI compliant
  55       firmware.
  56     items:
  57       - const: tx
  58       - const: rx
  59
  60   mboxes:
  61     description:
  62       List of phandle and mailbox channel specifiers. It should contain
  63       exactly one or two mailboxes, one for transmitting messages("tx")
  64       and another optional for receiving the notifications("rx") if supported.
  65     minItems: 1
  66     maxItems: 2
  67
  68   shmem:
  69     description:
  70       List of phandle pointing to the shared memory(SHM) area, for each
  71       transport channel specified.
  72     minItems: 1
  73     maxItems: 2
  74
  75   '#address-cells':
  76     const: 1
  77
  78   '#size-cells':
  79     const: 0
  80
  81   arm,smc-id:
  82     $ref: /schemas/types.yaml#/definitions/uint32
  83     description:
  84       SMC id required when using smc or hvc transports
  85
  86   protocol@11:
  87     type: object
  88     properties:
  89       reg:
  90         const: 0x11
  91
  92       '#power-domain-cells':
  93         const: 1
  94
  95     required:
  96       - '#power-domain-cells'
  97
  98   protocol@13:
  99     type: object
 100     properties:
 101       reg:
 102         const: 0x13
 103
 104       '#clock-cells':
 105         const: 1
 106
 107     required:
 108       - '#clock-cells'
 109
 110   protocol@14:
 111     type: object
 112     properties:
 113       reg:
 114         const: 0x14
 115
 116       '#clock-cells':
 117         const: 1
 118
 119     required:
 120       - '#clock-cells'
 121
 122   protocol@15:
 123     type: object
 124     properties:
 125       reg:
 126         const: 0x15
 127
 128       '#thermal-sensor-cells':
 129         const: 1
 130
 131     required:
 132       - '#thermal-sensor-cells'
 133
 134   protocol@16:
 135     type: object
 136     properties:
 137       reg:
 138         const: 0x16
 139
 140       '#reset-cells':
 141         const: 1
 142
 143     required:
 144       - '#reset-cells'
 145
 146   protocol@17:
 147     type: object
 148     properties:
 149       reg:
 150         const: 0x17
 151
 152       regulators:
 153         type: object
 154         description:
 155           The list of all regulators provided by this SCMI controller.
 156
 157         patternProperties:
 158           '^regulators@[0-9a-f]+$':
 159             type: object
 160             $ref: "../regulator/regulator.yaml#"
 161
 162             properties:
 163               reg:
 164                 maxItems: 1
 165                 description: Identifier for the voltage regulator.
 166
 167             required:
 168               - reg
 169
 170 additionalProperties: false
 171
 172 patternProperties:
 173   '^protocol@[0-9a-f]+$':
 174     type: object
 175     description:
 176       Each sub-node represents a protocol supported. If the platform
 177       supports a dedicated communication channel for a particular protocol,
 178       then the corresponding transport properties must be present.
 179       The virtio transport does not support a dedicated communication channel.
 180
 181     properties:
 182       reg:
 183         maxItems: 1
 184
 185       mbox-names:
 186         items:
 187           - const: tx
 188           - const: rx
 189
 190       mboxes:
 191         minItems: 1
 192         maxItems: 2
 193
 194       shmem:
 195         minItems: 1
 196         maxItems: 2
 197
 198     required:
 199       - reg
 200
 201 required:
 202   - compatible
 203
 204 if:
 205   properties:
 206     compatible:
 207       contains:
 208         const: arm,scmi
 209 then:
 210   properties:
 211     interrupts: false
 212     interrupt-names: false
 213
 214   required:
 215     - mboxes
 216     - shmem
 217
 218 else:
 219   if:
 220     properties:
 221       compatible:
 222         contains:
 223           const: arm,scmi-smc
 224   then:
 225     required:
 226       - arm,smc-id
 227       - shmem
 228
 229 examples:
 230   - |
 231     firmware {
 232         scmi {
 233             compatible = "arm,scmi";
 234             mboxes = <&mhuB 0 0>,
 235                      <&mhuB 0 1>;
 236             mbox-names = "tx", "rx";
 237             shmem = <&cpu_scp_lpri0>,
 238                     <&cpu_scp_lpri1>;
 239
 240             #address-cells = <1>;
 241             #size-cells = <0>;
 242
 243             scmi_devpd: protocol@11 {
 244                 reg = <0x11>;
 245                 #power-domain-cells = <1>;
 246             };
 247
 248             scmi_dvfs: protocol@13 {
 249                 reg = <0x13>;
 250                 #clock-cells = <1>;
 251
 252                 mboxes = <&mhuB 1 0>,
 253                          <&mhuB 1 1>;
 254                 mbox-names = "tx", "rx";
 255                 shmem = <&cpu_scp_hpri0>,
 256                         <&cpu_scp_hpri1>;
 257             };
 258
 259             scmi_clk: protocol@14 {
 260                 reg = <0x14>;
 261                 #clock-cells = <1>;
 262             };
 263
 264             scmi_sensors: protocol@15 {
 265                 reg = <0x15>;
 266                 #thermal-sensor-cells = <1>;
 267             };
 268
 269             scmi_reset: protocol@16 {
 270                 reg = <0x16>;
 271                 #reset-cells = <1>;
 272             };
 273
 274             scmi_voltage: protocol@17 {
 275                 reg = <0x17>;
 276                 regulators {
 277                     #address-cells = <1>;
 278                     #size-cells = <0>;
 279
 280                     regulator_devX: regulator@0 {
 281                         reg = <0x0>;
 282                         regulator-max-microvolt = <3300000>;
 283                     };
 284
 285                     regulator_devY: regulator@9 {
 286                         reg = <0x9>;
 287                         regulator-min-microvolt = <500000>;
 288                         regulator-max-microvolt = <4200000>;
 289                     };
 290                 };
 291             };
 292         };
 293     };
 294
 295     soc {
 296         #address-cells = <2>;
 297         #size-cells = <2>;
 298
 299         sram@50000000 {
 300             compatible = "mmio-sram";
 301             reg = <0x0 0x50000000 0x0 0x10000>;
 302
 303             #address-cells = <1>;
 304             #size-cells = <1>;
 305             ranges = <0 0x0 0x50000000 0x10000>;
 306
 307             cpu_scp_lpri0: scp-sram-section@0 {
 308                 compatible = "arm,scmi-shmem";
 309                 reg = <0x0 0x80>;
 310             };
 311
 312             cpu_scp_lpri1: scp-sram-section@80 {
 313                 compatible = "arm,scmi-shmem";
 314                 reg = <0x80 0x80>;
 315             };
 316
 317             cpu_scp_hpri0: scp-sram-section@100 {
 318                 compatible = "arm,scmi-shmem";
 319                 reg = <0x100 0x80>;
 320             };
 321
 322             cpu_scp_hpri2: scp-sram-section@180 {
 323                 compatible = "arm,scmi-shmem";
 324                 reg = <0x180 0x80>;
 325             };
 326         };
 327     };
 328
 329   - |
 330     firmware {
 331         scmi {
 332             compatible = "arm,scmi-smc";
 333             shmem = <&cpu_scp_lpri0 &cpu_scp_lpri1>;
 334             arm,smc-id = <0xc3000001>;
 335
 336             #address-cells = <1>;
 337             #size-cells = <0>;
 338
 339             scmi_devpd1: protocol@11 {
 340                 reg = <0x11>;
 341                 #power-domain-cells = <1>;
 342             };
 343
 344         };
 345     };
 346
 347 ...