Qualcomm Technologies, Inc. CPR4 Regulator - APSS Specific Bindings

APSS CPR4 controllers each support one CPR thread that monitors the voltage of
a pair of application processor (APSS) clusters that are powered by a shared
regulator supply. They also have a hardware channel to use these requests to
directly change the supply voltage at the PMIC via the SPM without software
intervention.

APSS CPR4 controllers also have to take into account the state of the memory
array power mux (APM) when scaling voltage to ensure that memory always receives
a sufficiently high voltage.

Both CPR open-loop voltages and CPR target quotients are stored in hardware
fuses for APSS CPR4 controllers.

This document describes the APSS specific CPR4 bindings.

=======================
Required Node Structure
=======================

CPR4 regulators must be described in three levels of devices nodes.  The first
level describes the CPR4 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.

All platform independent cpr3-regulator binding guidelines defined in
cpr3-regulator.txt also apply to cpr4-apss-regulator devices.

====================================
First Level Nodes - CPR4 Controllers
====================================

APSS specific properties:
- compatible
	Usage:      required
	Value type: <string>
	Definition: should be one of the following:
		    "qcom,cpr4-ipq807x-apss-regulator";

- interrupts
	Usage:      required
	Value type: <prop-encoded-array>
	Definition: CPR 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.

- qcom,apm-ctrl
	Usage:      required on systems that need APM management
	Value type: <phandle>
	Definition: phandle of memory array power mux (APM) controller device
		    node for the APM that is used by the APSS VDD supply

- qcom,apm-threshold-voltage
	Usage:      required if qcom,apm-ctrl is specified
	Value type: <u32>
	Definition: Specifies the APM threshold voltage in microvolts.  If the
		    vdd-supply voltage is greater than or equal to this level,
		    then the APM is switched to use the vdd-supply. If the
		    vdd-supply voltage is below this level, then the APM is
		    switched to use the system-supply.

- qcom,apm-hysteresis-voltage
	Usage:      optional
	Value type: <u32>
	Definition: Specifies the voltage delta in microvolts between the APM
		    threshold voltage and the highest corner open-loop voltage
		    which may be used as the ceiling for the corner.  If this
		    property is not specified, then a value of 0 is assumed.

- qcom,cpr-hw-closed-loop
	Usage:      optional
	Value type: <empty>
	Definition: Boolean flag which indicates that the APSS CPR4 controller
		    should operate in hardware closed-loop mode as opposed to
		    software closed-loop mode.

- vdd-limit-supply
	Usage:      required
	Value type: <phandle>
	Definition: phandle of the VDD supply limit regulator which controls the
		    CPR ceiling and floor voltages when operating in hardware
		    closed-loop mode.

- qcom,cpr-down-error-step-limit
	Usage:      required
	Value type: <u32>
	Definition: CPR4 hardware closed-loop down error step limit which
		    defines the maximum number of vdd-supply regulator steps
		    that the voltage may be reduced as the result of a single
		    CPR measurement.

- qcom,cpr-up-error-step-limit
	Usage:      required
	Value type: <u32>
	Definition: CPR4 hardware closed-loop up error step limit which defines
		    the maximum number of vdd-supply regulator steps that the
                    voltage may be increased as the result of a single
		    CPR measurement.

- qcom,cpr-saw-use-unit-mV
	Usage:      optional
	Value type: <empty>
	Definition: Boolean flag which indicates that the unit used in SAW PVC
		    interface is mV. Use this for vdd-supply regulators which
		    do not use PMIC voltage control register LSBs per actually
		    unique PMIC regulator output voltage.

- qcom,cpr-temp-point-map
	Usage:      required if qcom,corner-allow-temp-adjustment is specified
		    for at least one of the CPR3 regulators.
	Value type: <prop-encoded-array>
	Definition: The temperature points in decidegrees Celsius which indicate
		    the range of temperature bands supported. If t1, t2, and t3
		    are the temperature points, then the temperature bands are:
		    (-inf, t1], (t1, t2], (t2, t3], and (t3, inf).

- qcom,cpr-initial-temp-band
	Usage:      required if qcom,corner-allow-temp-adjustment is specified
		    for at least one of the CPR3 regulators.
	Value type: <u32>
	Definition: The initial temp band considering 0-based index at which
		    the baseline target quotients are derived and fused.

