blob: b02d759b1cf73b97cf6450cd7d6c95d6a35cfa99 [file] [log] [blame]
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: <string>
Definition: The value to use for this property is defined in the
platform specific cpr3-regulator binding documentation
files.
- reg
Usage: required
Value type: <prop-encoded-array>
Definition: Addresses and sizes for the memory of the CPR3 controller,
the first fuse row, and optionally the SAW module and/or a
register used to check if aging measurements are possible.
- reg-names
Usage: required
Value type: <stringlist>
Definition: Address names. Must include "cpr_ctrl" and "fuse_base".
"aging_allowed" and "saw" may also be specified. 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: <string>
Definition: Name for this CPR controller
- vdd-supply
Usage: required
Value type: <phandle>
Definition: phandle of the underlying regulator device that is managed
by this CPR controller.
- system-supply
Usage: optional
Value type: <phandle>
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: <phandle>
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: <prop-encoded-array>
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: <stringlist>
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: <prop-encoded-array>
Definition: CPR interrupt specifier and optionally a hardware
closed-loop ceiling interrupt specifier.
- interrupt-names
Usage: required
Value type: <stringlist>
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: <prop-encoded-array>
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: <u32>
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: <u32>
Definition: The time in nanoseconds between consecutive CPR
measurements.
- qcom,cpr-idle-cycles
Usage: required
Value type: <u32>
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: <u32>
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: <u32>
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: <u32>
Definition: The default maximum CPR step quotient value.
Supported values: 0 - 63.
- qcom,cpr-count-mode
Usage: required
Value type: <u32>
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: <u32>
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: <empty>
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: <u32>
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: <u32>
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: <u32>
Definition: Value required in the masked off "aging_allowed" register
bits in order for a CPR aging measurement to be possible.
- qcom,cpr-ignore-invalid-fuses
Usage: optional
Value type: <empty>
Definition: Boolean flag which indicates that software should ignore
invalid fuse values. This should only be used on simulator
targets in which fuses are not initialized.
- qcom,cpr-panic-reg-addr-list
Usage: optional
Value type: <prop-encoded-array>
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: <prop-encoded-array>
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.
- qcom,cpr-reset-step-quot-loop-en
Usage: optional; only meaningful for CPR4 and CPRh controllers
Value type: <empty>
Definition: Boolean value which indicates that the CPR controller should
be configured to reset step_quot on each loop_en = 0
transition. This configuration allows the CPR controller to
first use the default step_quot and then later switch to the
run-time calibrated step_quot.
- qcom,saw-avs-ctrl
Usage: required if "saw" registers are specified by reg and
reg-names properties
Value type: <u32>
Definition: SAW AVS_CTL register value to program at initialization time
in order to allow hardware closed-loop CPR voltage change
requests to reach the PMIC regulator.
- qcom,saw-avs-limit
Usage: required if "saw" registers are specified by reg and
reg-names properties
Value type: <u32>
Definition: SAW AVS_LIMIT register value to program at initialization
time in order to allow hardware closed-loop CPR voltage
change requests to reach the PMIC regulator.
- qcom,cpr-thread-has-always-vote-en
Usage: optional; only meaningful for CPR4 controller
Value type: <empty>
Definition: Boolean value which indicates that the CPR controller should
be configured to keep thread vote always enabled. This
configuration allows the CPR controller to not consider
MID/DN recommendations from other thread when all sensors
mapped to a thread collapsed.
=================================================
Second Level Nodes - CPR Threads for a Controller
=================================================
Platform independent properties:
- qcom,cpr-thread-id
Usage: required
Value type: <u32>
Definition: Specifies the hardware thread ID of this thread within the
CPR controller.
- qcom,cpr-consecutive-up
Usage: required
Value type: <u32>
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: <u32>
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: <u32>
Definition: The number CPR error steps required to generate an up event.
Supported values: 0 - 31.
- qcom,cpr-down-threshold
Usage: required
Value type: <u32>
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: <string>
Definition: Specifies the name for this CPR3 regulator.
- regulator-min-microvolt
Usage: required
Value type: <u32>
Definition: Minimum corner value which should be 1 to represent the
lowest supported corner.
- regulator-max-microvolt
Usage: required
Value type: <u32>
Definition: Maximum corner value which should be equal to largest value
listed in qcom,cpr-corners.
- qcom,cpr-fuse-corners
Usage: required
Value type: <u32>
Definition: Specifies the number of fuse corners. See platform specific
binding files for further requirements.
- qcom,cpr-fuse-combos
Usage: required
Value type: <u32>
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-speed-bins
Usage: optional
Value type: <u32>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <empty>
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: <empty>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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: <prop-encoded-array>
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.