Documentation/devicetree/bindings/power/qpnp-fg.txt - kernel/msm - Git at Google

 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,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-soc-max:			The percent SoC threshold at which the
 					HIGH_SOC interrupt will be asserted.
 - qcom,fg-soc-min:			The percent SoC threshold at which the
 					LOW_SOC interrupt will be asserted.
 - 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,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,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,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-battrt-sts

 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 {
 	spmi-dev-container;
 	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-battrt-sts",
 					"fg-soc-irq-count";
 	};

 	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";
 	};
 };
	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,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-soc-max: The percent SoC threshold at which the
	HIGH_SOC interrupt will be asserted.
	- qcom,fg-soc-min: The percent SoC threshold at which the
	LOW_SOC interrupt will be asserted.
	- 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,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,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,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-battrt-sts

	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 {
	spmi-dev-container;
	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-battrt-sts",
	"fg-soc-irq-count";
	};

	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";
	};
	};