|
| 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 <[email protected]> |
| 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 | +... |
0 commit comments