M7350/kernel/Documentation/devicetree/bindings/power/qpnp-bms.txt

Qualcomm's QPNP PMIC Battery Management System driver

QPNP PMIC BMS provides interface to clients to read properties related
to the battery. It's main function is to calculate 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 BMS driver, both implemented as
subnodes in the example. These peripherals must not be disabled if the BMS
device is to enabled:
- qcom,bms-bms : The main BMS device. Supports battery monitoring controls and
		sensors.
- qcom,bms-iadc : The BMS IADC peripheral in the IADC device. This is required
		to determine whether the BMS is using an internal or external
		rsense to accumulate the Coulomb Counter and read current.

Parent node required properties:
- compatible : should be "qcom,qpnp-bms" for the BM driver.
- qcom,r-sense-uohm : sensor resistance in in micro-ohms.
- qcom,v-cutoff-uv : cutoff voltage where the battery is considered dead in
			micro-volts.
- qcom,max-voltage-uv : maximum voltage for the battery in micro-volts.
- qcom,r-conn-mohm : connector resistance in milli-ohms.
- qcom,shutdown-soc-valid-limit : If the ocv upon restart is within this
			distance of the shutdown ocv, the BMS will try to force
			the new SoC to the old one to provide charge continuity.
			That is to say,
				if (abs(shutdown-soc - current-soc) < limit)
				then use old SoC.
- qcom,adjust-soc-low-threshold : The low threshold for when the BMS algorithm
			starts adjusting. If the estimated SoC is not below
			this percentage, do not adjust.
- qcom,ocv-voltage-low-threshold-uv : The low voltage threshold for the
			"flat portion" of the discharge curve. The bms will not
			accept new ocvs between these thresholds.
- qcom,ocv-voltage-high-threshold-uv : The high voltage threshold for
			the "flat portion" of the discharge curve.
			The bms will not accept new ocvs between these
			thresholds.
- qcom,low-soc-calculate-soc-threshold : The SoC threshold for when
			the periodic calculate_soc work speeds up. This ensures
			SoC is updated in userspace constantly when we are near
			shutdown.
- qcom,low-voltage-threshold : The battery voltage threshold in micro-volts for
			when the BMS tries to wake up and hold a wakelock to
			ensure a clean shutdown.
- qcom,low-soc-calculate-soc-ms : The time period between subsequent
			SoC recalculations when the current SoC is below
			qcom,low-soc-calculate-soc-threshold or when battery
			voltage is below qcom,low-voltage-threshold.
- qcom,calculate-soc-ms : The time period between subsequent SoC
			recalculations when the current SoC is above or equal
			qcom,low-soc-calculate-soc-threshold.
- qcom,chg-term-ua : current in micro-amps when charging is considered done.
			As soon as current passes this point, charging is
			stopped.
- qcom,batt-type: Type of battery used. This is an integer that corresponds
			to the enum defined in
			include/linux/mfd/pm8xxx/batterydata-lib.h
- qcom,high-ocv-correction-limit-uv: how much the bms will correct OCV when
			voltage is above the flat portion of the discharge
			curve.
- qcom,low-ocv-correction-limit-uv: how much the bms will correct OCV when
			voltage is below the flat portion of the discharge
			curve.
- qcom,hold-soc-est: if the voltage-based estimated SoC is above this percent,
			the BMS will clamp SoC to be at least 1.
- qcom,tm-temp-margin: if the pmic die temperature changes by more than this
			value, recalibrate the ADCs. The unit of this property
			is in millidegrees celsius.

Parent node optional properties:
- qcom,ignore-shutdown-soc: A boolean that controls whether BMS will
			try to force the startup SoC to be the same as the
			shutdown SoC. Defining it will make BMS ignore the
			shutdown SoC.
- qcom,use-voltage-soc : A boolean that controls whether BMS will use
			voltage-based SoC instead of a coulomb counter based
			one. Voltage-based SoC will not guarantee linearity.
- qcom,use-external-rsense : A boolean that controls whether BMS will use
			an external sensor resistor instead of the default
			RDS of the batfet.
- qcom,use-ocv-thresholds : A boolean that controls whether BMS will take
			new OCVs only between the defined thresholds.

All sub node required properties:
- reg : offset and length of the PMIC peripheral register map.

qcom,bms-bms node required properties:
- interrupts : the interrupt mappings.
		The format should be
		<slave-id peripheral-id interrupt-number>.
- interrupt-names : names for the mapped bms interrupt
		The following interrupts are required:
		0 : vsense_for_r
		1 : vsense_avg
		2 : sw_cc_thr
		3 : ocv_thr
		4 : charge_begin
		5 : good_ocv
		6 : ocv_for_r
		7 : cc_thr

Example:
pm8941_bms: qcom,bms {
	spmi-dev-container;
	compatible = "qcom,qpnp-bms";
	#address-cells = <1>;
	#size-cells = <1>;
	status = "disabled";

	qcom,r-sense-uohm = <10000>;
	qcom,v-cutoff-uv = <3400000>;
	qcom,max-voltage-uv = <4200000>;
	qcom,r-conn-mohm = <18>;
	qcom,shutdown-soc-valid-limit = <20>;
	qcom,ocv-voltage-low-threshold-uv = <3650000>;
	qcom,ocv-voltage-high-threshold-uv = <3750000>;
	qcom,adjust-soc-low-threshold = <15>;
	qcom,low-soc-calculate-soc-threshold = <15>;
	qcom,low-voltage-threshold = <3420000>;
	qcom,low-soc-calculate-soc-ms = <5000>;
	qcom,calculate-soc-ms = <20000>;
	qcom,chg-term-ua = <100000>;
	qcom,batt-type = <0>;
	qcom,low-ocv-correction-limit-uv = <100>;
	qcom,high-ocv-correction-limit-uv = <50>;
	qcom,hold-soc-est = <3>;
	qcom,tm-temp-margin = <5000>;

	qcom,bms-iadc@3800 {
		reg = <0x3800 0x100>;
	};

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

		interrupt-names = "vsense_for_r",
				  "vsense_avg",
				  "sw_cc_thr",
				  "ocv_thr",
				  "charge_begin",
				  "good_ocv",
				  "ocv_for_r",
				  "cc_thr";
	};
};