android10/kernel/Documentation/devicetree/bindings/power/supply/qcom/qpnp-fg.txt

QTI's QPNP PMIC Fuel Gauge Device

QPNP PMIC FG provides interface to clients to read properties related
to the battery. Its main function is to retrieve the State of Charge (SOC),
a 0-100 percentage representing the amount of charge left in the battery.

There are two required peripherals in the FG driver, both implemented as
subnodes in the example. These peripherals must not be disabled if the FG
device is to enabled:

- qcom,fg-soc : The main FG device. Supports battery fuel gauge controls and
		sensors.
- qcom,fg-batt : The FG battery device supports interrupts and controls with
		respect to the state of the connected battery.For example: the
		peripheral informs the driver if the battery has been identified
		by the fuel gauge based on a given battery resistance range.

Optionally ADC nodes can be added
- qcom,revid-tp-rev: A subnode with a register address for the TP_REV register
		in the REVID peripheral. This is used to apply workarounds that
		may depend on the trim program.
- qcom,fg-adc-vbat : A subnode with a register address for the FG_ADC_USR
		peripheral which is used mainly for battery current limiting (BCL).
		This node maps out the VBAT reading register which allows to have
		a +/- 32 mV accurate reading of VBAT.
- qcom,fg-adc-ibat : A subnode with a register address for the FG_ADC_USR
		peripheral which is used mainly for battery current limiting (BCL).
		This node maps out the IBAT current reading register which allows
		to have a +/- 32 mA accurate reading of IBAT.

Parent node required properties:
- compatible : should be "qcom,qpnp-fg" for the FG driver.
- qcom,pmic-revid :			Should specify the phandle of PMIC
					revid module. This is used to identify
					the PMIC subtype.

Parent node optional properties:
- qcom,warm-bat-decidegc:		Warm battery temperature in decidegC.
- qcom,cool-bat-decidegc:		Cool battery temperature in decidegC.
- qcom,hot-bat-decidegc:		Hot battery temperature in decidegC.
- qcom,cold-bat-decidegc:		Cold battery temperature in decidegC.
- qcom,cold-hot-jeita-hysteresis:	A tuple of 2. Index[0] is cold
					hysteresis and index[1] is hot
					hysterisis(in decidegC).
- qcom,ext-sense-type:			Current sense channel used by the FG.
					Set this to use external rsense.
- qcom,thermal-coefficients:		Byte array of thermal coefficients for
					reading battery thermistor. This should
					be exactly 6 bytes in length.
					Example: [01 02 03 04 05 06]
- qcom,resume-soc:			soc to resume charging in percentage.
- qcom,resume-soc-raw:			soc to resume charging in the scale of
					[0-255]. This overrides qcom,resume-soc
					if defined.
- qcom,hold-soc-while-full:		A boolean property that when defined
					holds SOC at 100% when the battery is
					full.
- qcom,bcl-lm-threshold-ma:		BCL LPM to MPM mode transition threshold
					in milliAmpere.
- qcom,bcl-mh-threshold-ma:		BCL MPM to HPM mode transition threshold
					in milliAmpere.
- qcom,use-otp-profile:			Specify this flag to avoid RAM loading
					any battery profile.
- qcom,sw-rbias-control:		Boolean property which defines whether
					the Rbias needs to be controlled by
					software. If this is not set, it will
					be controlled by hardware (default).
- qcom,fg-iterm-ma:			Battery current at which the fuel gauge
					will try to scale 100% towards. When
					the charge current goes above this, the
					SoC should be at 100%.
- qcom,fg-chg-iterm-ma:			Battery current at which the fuel gauge
					will issue end of charge if the charger
					is configured to use the fuel gauge
					ADCs for end of charge detection. This
					property is in milliamps and should be
					positive (e.g. 100mA to terminate at
					-100mA).
- qcom,irq-volt-empty-mv:		The voltage threshold that the empty
					soc interrupt will be triggered. When
					the empty soc interrupt fires, battery
					soc will be pulled to 0 and the
					userspace will be notified via the
					power supply framework. The userspace
					will read 0% soc and immediately
					shutdown.
- qcom,fg-cutoff-voltage-mv:		The voltage where the fuel gauge will
					steer the SOC to be zero. For example,
					if the cutoff voltage is set to 3400mv,
					the fuel gauge will try to count SoC so
					that the battery SoC will be 0 when it
					is 3400mV.
- qcom,fg-vbat-estimate-diff-mv:	If the estimated voltage based on SoC
					and battery current/resistance differs
					from the actual voltage by more than
					this amount, the fuel gauge will
					redo the first SoC estimate when the
					driver probes.
- qcom,fg-delta-soc:			How many percent the monotonic SoC must
					change before a new delta_soc interrupt
					is asserted. If this value is raised
					above 3-4, some period workarounds may
					not function well, so it's best to
					leave this at 1 or 2%.
- qcom,fg-vbatt-low-threshold:		Voltage (in mV) which upon set will be
					used for configuring the low battery
					voltage threshold. Interrupt will be
					asserted and handled based upon
					this. If this property is not specified,
					low battery voltage threshold will be
					configured to 4200 mV.