- qcom,cpr-step-quot-fixed
	Usage:      optional
	Value type: <u32>
	Definition: Fixed step quotient value used by controller for applying
		    the SDELTA margin adjustments on the programmed target
		    quotient values. 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-voltage-settling-time
	Usage:      optional
	Value type: <u32>
		    The time in nanoseconds that it takes for the vdd-supply
		    voltage to settle after being increased or decreased by
		    qcom,voltage-step microvolts. This is used as the wait
		    time after applying SDELTA voltage margin adjustments.

=================================================
Second Level Nodes - CPR Threads for a Controller
=================================================

APSS specific properties:
N/A

===============================================
Third Level Nodes - CPR Regulators for a Thread
===============================================

APSS specific properties:
- qcom,cpr-fuse-corners
	Usage:      required
	Value type: <u32>
	Definition: Specifies the number of fuse corners. This value must be 4
		    for APSS. These fuse corners are: LowSVS, SVS, Nominal,
		    and Turbo.

- 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.  For APSS the maximum
		    supported value is 64.  The first 8 fuse combos correspond
		    to speed bin fuse value 0 along with CPR revision fuse
		    values 0 to 7.  The second 8 fuse combos correspond to speed
		    bin fuse value 1 along with CPR revision fuse values 0 to 7.
		    The last 8 fuse combos correspond to speed bin fuse value 7
		    along with CPR revision fuse values 0 to 7.

- 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.  For APSS the maximum supported value
		    is 8.

- qcom,mem-acc-voltage
	Usage:      required if mem-acc-supply is specified for the CPR4 controller
		    containing this regulator
	Value type: <prop-encoded-array>
	Definition: A list of integer tuples which each define the mem-acc-supply
		    corner 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,allow-quotient-interpolation
	Usage:      optional
	Value type: <empty>
	Definition: Boolean flag which indicates that it is acceptable to use
		    interpolated CPR target quotient values.  These values are
		    interpolated between the target quotient Fmax fuse values.

- qcom,corner-allow-core-count-adjustment
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: A list of integer tuples which each define the CPR core
		    count adjustment feature enable state for each voltage
		    corner in order from lowest to highest. Each element in
		    the tuple should be either 0 (per-core-count adjustment
		    not allowed) or 1 (per-core-count adjustment allowed).

		    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,max-core-count
	Usage:      required if qcom,corner-allow-core-count-adjustment is
		    specified for this CPR3 regulator.
	Value type: <u32>
	Definition: The maximum number of cores considered for core-count vmin
		    adjustments specified for this regulator voltage corners.

- qcom,corner-allow-temp-adjustment
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: A list of integer tuples which each define the CPR
		    temperature adjustment feature enable state for each voltage
		    corner in order from lowest to highest. Each element in the
		    tuple should be either 0 (temperature adjustment not
		    allowed) or 1 (temperature adjustment allowed).

		    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-cornerX-temp-core-voltage-adjustment
	Usage:      required if qcom,corner-allow-core-count-adjustment
		    specified for this CPR3 regulator.
	Value type: <prop-encoded-array>
	Definition: A grouping of integer tuple lists for cornerX. The possible
		    values for X are 1 to the max value specified in
		    qcom,cpr-corners. Each tuple defines the temperature based
		    voltage adjustment in microvolts for each temperature band
		    from lowest to highest for a given number of online cores.
		    Each tuple must have a number of elements equal to either
		    (the number of elements in qcom,cpr-ctrl-temp-point-map
		    + 1), if qcom,cpr-ctrl-temp-point-map is specified, or 1.

		    Each tuple list must contain a number of tuples equal to
		    either qcom,max-core-count, if qcom,max-core-count is
		    specified, or 1. The tuples should be ordered from lowest
		    to highest core count.

		    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.

- qcom,cpr-num-boost-cores
	Usage:      required if qcom,allow-boost specified for this CPR3
		    regulator.
	Value type: <u32>
	Definition: Integer value indicates that voltage boost will be applied
		    when the number of online cores become this value.

