Qualcomm Technologies, Inc. CPR3 Regulator - Platform Independent Bindings Core Power Reduction (CPR) version 3 controllers are used by some Qualcomm Technologies, Inc. (QTI) SoCs to manage important voltage regulators. CPR3 controllers are capable of monitoring several ring oscillator sensing loops simultaneously. The CPR3 controller informs software when the silicon conditions require the supply voltage to be increased or decreased. On certain supply rails, the CPR3 controller is able to propagate the voltage increase or decrease requests all the way to the PMIC without software involvement. This document describes the common platform independent bindings that apply to all CPR3 controllers. ======================= Required Node Structure ======================= CPR3 regulators must be described in three levels of devices nodes. The first level describes the CPR3 controller. The second level describes one or more hardware threads managed by the controller. The third level describes one or more logical regulators handled by each CPR thread. ==================================== First Level Nodes - CPR3 Controllers ==================================== Platform independent properties: - compatible Usage: required Value type: Definition: The value to use for this property is defined in the platform specific cpr3-regulator binding documentation files. - reg Usage: required Value type: Definition: Addresses and sizes for the memory of the CPR3 controller, the first fuse row, and optionally a register used to check if aging measurements are possible. - reg-names Usage: required Value type: Definition: Address names. Must include "cpr_ctrl" and "fuse_base". "aging_allowed" may also be specified. "cpr_tcsr_reg" is optional which will be used for reading CPR settings from TCSR register. The strings must be specified in the same order as the corresponding addresses are specified in the reg property. - qcom,cpr-ctrl-name Usage: required Value type: Definition: Name for this CPR controller - vdd-supply Usage: required Value type: Definition: phandle of the underlying regulator device that is managed by this CPR controller. - system-supply Usage: optional Value type: Definition: phandle of the system-level regulator device which the vdd-supply depends upon. Requests for this regulator must be made before increasing the vdd-supply voltage and after decreasing the vdd-supply voltage. - mem-acc-supply Usage: optional Value type: Definition: phandle of the mem-acc regulator device which is used to configure memory array circuitry settings based upon the performance operating point. Requests for this regulator must be made before decreasing the vdd-supply voltage and after increasing the vdd-supply voltage. - clocks Usage: optional Value type: Definition: Array of clock tuples in which each tuple consists of a phandle to a clock device and a clock ID number. The CPR3 core clock must be specified for some targets. See platform specific cpr3-regulator binding documentation for additional clocks that may also need to be specified. - clock-names Usage: optional Value type: Definition: Clock names. This list must match up 1-to-1 with the clocks specified in the 'clocks' property. "core_clk" must be specified for some platforms. Other clocks may be required for some platforms. - interrupts Usage: required Value type: Definition: CPR interrupt specifier and optionally a hardware closed-loop ceiling interrupt specifier. - interrupt-names Usage: required Value type: Definition: Interrupt names. This list must match up 1-to-1 with the interrupts specified in the 'interrupts' property. "cpr" must be specified. "ceiling" may be specified for some platforms. - qcom,cpr-interrupt-affinity Usage: optional Value type: Definition: A list of CPU phandles which correspond to the cores that the "cpr" interrupt should have affinity for. - qcom,cpr-sensor-time Usage: required Value type: Definition: The time in nanoseconds that each CPR sensor within the sensing loop takes to perform a measurement. - qcom,cpr-loop-time Usage: required Value type: Definition: The time in nanoseconds between consecutive CPR measurements. - qcom,cpr-idle-cycles Usage: required Value type: Definition: The number of CPR core clock cycles for the CPR controller to wait in transitional states. Supported values: 0 - 31. - qcom,voltage-step Usage: required Value type: Definition: The voltage in microvolts of a single step of the VDD supply regulator being controlled by CPR. - qcom,cpr-step-quot-init-min Usage: required Value type: Definition: The default minimum CPR step quotient value. The step quotient is the number of additional ring oscillator ticks observed for each qcom,voltage-step increase in vdd-supply output voltage. Supported values: 0 - 63. - qcom,cpr-step-quot-init-max Usage: required Value type: Definition: The default maximum CPR step quotient value. Supported values: 0 - 63. - qcom,cpr-count-mode Usage: required Value type: Definition: The CPR counting mode to use during CPR measurements. Supported values: 0 - Read all sensors at once and use the minimum quotient value observed in repeated measurements. 1 - Read all sensors at once and use the maximum quotient value observed in repeated measurements. 2 - Read each sensor once in a sequential, staggered fashion. - qcom,cpr-count-repeat Usage: optional Value type: Definition: The number of times to read CPR sensors during a single CPR measurement when using one of the all-at-once count modes. - qcom,cpr-enable Usage: optional Value type: Definition: Boolean flag which indicates that the CPR3 controller should operate in closed-loop mode (i.e. CPR sensing loop enabled) as opposed to open-loop mode (i.e. CPR sensing loop disabled) by default. - qcom,cpr-aging-ref-voltage Usage: required if qcom,allow-aging-voltage-adjustment is specified for any third level nodes Value type: Definition: Specifies the CPR aging reference voltage in microvolts. This is the voltage that vdd-supply must be set to when performing an aging measurement. - qcom,cpr-aging-allowed-reg-mask Usage: required if "aging_allowed" register is specified Value type: Definition: Bitmask used to mask off the "aging_allowed" register. - qcom,cpr-aging-allowed-reg-value Usage: required if "aging_allowed" register is specified Value type: Definition: Value required in the masked off "aging_allowed" register bits in order for a CPR aging measurement to be possible. - qcom,cpr-panic-reg-addr-list Usage: optional Value type: Definition: Array of register addresses to be dumped when device resets. - qcom,cpr-panic-reg-name-list Usage: optional, though only meaningful if qcom,cpr-panic-reg-addr-list is specified Value type: Definition: Address names. Must be specified in the same order as the corresponding addresses are specified in the qcom,cpr-panic-reg-addr-list property. ================================================= Second Level Nodes - CPR Threads for a Controller ================================================= Platform independent properties: - qcom,cpr-thread-id Usage: required Value type: Definition: Specifies the hardware thread ID of this thread within the CPR controller. - qcom,cpr-consecutive-up Usage: required Value type: Definition: The number of consecutive CPR step up events needed to to trigger an up interrupt. Supported values: 0 - 15. - qcom,cpr-consecutive-down Usage: required Value type: Definition: The number of consecutive CPR step down events needed to to trigger a down interrupt. Supported values: 0 - 15. - qcom,cpr-up-threshold Usage: required Value type: Definition: The number CPR error steps required to generate an up event. Supported values: 0 - 31. - qcom,cpr-down-threshold Usage: required Value type: Definition: The number CPR error steps required to generate a down event. Supported values: 0 - 31. =============================================== Third Level Nodes - CPR Regulators for a Thread =============================================== Platform independent properties: - regulator-name Usage: required Value type: Definition: Specifies the name for this CPR3 regulator. - regulator-min-microvolt Usage: required Value type: Definition: Minimum corner value which should be 1 to represent the lowest supported corner. - regulator-max-microvolt Usage: required Value type: Definition: Maximum corner value which should be equal to largest value listed in qcom,cpr-corners. - qcom,cpr-fuse-corners Usage: required Value type: Definition: Specifies the number of fuse corners. See platform specific binding files for further requirements. - qcom,cpr-fuse-combos Usage: required Value type: Definition: Specifies the number of fuse combinations being supported by the device. This value is utilized by several other properties. Supported values are 1 up to the maximum possible for a given regulator type. See platform specific binding files for further details. - qcom,cpr-part-types Usage: optional Value type: Definition: Specifies the number of part types supported for which correction voltages are different. This will be used by qcom,cpr-parts-voltage property. Supported values are 1 up to the maximum number of part types - qcom,cpr-parts-voltage Usage: required if qcom,cpr-part-types is specified Value type: Definition: A list of integers which defines voltage in increasing order. It will be used to determine the part type by comparing the voltage in this array with part fused open loop voltage. - qcom,cpr-speed-bins Usage: optional Value type: Definition: Specifies the number of speed bins being supported by the device. This value is utilized by several other properties. Supported values are 1 up to the maximum possible for a given regulator type. See platform specific binding files for further details. This property can only be utilized if the number of corners for all fuse combinations associated with a given speed bin is the same. - qcom,cpr-corners Usage: required Value type: Definition: A list of integers which defines how many voltage corners are to be used for each fuse combination. The list must contain either qcom,cpr-fuse-combos number of elements in which case the corner counts are applied to fuse combinations 1-to-1 or the list must contain exactly 1 element which is used regardless of the fuse combination found on a given chip. - qcom,cpr-speed-bin-corners Usage: required if qcom,cpr-speed-bins is specified Value type: Definition: A list of integers which defines how many voltage corners are to be used for each speed bin. The list must contain qcom,cpr-speed-bins number of elements. - qcom,cpr-corner-fmax-map Usage: required Value type: Definition: A list of integer tuples which each define the highest (i.e. maximum frequency) 1-based corner value associated with each fuse-corner. Each tuple must have a number of elements equal to the value of the qcom,cpr-fuse-corners property. The elements of a tuple are ordered from lowest to highest fuse corner. The list must contain qcom,cpr-fuse-combos number of tuples in which case the tuples are matched to fuse combinations 1-to-1 or qcom,cpr-speed-bins number of tuples in which case the tuples are matched to speed bins 1-to-1 or exactly 1 tuple which is used regardless of the fuse combination and speed bin found on a given chip. - qcom,cpr-voltage-ceiling Usage: required Value type: Definition: A list of integer tuples which each define the CPR ceiling voltage in microvolts for each voltage corner in order from lowest to highest. The list must contain qcom,cpr-fuse-combos number of tuples in which case the tuples are matched to fuse combinations 1-to-1 or qcom,cpr-speed-bins number of tuples in which case the tuples are matched to speed bins 1-to-1 or exactly 1 tuple which is used regardless of the fuse combination and speed bin found on a given chip. Each tuple must be of the length defined in the corresponding element of the qcom,cpr-corners property or the qcom,cpr-speed-bins property. A single tuple may only be specified if all of the corner counts in qcom,cpr-corners are the same. - qcom,cpr-voltage-floor Usage: required Value type: Definition: A list of integer tuples which each define the CPR floor voltage in microvolts for each voltage corner in order from lowest to highest. The list and tuples must meet the same size requirements as those specified for qcom,cpr-voltage-ceiling above. - qcom,cpr-floor-to-ceiling-max-range Usage: optional Value type: Definition: A list of integer tuples which each define the maximum allowed difference between the final floor voltage and the final ceiling voltage in microvolts for each voltage corner in order from lowest to highest. A negative value may be specified for an element to indicate that there is no limitation of the floor to ceiling voltage range for the corresponding corner. In the case that the initial floor to ceiling voltage is greater than the max range specified, the floor voltage will be increased in order to satisfy the max range constraint. The list and tuples must meet the same size requirements as those specified for qcom,cpr-voltage-ceiling above. - qcom,system-voltage Usage: optional Value type: Definition: A list of integer tuples which each define the system-supply voltage in microvolts or corners or levels for each voltage corner in order from lowest to highest. The list and tuples must meet the same size requirements as those specified for qcom,cpr-voltage-ceiling above. - qcom,corner-frequencies Usage: required Value type: Definition: A list of integer tuples which each define the CPU frequency in Hertz corresponding to each voltage corner in order from lowest to highest. The list and tuples must meet the same size requirements as those specified for qcom,cpr-voltage-ceiling above. - qcom,allow-voltage-interpolation Usage: optional Value type: Definition: Boolean flag which indicates that it is acceptable to use interpolated open-loop voltage values. These values are interpolated between the open-loop voltage Fmax fuse values. - qcom,cpr-scaled-open-loop-voltage-as-ceiling Usage: optional Value type: Definition: Boolean flag which indicates that it is acceptable to use the interpolated open-loop voltage for each corner as the CPR ceiling voltage for each corner. - qcom,cpr-open-loop-voltage-fuse-adjustment Usage: optional Value type: Definition: A list of integer tuples which each define the open-loop voltage adjustment in microvolts for each fused voltage corner in order from lowest to highest. This adjustment is applied to the values read from fuses before the values are used in interpolation for intermediate corners. The list and tuples must meet the same size requirements as those specified for qcom,cpr-corner-fmax-map above. The open-loop voltage for a given fuse corner corresponds to the voltage that is safe to use under all circumstances. It is used as a starting voltage for CPR and may also be specified as a ceiling voltage for CPR scaling. - qcom,cpr-open-loop-voltage-adjustment Usage: optional Value type: Definition: A list of integer tuples which each define the open-loop voltage adjustment in microvolts for each voltage corner in order from lowest to highest. This adjustment is applied to the open-loop voltage values after they have been interpolated for intermediate corners. The list and tuples must meet the same size requirements as those specified for qcom,cpr-voltage-ceiling above. - qcom,cpr-open-loop-voltage-min-diff Usage: optional; only meaningful if the qcom,cpr-open-loop-voltage-adjustment property is specified Value type: Definition: A list of integer tuples which each define the minimum allowed open-loop voltage difference in microvolts between each voltage corner and the one immediately preceding it. The elements in a tuple are ordered from the lowest to the highest corner. The value specified for the first corner is ignored since there is no corner before it. Negative voltage values may be specified for this property. A negative value means that the open-loop voltage of a corner may be lower than that of the preceding corner. The minimum difference is enforced after the open-loop voltage values have been interpolated for intermediate corners and after adjustments have been applied. The list and tuples must meet the same size requirements as those specified for qcom,cpr-voltage-ceiling above. If this property is not specified, then the minimum difference is assumed to be 0 uV for all corners. - qcom,cpr-closed-loop-voltage-fuse-adjustment Usage: optional Value type: Definition: A list of integer tuples which each define the closed-loop voltage adjustment in microvolts for each fused voltage corner in order from lowest to highest. This adjustment is applied to the values read from fuses before the values are used in interpolation for intermediate corners. The list and tuples must meet the same size requirements as those specified for qcom,cpr-corner-fmax-map above. The qcom,cpr-ro-scaling-factor property must be specified in order to utilize this property. The closed-loop voltage for a given fuse corner corresponds to the voltage that the CPR controller settles the VDD supply rail to based upon the programmed CPR target quotients and the current silicon conditions. - qcom,cpr-closed-loop-voltage-adjustment Usage: optional Value type: Definition: A list of integer tuples which each define the closed-loop voltage adjustment in microvolts for each voltage corner in order from lowest to highest. This adjustment is applied to target quotient values after they have been interpolated for intermediate corners. The list and tuples must meet the same size requirements as those specified for qcom,cpr-voltage-ceiling above. The qcom,cpr-ro-scaling-factor property must be specified in order to utilize this property. - qcom,cpr-ro-scaling-factor Usage: required if qcom,cpr-closed-loop-voltage-fuse-adjustment, qcom,cpr-closed-loop-voltage-adjustment, or qcom,allow-aging-voltage-adjustment is specified Value type: Definition: A grouping of integer tuple lists. Each tuple defines the CPR ring oscillator (RO) scaling factor with units of QUOT/V for each RO for a given fuse corner. Since CPR3 supports exactly 16 ROs, each tuple must contain 16 elements corresponding to RO0 through RO15 in order. If a given RO is unused for a fuse corner, then its scaling factor may be specified as 0. Each tuple list must contain the number of tuples defined in the qcom,cpr-fuse-corners property. The tuples in a given list are ordered from the lowest fuse corner to the highest fuse corner. The tuple list grouping must contain qcom,cpr-fuse-combos number of tuple lists in which case the lists are matched to fuse combinations 1-to-1 or qcom,cpr-speed-bins number of tuple lists in which case the lists are matched to speed bins 1-to-1 or exactly 1 list which is used regardless of the fuse combination and speed bin found on a given chip. The target quotient adjustment to apply for each RO of a given corner is determined by multiplying the adjustment value in qcom,cpr-closed-loop-voltage-fuse-adjustment or qcom,cpr-closed-loop-voltage-adjustment by the relevant RO scaling factor in this property. - qcom,allow-aging-voltage-adjustment Usage: optional Value type: Definition: A list of integers which specifies if CPR aging adjustment should be performed for each fuse combination. Supported per-combo element values: 0 - do not perform CPR aging adjustment 1 - perform CPR aging adjustment The list must contain qcom,cpr-fuse-combos number of elements in which case the elements are matched to fuse combinations 1-to-1 or qcom,cpr-speed-bins number of elements in which case the elements are matched to speed bins 1-to-1 or exactly 1 element which is used regardless of the fuse combination and speed bin found on a given chip. - qcom,allow-aging-open-loop-voltage-adjustment Usage: optional Value type: Definition: A list of integers which specifies if CPR aging adjustment should be applied to open-loop voltages for each fuse combination. Note that aging adjustment must be allowed via qcom,allow-aging-voltage-adjustment in order for this property to have an effect. Supported per-combo element values: 0 - do not perform CPR aging adjustment 1 - perform CPR aging adjustment The list must meet the same size requirements as those specified for qcom,allow-aging-voltage-adjustment above. - qcom,cpr-aging-max-voltage-adjustment Usage: required if qcom,allow-aging-voltage-adjustment is specified Value type: Definition: A list of integers which defines the maximum CPR aging voltage margin adjustment in microvolts that may be added for each fuse combination. If this property is specified and the adjustment specified is greater than 0, then aging adjustments are required for this regulator. The list must meet the same size requirements as those specified for qcom,allow-aging-voltage-adjustment above. - qcom,cpr-aging-ref-corner Usage: required if qcom,allow-aging-voltage-adjustment is specified Value type: Definition: A list of integers which defines the CPR reference corner for this regulator to use during aging measurements for each fuse combination. The list must meet the same size requirements as those specified for qcom,allow-aging-voltage-adjustment above. - qcom,cpr-aging-ro-scaling-factor Usage: required if qcom,allow-aging-voltage-adjustment is specified Value type: Definition: A list of integers which defines the CPR aging ring oscillator (RO) scaling factor with units of QUOT/V to use during aging measurements for each fuse combination. The list must meet the same size requirements as those specified for qcom,allow-aging-voltage-adjustment above. - qcom,cpr-aging-derate Usage: optional, though only meaningful if qcom,allow-aging-voltage-adjustment is specified Value type: Definition: A list of integer tuples which each define the CPR aging derating scaling factor to apply to the closed-loop voltage margin adjustment for each corner. The individual scaling factors have units of uV/mV and are ordered from lowest to highest corner per tuple. For example, a value of 900 specifies that the voltage adjustment for the corner should be 90% (900/1000) of that for the reference corner. The list and tuples must meet the same size requirements as those specified for qcom,cpr-voltage-ceiling above. If this property is not specified, then it is assumed that no corners require derating (i.e. the scaling factor would be 1000). All properties specified within the core regulator framework can also be used in third level nodes. These bindings can be found in: Documentation/devicetree/bindings/regulator/regulator.txt. See platform specific cpr3-regulator binding documentation files for examples.