- qcom,fg-rconn-mohm:			Battery connector resistance (Rconn) in
					milliohms. If Rconn is specified, then
					Rslow values will be updated to account
					it for an accurate ESR.
- qcom,cycle-counter-en:		Boolean property which enables the cycle
					counter feature. If this property is
					present, then the following properties
					to specify low and high soc thresholds
					should be defined.
- qcom,capacity-learning-on:		A boolean property to have the fuel
					gauge driver attempt to learn the
					battery capacity when charging. Takes
					precedence over capacity-estimation-on.
- qcom,capacity-learning-feedback:	A boolean property to have the fuel
					gauge driver to feedback the learned
					capacity into the capacity learning
					algorithm. This has to be used only if
					the property "qcom,capacity-learning-on"
					is specified.
- qcom,cl-max-increment-deciperc:	The maximum percent that the capacity
					can rise as the result of a single
					charge cycle. This property corresponds
					to .1% increments.
- qcom,cl-max-decrement-deciperc:	The maximum percent that the capacity
					can fall as the result of a single
					charge cycle. This property corresponds
					to .1% decrements.
- qcom,cl-max-temp-decidegc:		Above this temperature, capacity
					learning will be canceled.
- qcom,cl-mix-temp-decidegc:		Below this temperature, capacity
					learning will be canceled.
- qcom,cl-max-start-soc:		The battery soc has to be below this
					value at the start of a charge cycle
					for capacity learning to be run.
- qcom,cl-vbat-est-thr-uv:		The maximum difference between the
					battery voltage shadow and the current
					predicted voltage in uV to initiate
					capacity learning.
- qcom,cl-max-limit-deciperc:		The maximum percent that the capacity
					cannot go above during any capacity
					learning cycle. This property is in the
					unit of .1% increments.
- qcom,cl-min-limit-deciperc:		The minimum percent that the capacity
					cannot go below during any capacity
					learning cycle. This property is in the
					unit of .1% increments.
- qcom,capacity-estimation-on:		A boolean property to have the fuel
					gauge driver attempt to estimate the
					battery capacity using battery
					resistance.
- qcom,aging-eval-current-ma:		Current used to evaluate battery aging.
					This value should be around the steady
					state current drawn from the battery
					when the phone is low on battery.
- qcom,fg-cc-cv-threshold-mv:		Voltage threshold in mV for configuring
					constant charge (CC) to constant
					voltage (CV) setpoint in FG upon
					which the battery EOC status will
					be determined. This value should be
					10 mV less than the float voltage
					configured in the charger.
					This property should only be specified
					if "qcom,autoadjust-vfloat" property is
					specified in the charger driver to
					ensure a proper operation.
- qcom,bad-battery-detection-enable:	A boolean property to enable the fuel
					gauge driver to detect the damaged battery
					when the safety-timer expires by using the
					coulomb count.
- qcom,fg-therm-delay-us:		The time in microseconds to delay battery
					thermistor biasing.
- qcom,esr-pulse-tuning-en:		A boolean property to enable ESR pulse
					tuning feature. If this is enabled,
					ESR pulse extraction will be disabled
					when state of charge (SOC) is less than
					2%. It will be enabled back when SOC
					gets above 2%. In addition, for SOC
					between 2% and 5%, ESR pulse timing
					settings will be different from default.
					Once SOC crosses 5%, ESR pulse timings
					will be restored back to default.
- qcom,fg-control-slope-limiter:	A boolean property to specify if SOC
					slope limiter coefficients needs to
					be modified based on charging status
					and battery temperature threshold.
- qcom,fg-slope-limit-temp-threshold:	Temperature threshold in decidegC used
					for applying the slope coefficient based
					on charging status and battery
					temperature. If this property is not
					specified, a default value of 100 (10C)
					will be applied by default.
- qcom,fg-slope-limit-low-temp-chg:	When the temperature goes below the
					specified temperature threshold and
					battery is charging, slope coefficient
					specified with this property will be
					applied. If this property is not
					specified, a default value of 45 will be
					applied.
- qcom,fg-slope-limit-low-temp-dischg:	Same as "qcom,fg-slope-limit-low-temp-chg"
					except this is when the battery is
					discharging.
- qcom,fg-slope-limit-high-temp-chg:	When the temperature goes above the
					specified temperature threshold and
					battery is charging, slope coefficient
					specified with this property will be
					applied. If this property is not
					specified, a default value of 2 will be
					applied.
- qcom,fg-slope-limit-high-temp-dischg:	Same as "qcom,fg-slope-limit-high-temp-chg"
					except this is when the battery is
					discharging.
- qcom,fg-dischg-voltage-gain-ctrl:	A boolean property to specify if the
					voltage gain needs to be modified
					during discharging based on monotonic
					soc.
- qcom,fg-dischg-voltage-gain-soc:	Array of monotonic SOC threshold values
					to change the voltage gain settings
					during discharge. This should be defined
					in the ascending order and in the range
					of 0-100. Array limit is set to 3.
					If qcom,fg-dischg-voltage-gain-ctrl is
					set, then this property should be
					specified to apply the gain settings.