- qcom,cpr-boost-temp-adjustment
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: A list of integer tuples which each define the temperature
		    based voltage adjustment to boost voltage in microvolts
		    for each temperature band in order from lowest to highest.

		    The number of elements in each tuple should be equal to either
		    (the number of elements in qcom,cpr-ctrl-temp-point-map
		    + 1), if qcom,cpr-ctrl-temp-point-map is specified, or 1.

		    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,allow-boost
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: A list of integers which specifies if the voltage boost
		    feature should be enabled for each fuse combination.
		    Supported per-combo element values:
			0 - voltage boost feature disabled
			1 - voltage boost feature enabled

		    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,cpr-boost-voltage-fuse-adjustment
	Usage:      optional
	Value type: <u32>
	Definition: A list of integers which defines the voltage adjustment
		    in microvolts for the fused boost voltage. This adjustment
		    is applied to the values read from boost fuses.

		    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,cpr-misc-fuse-voltage-adjustment
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: A grouping of integer tuple lists where each tuple defines
		    the voltage adjustments in microvolts for each voltage
		    corner in order from lowest to highest. This adjustment is
		    applied to both open-loop and closed-loop voltages.

		    Each tuple list must contain a number of tuples equal to
		    2 to the power of the number of bits selected for misc
		    voltage adj fuse definition. For MSM8953 the tuple
		    list must contain 2 tuples for the 1-bit misc fuse.
		    Tuples in a list should be specified in ascending order
		    according to the misc fuse value assuming that the fuse
		    is treated like an unsigned integer.

		    The tuple list grouping must contain 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 speed bin found on a given chip.

- qcom,cpr-ro-sel
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: A list of integers which defines the RO select values for
		    each corner per CPR revision.

		    The tuple list should be used when fused RO select values are
		    not proper.

=======
Example
=======

