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 Binding
   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       opp-microvolt:
  54         description: |
  55           Voltage for the OPP
  56
  57           A single regulator's voltage is specified with an array of size one or three.
  58           Single entry is for target voltage and three entries are for <target min max>
  59           voltages.
  60
  61           Entries for multiple regulators shall be provided in the same field separated
  62           by angular brackets <>. The OPP binding doesn't provide any provisions to
  63           relate the values to their power supplies or the order in which the supplies
  64           need to be configured and that is left for the implementation specific
  65           binding.
  66
  67           Entries for all regulators shall be of the same size, i.e. either all use a
  68           single value or triplets.
  69         minItems: 1
  70         maxItems: 8   # Should be enough regulators
  71         items:
  72           minItems: 1
  73           maxItems: 3
  74
  75       opp-microamp:
  76         description: |
  77           The maximum current drawn by the device in microamperes considering
  78           system specific parameters (such as transients, process, aging,
  79           maximum operating temperature range etc.) as necessary. This may be
  80           used to set the most efficient regulator operating mode.
  81
  82           Should only be set if opp-microvolt or opp-microvolt-<name> is set for
  83           the OPP.
  84
  85           Entries for multiple regulators shall be provided in the same field
  86           separated by angular brackets <>. If current values aren't required
  87           for a regulator, then it shall be filled with 0. If current values
  88           aren't required for any of the regulators, then this field is not
  89           required. The OPP binding doesn't provide any provisions to relate the
  90           values to their power supplies or the order in which the supplies need
  91           to be configured and that is left for the implementation specific
  92           binding.
  93         minItems: 1
  94         maxItems: 8   # Should be enough regulators
  95
  96       opp-level:
  97         description:
  98           A value representing the performance level of the device.
  99         $ref: /schemas/types.yaml#/definitions/uint32
 100
 101       opp-peak-kBps:
 102         description:
 103           Peak bandwidth in kilobytes per second, expressed as an array of
 104           32-bit big-endian integers. Each element of the array represents the
 105           peak bandwidth value of each interconnect path. The number of elements
 106           should match the number of interconnect paths.
 107         minItems: 1
 108         maxItems: 32  # Should be enough
 109
 110       opp-avg-kBps:
 111         description:
 112           Average bandwidth in kilobytes per second, expressed as an array
 113           of 32-bit big-endian integers. Each element of the array represents the
 114           average bandwidth value of each interconnect path. The number of elements
 115           should match the number of interconnect paths. This property is only
 116           meaningful in OPP tables where opp-peak-kBps is present.
 117         minItems: 1
 118         maxItems: 32  # Should be enough
 119
 120       clock-latency-ns:
 121         description:
 122           Specifies the maximum possible transition latency (in nanoseconds) for
 123           switching to this OPP from any other OPP.
 124
 125       turbo-mode:
 126         description:
 127           Marks the OPP to be used only for turbo modes. Turbo mode is available
 128           on some platforms, where the device can run over its operating
 129           frequency for a short duration of time limited by the device's power,
 130           current and thermal limits.
 131         type: boolean
 132
 133       opp-suspend:
 134         description:
 135           Marks the OPP to be used during device suspend. If multiple OPPs in
 136           the table have this, the OPP with highest opp-hz will be used.
 137         type: boolean
 138
 139       opp-supported-hw:
 140         description: |
 141           This property allows a platform to enable only a subset of the OPPs
 142           from the larger set present in the OPP table, based on the current
 143           version of the hardware (already known to the operating system).
 144
 145           Each block present in the array of blocks in this property, represents
 146           a sub-group of hardware versions supported by the OPP. i.e. <sub-group
 147           A>, <sub-group B>, etc. The OPP will be enabled if _any_ of these
 148           sub-groups match the hardware's version.
 149
 150           Each sub-group is a platform defined array representing the hierarchy
 151           of hardware versions supported by the platform. For a platform with
 152           three hierarchical levels of version (X.Y.Z), this field shall look
 153           like
 154
 155           opp-supported-hw = <X1 Y1 Z1>, <X2 Y2 Z2>, <X3 Y3 Z3>.
 156
 157           Each level (eg. X1) in version hierarchy is represented by a 32 bit
 158           value, one bit per version and so there can be maximum 32 versions per
 159           level. Logical AND (&) operation is performed for each level with the
 160           hardware's level version and a non-zero output for _all_ the levels in
 161           a sub-group means the OPP is supported by hardware. A value of
 162           0xFFFFFFFF for each level in the sub-group will enable the OPP for all
 163           versions for the hardware.
 164         $ref: /schemas/types.yaml#/definitions/uint32-matrix
 165         maxItems: 32
 166         items:
 167           minItems: 1
 168           maxItems: 4
 169
 170       required-opps:
 171         description:
 172           This contains phandle to an OPP node in another device's OPP table. It
 173           may contain an array of phandles, where each phandle points to an OPP
 174           of a different device. It should not contain multiple phandles to the
 175           OPP nodes in the same OPP table. This specifies the minimum required
 176           OPP of the device(s), whose OPP's phandle is present in this property,
 177           for the functioning of the current device at the current OPP (where
 178           this property is present).
 179         $ref: /schemas/types.yaml#/definitions/phandle-array
 180
 181     patternProperties:
 182       '^opp-microvolt-':
 183         description:
 184           Named opp-microvolt property. This is exactly similar to the above
 185           opp-microvolt property, but allows multiple voltage ranges to be
 186           provided for the same OPP. At runtime, the platform can pick a <name>
 187           and matching opp-microvolt-<name> property will be enabled for all
 188           OPPs. If the platform doesn't pick a specific <name> or the <name>
 189           doesn't match with any opp-microvolt-<name> properties, then
 190           opp-microvolt property shall be used, if present.
 191         $ref: /schemas/types.yaml#/definitions/uint32-matrix
 192         minItems: 1
 193         maxItems: 8   # Should be enough regulators
 194         items:
 195           minItems: 1
 196           maxItems: 3
 197
 198       '^opp-microamp-':
 199         description:
 200           Named opp-microamp property. Similar to opp-microvolt-<name> property,
 201           but for microamp instead.
 202         $ref: /schemas/types.yaml#/definitions/uint32-array
 203         minItems: 1
 204         maxItems: 8   # Should be enough regulators
 205
 206     dependencies:
 207       opp-avg-kBps: [ opp-peak-kBps ]
 208
 209 required:
 210   - compatible
 211
 212 additionalProperties: true
 213
 214 ...