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 Binding 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: 16 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 current 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 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 244required: 245 - compatible 246 247additionalProperties: true 248 249... 250