apc_cpr: cpr4-ctrl@b018000 {
	compatible = "qcom,cpr4-msm8953-apss-regulator";
	reg = <0xb018000 0x4000>, <0xa4000 0x1000>;
	reg-names = "cpr_ctrl", "fuse_base";
	interrupts = <GIC_SPI 15 IRQ_TYPE_EDGE_RISING>;
	interrupt-names = "cpr";

	qcom,cpr-ctrl-name = "apc";

	qcom,cpr-sensor-time = <1000>;
	qcom,cpr-loop-time = <5000000>;
	qcom,cpr-idle-cycles = <15>;
	qcom,cpr-step-quot-init-min = <13>;
	qcom,cpr-step-quot-init-max = <13>;
	qcom,cpr-count-mode = <2>;		/* Staggered */
	qcom,cpr-down-error-step-limit = <1>;
	qcom,cpr-up-error-step-limit = <1>;

	qcom,apm-ctrl = <&apc_apm>;
	qcom,apm-threshold-voltage = <848000>;
	qcom,apm-hysteresis-voltage = <5000>;

	vdd-supply = <&pm8953_s5>;
	qcom,voltage-step = <5000>;
	vdd-limit-supply = <&pm8953_s5_limit>;
	mem-acc-supply = <&apc_mem_acc_vreg>;

	qcom,cpr-enable;
	qcom,cpr-hw-closed-loop;

	qcom,cpr-temp-point-map = <0 250 850>;
	qcom,cpr-initial-temp-band = <3>;
	qcom,cpr-step-quot-fixed = <16>;
	qcom,cpr-voltage-settling-time = <1600>;

	qcom,cpr-panic-reg-addr-list =
			<0xb1d2c18 0xb1d2900 0x0b1112b0 0xb018798>;
	qcom,cpr-panic-reg-name-list =
			"CCI_SAW4_PMIC_STS", "CCI_SAW4_VCTL",
			"APCS_ALIAS0_APM_CTLER_STATUS",
			"APCS0_CPR_CORE_ADJ_MODE_REG";

	thread@0 {
		qcom,cpr-thread-id = <0>;
		qcom,cpr-consecutive-up = <1>;
		qcom,cpr-consecutive-down = <1>;
		qcom,cpr-up-threshold = <1>;
		qcom,cpr-down-threshold = <1>;

		apc_vreg: regulator {
			regulator-name = "apc_corner";
			regulator-min-microvolt = <1>;
			regulator-max-microvolt = <8>;

			qcom,cpr-fuse-corners = <4>;
			qcom,cpr-fuse-combos = <8>;
			qcom,cpr-speed-bins = <1>;
			qcom,cpr-corners = <8>;

			qcom,cpr-corner-fmax-map = <1 2 4 8>;

			qcom,cpr-voltage-ceiling =
				<645000  720000 790000  865000 920000
				 990000 1065000 1065000>;

			qcom,cpr-voltage-floor =
				<590000  625000 690000  755000 800000
				 855000  920000 920000>;

			qcom,mem-acc-voltage = <1 1 2 2 2 2 2 2>;

			qcom,corner-frequencies =
				<652800000 1036800000 1401600000
				1689600000 1843200000 1958400000
				2150400000 2208000000>;

			qcom,cpr-misc-fuse-voltage-adjustment =
				/* Speed bin 0; misc fuse 0..1 */
				<    0     0     0     0
				     0     0     0     0>,
				<    0     0 30000     0
				     0     0     0     0>;

			qcom,allow-voltage-interpolation;
			qcom,allow-quotient-interpolation;
			qcom,cpr-scaled-open-loop-voltage-as-ceiling;

			qcom,corner-allow-temp-adjustment =
					<0 0 0 1 0 1 1 1>;

			qcom,corner-allow-core-count-adjustment =
					<0 0 0 0 1 1 1 1>;
			qcom,max-core-count = <8>;
			qcom,cpr-corner4-temp-core-voltage-adjustment =
				<(-20000) (-10000) (-5000) 0>,
				<(-20000) (-10000) (-5000) 0>,
				<(-20000) (-10000) (-5000) 0>,
				<(-20000) (-10000) (-5000) 0>,
				<(-20000) (-10000) (-5000) 0>,
				<(-20000) (-10000) (-5000) 0>,
				<(-20000) (-10000) (-5000) 0>,
				<(-20000) (-10000) (-5000) 0>;
			qcom,cpr-corner5-temp-core-voltage-adjustment =
				<(-50000) (-50000) (-50000) (-50000)>,
				<(-50000) (-50000) (-50000) (-50000)>,
				<(-40000) (-40000) (-40000) (-40000)>,
				<(-40000) (-40000) (-40000) (-40000)>,
				<(-30000) (-30000) (-30000) (-30000)>,
				<(-30000) (-30000) (-30000) (-30000)>,
				<(-20000) (-20000) (-20000) (-20000)>,
				<(-20000) (-20000) (-20000) (-20000)>;
			qcom,cpr-corner6-temp-core-voltage-adjustment =
				<(-50000) (-40000) (-30000) (-20000)>,
				<(-50000) (-40000) (-30000) (-20000)>,
				<(-40000) (-30000) (-20000) (-10000)>,
				<(-40000) (-30000) (-20000) (-10000)>,
				<(-30000) (-20000) (-10000)  (-5000)>,
				<(-30000) (-20000) (-10000)  (-5000)>,
				<(-20000) (-10000)  (-5000)       0 >,
				<(-20000) (-10000)  (-5000)       0 >;
			qcom,cpr-corner7-temp-core-voltage-adjustment =
				<(-50000) (-40000) (-30000) (-20000)>,
				<(-50000) (-40000) (-30000) (-20000)>,
				<(-40000) (-30000) (-20000) (-10000)>,
				<(-40000) (-30000) (-20000) (-10000)>,
				<(-30000) (-20000) (-10000)  (-5000)>,
				<(-30000) (-20000) (-10000)  (-5000)>,
				<(-20000) (-10000)  (-5000)       0 >,
				<(-20000) (-10000)  (-5000)       0 >;
			qcom,cpr-corner8-temp-core-voltage-adjustment =
				<(-50000) (-40000) (-30000) (-20000)>,
				<(-50000) (-40000) (-30000) (-20000)>,
				<(-40000) (-30000) (-20000) (-10000)>,
				<(-40000) (-30000) (-20000) (-10000)>,
				<(-30000) (-20000) (-10000)  (-5000)>,
				<(-30000) (-20000) (-10000)  (-5000)>,
				<(-20000) (-10000)  (-5000)       0 >,
				<(-20000) (-10000)  (-5000)       0 >;

			qcom,cpr-num-boost-cores = <4>;
			qcom,cpr-boost-voltage-fuse-adjustment = <(-10000)>;
			qcom,cpr-boost-temp-adjustment =
				<(-20000) (-15000) (-10000) 0>;
			qcom,allow-boost =
				<1>;
		};
	};
};