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