- qcom,fg-dischg-med-voltage-gain:	Array of voltage gain values that needs
					to be applied to medC voltage gain when
					the monotonic SOC goes below the SOC
					threshold specified under
					qcom,fg-dischg-voltage-gain-soc. Array
					limit is set to 3.
					If qcom,fg-dischg-voltage-gain-ctrl is
					set, then this property should be
					specified to apply the gain setting.
- qcom,fg-dischg-high-voltage-gain:	Array of voltage gain values that needs
					to be applied to highC voltage gain when
					the monotonic SOC goes below the SOC
					threshold specified under
					qcom,fg-dischg-voltage-gain-soc. Array
					limit is set to 3.
					If qcom,fg-dischg-voltage-gain-ctrl is
					set, then this property should be
					specified to apply the gain setting.
- qcom,fg-use-vbat-low-empty-soc:	A boolean property to specify whether
					vbatt-low interrupt is used to handle
					empty battery condition. If this is
					not specified, empty battery condition
					is detected by empty-soc interrupt.
- qcom,fg-batt-temp-low-limit:		Battery temperature (in decidegC) low
					limit  which will be used to validate
					the battery temperature reading from FG.
					If the battery temperature goes below
					this limit, last read good temperature
					will be notified to userspace. If this
					limit is not specified, then the
					default limit would be -60C.
- qcom,fg-batt-temp-high-limit:		Battery temperature (in decidegC) high
					limit  which will be used to validate
					the battery temperature reading from FG.
					If the battery temperature goes above
					this limit, last read good temperature
					will be notified to userspace. If this
					limit is not specified, then the
					default limit would be 150C.
- qcom,fg-cc-soc-limit-pct:		Percentage of CC_SOC before resetting
					FG and restore the full CC_SOC value.
- qcom,fg-restore-batt-info:		A boolean property to specify whether
					battery parameters needs to be
					restored. If this feature is enabled,
					then validating the battery parameters
					by OCV/battery SOC, validation range
					in percentage should be specified via
					appropriate module parameters to make
					it work properly.

qcom,fg-soc node required properties:
- reg : offset and length of the PMIC peripheral register map.
- interrupts : the interrupt mappings.
		The format should be
		<slave-id peripheral-id interrupt-number>.
- interrupt-names : names for the mapped fg soc interrupts
		The following interrupts are required:
		0: high-soc
		1: low-soc
		2: full-soc
		3: empty-soc
		4: delta-soc
		5: first-est-done
		6: sw-fallbk-ocv
		7: sw-fallbk-new-batt

qcom,fg-memif node required properties:
- reg : offset and length of the PMIC peripheral register map.
- interrupts : the interrupt mappings.
		The format should be
		<slave-id peripheral-id interrupt-number>.
- interrupt-names : names for the mapped fg adc interrupts
		The following interrupts are required:
		0: mem-avail

Example:
pmi8994_fg: qcom,fg {
	compatible = "qcom,qpnp-fg";
	#address-cells = <1>;
	#size-cells = <1>;
	status = "disabled";
	qcom,pmic-revid = <&pmi8994_revid>;

	qcom,fg-soc@4000 {
		reg = <0x4000 0x100>;
		interrupts =	<0x2 0x40 0x0>,
				<0x2 0x40 0x1>,
				<0x2 0x40 0x2>,
				<0x2 0x40 0x3>,
				<0x2 0x40 0x4>,
				<0x2 0x40 0x5>,
				<0x2 0x40 0x6>,
				<0x2 0x40 0x7>;

		interrupt-names =	"high-soc",
					"low-soc",
					"full-soc",
					"empty-soc",
					"delta-soc",
					"first-est-done",
					"sw-fallbk-ocv",
					"sw-fallbk-new-batt";
	};

	qcom,fg-batt@4100 {
		reg = <0x4100 0x100>;
		interrupts =	<0x2 0x41 0x0>,
				<0x2 0x41 0x1>,
				<0x2 0x41 0x2>,
				<0x2 0x41 0x3>,
				<0x2 0x41 0x4>,
				<0x2 0x41 0x5>,
				<0x2 0x41 0x6>,
				<0x2 0x41 0x7>;

		interrupt-names =	"soft-cold",
					"soft-hot",
					"vbatt-low",
					"batt-ided",
					"batt-id-req",
					"batt-unknown",
					"batt-missing",
					"batt-match";
	};

	qcom,fg-adc-vbat@4254 {
		reg = <0x4254 0x1>;
	};

	qcom,fg-adc-ibat@4255 {
		reg = <0x4255 0x1>;
	};

	qcom,fg-memif@4400 {
		reg = <0x4400 0x100>;
		interrupts =	<0x2 0x44 0x0>,
				<0x2 0x44 0x1>;

		interrupt-names =	"mem-avail",
					"data-rcvry-sug";

		qcom,cold-hot-jeita-hysteresis = <30 50>;
	};
};