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