kernel_samsung_msm8974/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.

Additionally, optional subnodes may be included:
- qcom,batt-pres-status : A subnode with a register address for the SMBB
		battery interface's BATT_PRES_STATUS register. If this node is
		added, then the BMS will try to detect offmode battery removal
		via the battery interface's offmode battery removal circuit.
- qcom,soc-storage-reg : A subnode with a register address to a spare PMIC
		register. If this node is included, then the BMS will store its
		shutdown SOC in the specified register instead of the default
		BMS data register.
- qcom,battery-data : A phandle to a node containing the available batterydata
		profiles. See the batterydata bindings documentation for more
		details.

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-voltage-calculate-soc-ms : The time period between subsequent
			SoC recalculations when the current voltage is below
			qcom,low-voltage threshold. This takes precedence over
			qcom,low-soc-calculate-soc-ms.
- 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. This takes
			precedence over qcom,calculate-soc-ms.
- 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.
- qcom,min-fcc-learning-soc: An interger value which defines the minimum SOC
			to start FCC learning. This is applicable only if
			FCC learning is enabled.
- qcom,min-fcc-ocv-pc:	An interger value which defines the minimum PC-lookup
			(OCV) to start FCC learning. This is applicable only if
			FCC learning is enabled.
- qcom,min-fcc-learning-samples: An interger value which defines the minimum
			number of the FCC measurement cycles required to
			generate an FCC update. This is applicable only
			if the FCC learning is enabled.
- qcom,fcc-resolution:	An integer which defines the fcc resolution used
			for storing the FCC(mAh) in the 8-bit BMS register.
			For example - A value of 10 indicates:
			FCC value (in mAh) = (8-bit register value) * 10.
- qcom,bms-vadc: Corresponding VADC device's phandle.
- qcom,bms-iadc: Corresponding IADC device's phandle.

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.
- qcom,enable-fcc-learning: A boolean that defines if FCC learning is enabled.
- qcom,bms-adc_tm: Corresponding ADC_TM device's phandle to set recurring
			measurements and receive notifications for
			die_temperature and vbatt.

qcom,batt-pres-status node required properties:
- reg : offset and length of the PMIC SMBB battery interface BATT_PRES_STATUS
		register.

qcom,soc-storage-reg node required properties:
- reg : address and length of the spare PMIC register that the BMS will store
		shutdown SoC in.

qcom,bms-iadc node required properties:
- reg : offset and length of the PMIC peripheral register map.

qcom,bms-bms 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 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-voltage-calculate-soc-ms = <1000>;
	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,battery-data = <&mtp_batterydata>;
	qcom,bms-vadc = <&pm8941_vadc>;
	qcom,bms-iadc = <&pm8941_iadc>;
	qcom,bms-adc_tm = <&pm8941_adc_tm>;

	qcom,batt-pres-status@1208 {
		reg = <0x1208 0x1>;
	}

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