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

Qualcomm's QPNP Voltage-Mode(VM) PMIC Battery Management System

QPNP PMIC VM BMS provides interface to clients to read properties related
to the battery. Its main function is to calculate the SOC (state of charge)
of the battery based on periodic sampling of the VBAT (battery voltage).

Parent node required properties:
- compatible	: Must be  "qcom,qpnp-vm-bms" for the BM driver.
- 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 : leave CV state
		1 : enter CV state
		2 : good ocv generated
		3 : ocv_thr
		4 : fifo update
		5 : fsm state chnaged

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,battery-data : A phandle to a node containing the available batterydata
		profiles. See the batterydata bindings documentation for more
		details.

Parent node required properties:
- 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,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,volatge-soc-timeout-ms : The timeout period after which the module starts
			reporting volage based SOC and does not use the VMBMS
			algorithm for SOC calculation.
- qcom,bms-vadc: Corresponding VADC device's phandle.
- qcom,bms-adc_tm: Corresponding ADC_TM device's phandle to set recurring
                        measurements and receive notifications for vbatt.
- qcom,pmic-revid : Phandle pointing to the revision peripheral node.

Parent node Optional properties
- qcom,s1-sample-interval-ms: The sampling rate in ms of the accumulator in state
			S1. (i.e) the rate at which the accumulator is being
			filled with vbat samples. Minimum value = 0 and
			Maximum value = 2550ms.
- qcom,s2-sample-interval-ms: The sampling rate in ms of the accumulator in state
			S2. (i.e) the rate at which the accumulator is being
			filled with vbat samples. Minimum value = 0 and
			Maximum value = 2550ms.
- qcom,s1-sample-count: The number of samples to be accululated for one FIFO in
			state S1. Possible values are - 0, 4, 8, 16, 32, 64, 128,
			256.
- qcom,s2-sample-count: The number of samples to be accululated for one FIFO in
			state S2. Possible values are - 0, 4, 8, 16, 32, 64, 128,
			256.
- qcom,s1-fifo-legth:	Number of FIFO's to be filled in state S1, to generate
			the fifo_update_done interrupt. Possile values - 0 to 8
- qcom,s2-fifo-legth:	Number of FIFO's to be filled in state S2, to generate
			the fifo_update_done interrupt. Possible values- 0 to 8
- qcom,force-s3-on-suspend : Bool property to force the BMS into S3 (sleep) state
			while entering into system suspend.
- qcom,force-bms-active-on-charger: Bool property to keep BMS FSM active
				if charger is present.
- qcom,report-charger-eoc : Bool property to indicate if BMS needs to indicate
			EOC to charger.
- 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,disable-bms :	Bool property to disable the VMBMS hardware module.
			Enable this property if BMS is not supported or an external
			fuel gauge is used.
- qcom,s3-ocv-tolerence-uv : The S3 state OCV tolerence threshold in uV. The
			LSB value is 300uV and maximum value is 76500uV.
- qcom,low-soc-fifo-length : The fifo length (of S2 STATE) to be used at lower
			SOCs. If this value is not specified the system uses
			default length.
- qcom,resume-soc:	Capacity in percent at which charging should resume
			when a fully charged battery drops below this level.
- qcom,low-temp-threshold : The temperature threshold below which the IBAT
			averaging and UUC smoothening is disabled. This value
			is in deci-degrees centigrade. If not specified it
			defaults to 0.
- qcom,ibat-avg-samples : The number of samples to be averaged for IBAT
			estimation. If not specified it defaults to 16.
			The possible values are 1 to 16.
- qcom,batt-aging-comp : A boolean that defines if battery aging compensation
			is enabled.
- qcom,use-reported-soc : Bool property to enable the reported_soc logic. To
			enable this feature, qcom,resume-soc must be defined as
			a proper value. The BMS is also required to control the
			charging, discharging and recharging.

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

qcom,qpnp-chg-pres required properties:
- reg : offset and length of the PMIC LBC charger interafce CHARGER_OPTION
		register.

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

	qcom,v-cutoff-uv = <3400000>;
	qcom,max-voltage-uv = <4200000>;
	qcom,r-conn-mohm = <18>;
	qcom,shutdown-soc-valid-limit = <20>;
	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,low-soc-fifo-length = <2>;
	qcom,calculate-soc-ms = <20000>;
	qcom,s3-ocv-tolerence-uv = <1200>;
	qcom,volatge-soc-timeout-ms = <60000>;
	qcom,battery-data = <&mtp_batterydata>;
	qcom,bms-vadc = <&pm8916_vadc>;
	qcom,bms-adc_tm = <&pm8916_adc_tm>;

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

	qcom,qpnp-chg-pres@1208 {
		reg = <0x1108 0x1>;
	}

	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>,

		interrupt-names = "leave_cv",
				  "enter_cv",
				  "good_ocv",
				  "ocv_thr",
				  "fifo_updtaed",
				  "fsm_state_change";
	};
};