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