Documentation/devicetree/bindings/opp/opp-v2-base.yaml

   1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/opp/opp-v2-base.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: Generic OPP (Operating Performance Points) Common Properties
   8
   9 maintainers:
  10   - Viresh Kumar <viresh.kumar@linaro.org>
  11
  12 description: |
  13   Devices work at voltage-current-frequency combinations and some implementations
  14   have the liberty of choosing these. These combinations are called Operating
  15   Performance Points aka OPPs. This document defines bindings for these OPPs
  16   applicable across wide range of devices. For illustration purpose, this document
  17   uses CPU as a device.
  18
  19   This describes the OPPs belonging to a device.
  20
  21 select: false
  22
  23 properties:
  24   $nodename:
  25     pattern: '^opp-table(-[a-z0-9]+)?$'
  26
  27   opp-shared:
  28     description:
  29       Indicates that device nodes using this OPP Table Node's phandle switch
  30       their DVFS state together, i.e. they share clock/voltage/current lines.
  31       Missing property means devices have independent clock/voltage/current
  32       lines, but they share OPP tables.
  33     type: boolean
  34
  35 patternProperties:
  36   '^opp(-?[0-9]+)*$':
  37     type: object
  38     description:
  39       One or more OPP nodes describing voltage-current-frequency combinations.
  40       Their name isn't significant but their phandle can be used to reference an
  41       OPP. These are mandatory except for the case where the OPP table is
  42       present only to indicate dependency between devices using the opp-shared
  43       property.
  44
  45     properties:
  46       opp-hz:
  47         description:
  48           Frequency in Hz, expressed as a 64-bit big-endian integer. This is a
  49           required property for all device nodes, unless another "required"
  50           property to uniquely identify the OPP nodes exists. Devices like power
  51           domains must have another (implementation dependent) property.
  52
  53           Entries for multiple clocks shall be provided in the same field, as
  54           array of frequencies.  The OPP binding doesn't provide any provisions
  55           to relate the values to their clocks or the order in which the clocks
  56           need to be configured and that is left for the implementation
  57           specific binding.
  58         minItems: 1
  59         maxItems: 32
  60         items:
  61           maxItems: 1
  62
  63       opp-microvolt:
  64         description: |
  65           Voltage for the OPP
  66
  67           A single regulator's voltage is specified with an array of size one or three.
  68           Single entry is for target voltage and three entries are for <target min max>
  69           voltages.
  70
  71           Entries for multiple regulators shall be provided in the same field separated
  72           by angular brackets <>. The OPP binding doesn't provide any provisions to
  73           relate the values to their power supplies or the order in which the supplies
  74           need to be configured and that is left for the implementation specific
  75           binding.
  76
  77           Entries for all regulators shall be of the same size, i.e. either all use a
  78           single value or triplets.
  79         minItems: 1
  80         maxItems: 8   # Should be enough regulators
  81         items:
  82           minItems: 1
  83           maxItems: 3
  84
  85       opp-microamp:
  86         description: |
  87           The maximum current drawn by the device in microamperes considering
  88           system specific parameters (such as transients, process, aging,
  89           maximum operating temperature range etc.) as necessary. This may be
  90           used to set the most efficient regulator operating mode.
  91
  92           Should only be set if opp-microvolt or opp-microvolt-<name> is set for
  93           the OPP.
  94
  95           Entries for multiple regulators shall be provided in the same field
  96           separated by angular brackets <>. If current values aren't required
  97           for a regulator, then it shall be filled with 0. If current values
  98           aren't required for any of the regulators, then this field is not
  99           required. The OPP binding doesn't provide any provisions to relate the
 100           values to their power supplies or the order in which the supplies need
 101           to be configured and that is left for the implementation specific
 102           binding.
 103         minItems: 1
 104         maxItems: 8   # Should be enough regulators
 105
 106       opp-microwatt:
 107         description: |
 108           The power for the OPP in micro-Watts.
 109
 110           Entries for multiple regulators shall be provided in the same field
 111           separated by angular brackets <>. If power values aren't required
 112           for a regulator, then it shall be filled with 0. If power values
 113           aren't required for any of the regulators, then this field is not
 114           required. The OPP binding doesn't provide any provisions to relate the
 115           values to their power supplies or the order in which the supplies need
 116           to be configured and that is left for the implementation specific
 117           binding.
 118         minItems: 1
 119         maxItems: 8   # Should be enough regulators
 120
 121       opp-level:
 122         description:
 123           A value representing the performance level of the device.
 124         $ref: /schemas/types.yaml#/definitions/uint32
 125
 126       opp-peak-kBps:
 127         description:
 128           Peak bandwidth in kilobytes per second, expressed as an array of
 129           32-bit big-endian integers. Each element of the array represents the
 130           peak bandwidth value of each interconnect path. The number of elements
 131           should match the number of interconnect paths.
 132         minItems: 1
 133         maxItems: 32  # Should be enough
 134
 135       opp-avg-kBps:
 136         description:
 137           Average bandwidth in kilobytes per second, expressed as an array
 138           of 32-bit big-endian integers. Each element of the array represents the
 139           average bandwidth value of each interconnect path. The number of elements
 140           should match the number of interconnect paths. This property is only
 141           meaningful in OPP tables where opp-peak-kBps is present.
 142         minItems: 1
 143         maxItems: 32  # Should be enough
 144
 145       clock-latency-ns:
 146         description:
 147           Specifies the maximum possible transition latency (in nanoseconds) for
 148           switching to this OPP from any other OPP.
 149
 150       turbo-mode:
 151         description:
 152           Marks the OPP to be used only for turbo modes. Turbo mode is available
 153           on some platforms, where the device can run over its operating
 154           frequency for a short duration of time limited by the device's power,
 155           current and thermal limits.
 156         type: boolean
 157
 158       opp-suspend:
 159         description:
 160           Marks the OPP to be used during device suspend. If multiple OPPs in
 161           the table have this, the OPP with highest opp-hz will be used.
 162         type: boolean
 163
 164       opp-supported-hw:
 165         description: |
 166           This property allows a platform to enable only a subset of the OPPs
 167           from the larger set present in the OPP table, based on the current
 168           version of the hardware (already known to the operating system).
 169
 170           Each block present in the array of blocks in this property, represents
 171           a sub-group of hardware versions supported by the OPP. i.e. <sub-group
 172           A>, <sub-group B>, etc. The OPP will be enabled if _any_ of these
 173           sub-groups match the hardware's version.
 174
 175           Each sub-group is a platform defined array representing the hierarchy
 176           of hardware versions supported by the platform. For a platform with
 177           three hierarchical levels of version (X.Y.Z), this field shall look
 178           like
 179
 180           opp-supported-hw = <X1 Y1 Z1>, <X2 Y2 Z2>, <X3 Y3 Z3>.
 181
 182           Each level (eg. X1) in version hierarchy is represented by a 32 bit
 183           value, one bit per version and so there can be maximum 32 versions per
 184           level. Logical AND (&) operation is performed for each level with the
 185           hardware's level version and a non-zero output for _all_ the levels in
 186           a sub-group means the OPP is supported by hardware. A value of
 187           0xFFFFFFFF for each level in the sub-group will enable the OPP for all
 188           versions for the hardware.
 189         $ref: /schemas/types.yaml#/definitions/uint32-matrix
 190         maxItems: 32
 191         items:
 192           minItems: 1
 193           maxItems: 4
 194
 195       required-opps:
 196         description:
 197           This contains phandle to an OPP node in another device's OPP table. It
 198           may contain an array of phandles, where each phandle points to an OPP
 199           of a different device. It should not contain multiple phandles to the
 200           OPP nodes in the same OPP table. This specifies the minimum required
 201           OPP of the device(s), whose OPP's phandle is present in this property,
 202           for the functioning of the current device at the current OPP (where
 203           this property is present).
 204         $ref: /schemas/types.yaml#/definitions/phandle-array
 205         items:
 206           maxItems: 1
 207
 208     patternProperties:
 209       '^opp-microvolt-':
 210         description:
 211           Named opp-microvolt property. This is exactly similar to the above
 212           opp-microvolt property, but allows multiple voltage ranges to be
 213           provided for the same OPP. At runtime, the platform can pick a <name>
 214           and matching opp-microvolt-<name> property will be enabled for all
 215           OPPs. If the platform doesn't pick a specific <name> or the <name>
 216           doesn't match with any opp-microvolt-<name> properties, then
 217           opp-microvolt property shall be used, if present.
 218         $ref: /schemas/types.yaml#/definitions/uint32-matrix
 219         minItems: 1
 220         maxItems: 8   # Should be enough regulators
 221         items:
 222           minItems: 1
 223           maxItems: 3
 224
 225       '^opp-microamp-':
 226         description:
 227           Named opp-microamp property. Similar to opp-microvolt-<name> property,
 228           but for microamp instead.
 229         $ref: /schemas/types.yaml#/definitions/uint32-array
 230         minItems: 1
 231         maxItems: 8   # Should be enough regulators
 232
 233       '^opp-microwatt-':
 234         description:
 235           Named opp-microwatt property. Similar to opp-microamp-<name> property,
 236           but for microwatt instead.
 237         $ref: /schemas/types.yaml#/definitions/uint32-array
 238         minItems: 1
 239         maxItems: 8   # Should be enough regulators
 240
 241     dependencies:
 242       opp-avg-kBps: [ opp-peak-kBps ]
 243
 244 required:
 245   - compatible
 246
 247 additionalProperties: true
 248
 249 ...