dt-bindings: Add snapshot of QPNP QG devicetree bindings (3541d4b4) · Commits · e / devices / android_kernel_fairphone_FP5

bindings/power/supply/qcom/qpnp-qg.txt

0 → 100644

+506 −0

Original line number	Diff line number	Diff line
		Qualcomm Technologies, Inc. QPNP PMIC QGAUGE (QG) Device

		QPNP PMIC QGAUGE device provides the ability to gauge the State-of-Charge
		of the battery. It provides an interface to the clients to read various
		battery related parameters.

		=======================
		Required Node Structure
		=======================

		Qgauge device must be described in two level of nodes. The first level
		describes the properties of the Qgauge device and the second level
		describes the peripherals managed/used of the module.

		====================================
		First Level Node - QGAUGE device
		====================================

		- compatible
		Usage: required
		Value type: <string>
		Definition: Should be "qcom,qpnp-qg" or "qcom,qpnp-qg-lite".

		- qcom,pmic-revid
		Usage: required
		Value type: <phandle>
		Definition: Should specify the phandle of PMIC revid module. This is
		used to identify the PMIC subtype.

		- qcom,qg-vadc
		Usage: required
		Value type: <phandle>
		Definition: Phandle for the VADC node, it is used for BATT_ID and
		BATT_THERM readings.

		- qcom,vbatt-empty-mv
		Usage: optional
		Value type: <u32>
		Definition: The battery voltage threshold (in mV) at which the
		vbatt-empty interrupt fires. The SOC is forced to 0
		when this interrupt fires. If not specified, the
		default value is 3200 mV.

		- qcom,vbatt-empty-cold-mv
		Usage: optional
		Value type: <u32>
		Definition: The battery voltage threshold (in mV) at which the
		vbatt-empty interrupt fires. This threshold is only
		applied at cold temperature specified by
		'qcom,cold-temp-threshold'. The SOC is forced to 0
		when this interrupt fires. If not specified, the
		default value is 3000 mV.

		- qcom,vbatt-cutoff-mv
		Usage: optional
		Value type: <u32>
		Definition: The battery voltage threshold (in mV) at which the
		the Qgauge algorithm converges to 0 SOC. If not specified
		the default value is 3400 mV.

		- qcom,vbatt-low-mv
		Usage: optional
		Value type: <u32>
		Definition: The battery voltage threshold (in mV) at which the
		the VBAT_LOW interrupt fires. Software can take necessary
		the action when this interrupt fires. If not specified
		the default value is 3500 mV.

		- qcom,vbatt-low-cold-mv
		Usage: optional
		Value type: <u32>
		Definition: The battery voltage threshold (in mV) at which the
		the VBAT_LOW interrupt fires. The threshold is only
		applied at cold temperature specified by
		'qcom,cold-temp-threshold'. Software can take necessary
		the action when this interrupt fires. If not specified
		the default value is 3800 mV.

		- qcom,qg-iterm-ma
		Usage: optional
		Value type: <u32>
		Definition: The battery current (in mA) at which the the QG algorithm
		converges the SOC to 100% during charging and can be used to
		terminate charging. If not specified, the default value is
		100mA.

		- qcom,delta-soc
		Usage: optional
		Value type: <u32>
		Definition: The SOC percentage increase at which the SOC is
		periodically reported to the userspace. If not specified,
		the value defaults to 1%.

		- qcom,s2-fifo-length
		Usage: optional
		Value type: <u32>
		Definition: The total number if FIFO samples which need to be filled up
		in S2 state of QG to fire the FIFO DONE interrupt.
		Minimum value = 1 Maximum Value = 8. If not specified,
		the default value is 5.

		- qcom,s2-acc-length
		Usage: optional
		Value type: <u32>
		Definition: The number of distinct V & I samples to be accumulated
		in each FIFO in the S2 state of QG.
		Minimum Value = 0 Maximum Value = 256. If not specified,
		the default value is 128.

		- qcom,s2-acc-interval-ms
		Usage: optional
		Value type: <u32>
		Definition: The time (in ms) between each of the V & I samples being
		accumulated in FIFO.
		Minimum Value = 0 ms Maximum Value = 2550 ms. If not
		specified the default value is 100 ms.

		- qcom,ocv-timer-expiry-min
		Usage: optional
		Value type: <u32>
		Definition: The maximum time (in minutes) for the QG to transition from
		S3 to S2 state.
		Minimum Value = 2 min Maximum Value = 30 min. If not
		specified the hardware default is set to 14 min.

		- qcom,ocv-tol-threshold-uv
		Usage: optional
		Value type: <u32>
		Definition: The OCV detection error tolerance (in uV). The maximum
		voltage allowed between 2 VBATT readings in the S3 state
		to qualify for a valid OCV.
		Minimum Value = 0 uV Maximum Value = 12262 uV Step = 195 uV

		- qcom,s3-entry-fifo-length
		Usage: optional
		Value type: <u32>
		Definition: The minimum number if FIFO samples which have to qualify the
		S3 IBAT entry threshold (qcom,s3-entry-ibat-ua) for QG
		to enter into S3 state.
		Minimum Value = 1 Maximum Value = 8. The hardware default
		is configured to 3.

		- qcom,s3-entry-ibat-ua
		Usage: optional
		Value type: <u32>
		Definition: The battery current (in uA) for the QG to enter into the S3
		state. The QG algorithm enters into S3 if the battery
		current is lower than this threshold consecutive for
		the FIFO length specified in 'qcom,s3-entry-fifo-length'.
		Minimum Value = 0 uA Maximum Value = 155550 uA
		Step = 610 uA.

		- qcom,s3-exit-ibat-ua
		Usage: optional
		Value type: <u32>
		Definition: The battery current (in uA) for the QG to exit S3 state.
		If the battery current is higher than this threshold QG
		exists S3 state.
		Minimum Value = 0 uA Maximum Value = 155550 uA
		Step = 610 uA.

		- qcom,rbat-conn-mohm
		Usage: optional
		Value type: <u32>
		Definition: Resistance of the battery connectors in mOhms.

		- qcom,ignore-shutdown-soc-secs
		Usage: optional
		Value type: <u32>
		Definition: Time in seconds beyond which shutdown SOC is ignored.
		If not specified the default value is 360 secs.

		- qcom,hold-soc-while-full
		Usage: optional
		Value type: <empty>
		Definition: A boolean property that when defined holds SOC at 100% when
		the battery is full until recharge starts.

		- qcom,linearize-soc
		Usage: optional
		Value type: <empty>
		Definition: A boolean property that when defined linearizes SOC when
		the SOC drops after charge termination monotonically to
		improve the user experience. This is applicable only if
		"qcom,hold-soc-while-full" is specified.

		- qcom,cold-temp-threshold
		Usage: optional
		Value type: <u32>
		Definition: Temperature threshold in decidegree at which the low
		temperature specific configuration as applied. If not
		specified, the default value is 0 degree centigrade.

		- qcom,cl-disable
		Usage: optional
		Value type: <empty>
		Definition: A boolean property to disable the battery capacity
		learning when charging.

		- qcom,cl-feedback-on
		Usage: optional
		Value type: <empty>
		Definition: A boolean property to feedback the learned capacity into
		the capacity lerning algorithm. This has to be used only if the
		property "qcom,cl-disable" is not specified.

		- qcom,cl-max-start-soc
		Usage: optional
		Value type: <u32>
		Definition: Battery SOC has to be below or equal to this value at the
		start of a charge cycle to start the capacity learning.
		If this is not specified, then the default value used
		will be 15. Unit is in percentage.

		- qcom,cl-min-start-soc
		Usage: optional
		Value type: <u32>
		Definition: Battery SOC has to be above or equal to this value at the
		start of a charge cycle to start the capacity learning.
		If this is not specified, then the default value used
		will be 10. Unit is in percentage.

		- qcom,cl-min-temp
		Usage: optional
		Value type: <u32>
		Definition: Lower limit of battery temperature to start the capacity
		learning. If this is not specified, then the default value
		used will be 150 (15 C). Unit is in decidegC.

		- qcom,cl-max-temp
		Usage: optional
		Value type: <u32>
		Definition: Upper limit of battery temperature to start the capacity
		learning. If this is not specified, then the default value
		used will be 500 (50 C). Unit is in decidegC.

		- qcom,cl-max-increment
		Usage: optional
		Value type: <u32>
		Definition: Maximum capacity increment allowed per capacity learning
		cycle. If this is not specified, then the default value
		used will be 5 (0.5%). Unit is in decipercentage.

		- qcom,cl-max-decrement
		Usage: optional
		Value type: <u32>
		Definition: Maximum capacity decrement allowed per capacity learning
		cycle. If this is not specified, then the default value
		used will be 100 (10%). Unit is in decipercentage.

		- qcom,cl-min-limit
		Usage: optional
		Value type: <u32>
		Definition: Minimum limit that the capacity cannot go below in a
		capacity learning cycle. If this is not specified, then
		the default value is 0. Unit is in decipercentage.

		- qcom,cl-max-limit
		Usage: optional
		Value type: <u32>
		Definition: Maximum limit that the capacity cannot go above in a
		capacity learning cycle. If this is not specified, then
		the default value is 0. Unit is in decipercentage.

		- qcom,cl-min-delta-batt-soc
		Usage: optional
		Value type: <u32>
		Definition: Minimum change in battery SOC to qualify for capacity
		learning. If this is not specified, then the default
		value is 10. Unit is in percentage.

		- qcom,cl-wt-enable
		Usage: optional
		Value type: <bool>
		Definition: A boolean property to enable weighted capacity learning
		based on change in battery SOC during a charging cycle.
		If this is specified, then "qcom,cl-min-start-soc" and
		"qcom,cl-max-start-soc" is not used.

		- qcom,esr-disable
		Usage: optional
		Value type: <bool>
		Definition: Boolean property to disable ESR estimation. If not defined
		ESR estimation stays enabled for charge-cycles.

		- qcom,esr-discharge-enable
		Usage: optional
		Value type: <bool>
		Definition: Boolean property to enable ESR estimation during discharge.
		Only valid if 'qcom,esr-disable' is not defined.

		- qcom,esr-qual-current-ua
		Usage: optional
		Value type: <u32>
		Definition: Minimum current differential in uA to qualify an ESR
		reading as valid. If not defined the value defaults
		to 130mA.

		- qcom,esr-qual-vbatt-uv
		Usage: optional
		Value type: <u32>
		Definition: Minimum vbatt differential in uV to qualify an ESR
		reading as valid. If not defined the value defaults
		to 7mV.

		- qcom,esr-disable-soc
		Usage: optional
		Value type: <u32>
		Definition: Minimum battery SOC below which ESR will not be
		attempted by QG. If not defined the value defaults
		to 10%.

		- qcom,esr-chg-min-ibat-ua
		Usage: optional
		Value type: <int>
		Definition: Minimun charge current (IBAT) in uA at which ESR will
		be attempted. If not specified the default value is
		in -450mA.

		- qcom,qg-ext-sns
		Usage: optional
		Value type: <bool>
		Definition: Boolean property to support external-rsense based
		configuration.

		- qcom,shutdown-temp-diff
		Usage: optional
		Value type: <u32>
		Definition: The allowed battery temperature in deci-degree difference
		between shutdown and power-on to continue with the shutdown
		SOC. If not specified the default value is 6 degrees C (60).

		- qcom,shutdown-soc-threshold
		Usage: optional
		Value type: <u32>
		Definition: The SOC difference allowed between PON and SHUTDOWN SOC
		for the shutdown SOC to be used. If the difference is
		beyond this value the PON SOC is used.

		- qcom,qg-use-s7-ocv
		Usage: optional
		Value type: <bool>
		Definition: Boolean property to use S7 for PON OCV.

		- qcom,min-sleep-time-secs
		Usage: optional
		Value type: <u32>
		Definition: The minimum sleep time in secs to allow a SOC
		jump if there has been a GOOD_OCV.

		- qcom,qg-sys-min-voltage
		Usage: optional
		Value type: <u32>
		Definition: The voltage threshold (in mV) which describes the system
		minimum voltage as per the hardware recommendation. This
		is not used for any configuration but only for calculating
		the available power. If this property is not specified,
		then the default value used is 2800 mV.

		- qcom,qg-sleep-config
		Usage: optional
		Value type: bool
		Definition: Enables sleep-state configurtion for QG. This
		allows configuring the FIFO length, accumulator
		interval and the accumulator length when system
		enters sleep.

		- qcom,sleep-s2-fifo-length
		Usage: optional
		Value type: <u32>
		Definition: The FIFO length to be applied when system enters sleep
		while discharging. Takes effect only if
		'qcom,qg-sleep-config' is enabled. the default value
		if not specified is 8.

		- qcom,sleep-s2-acc-length
		Usage: optional
		Value type: <u32>
		Definition: The accululator length to be applied when system
		enters sleep while discharging. Takes effect only if
		'qcom,qg-sleep-config' is enabled. the default value
		if not specified is 256.

		- qcom,sleep-s2-acc-intvl-ms
		Usage: optional
		Value type: <u32>
		Definition: The accululator count to be applied when system
		enters sleep while discharging. Takes effect only if
		'qcom,qg-sleep-config' is enabled. the default value
		if not specified is 200ms.

		- qcom,qg-fast-chg-config
		Usage: optional
		Value type: bool
		Definition: Enables fast-charge configurtion for QG. This
		allows configuring the FIFO length during
		fast charge.

		- qcom,fast-chg-s2-fifo-length
		Usage: optional
		Value type: <u32>
		Definition: The FIFO length to be applied when system enters
		fast-chargging. Takes effect only if
		'qcom,qg-fast-chg-config' is enabled. The
		default value if not specified is 1.

		- qcom,fvss-enable
		Usage: optional
		Value type: bool
		Definition: Enable Filtered Voltage based SOC scaling.
		This logic enables SOC scaling to report
		0 at the cutoff voltage.

		- qcom,fvss-vbatt-mv
		Usage: optional
		Value type: <u32>
		Definition: Battery voltage threshold at which FVSS is
		enabled. Applicable only if 'qcom,fvss-enable'
		is set.

		- qcom,multi-profile-load
		Usage: optional
		Value type: <bool>
		Definition: A boolean property that when specified indicates that
		multiple profile loading needs to be enabled. This requires
		multiple battery profiles to be specified for a battery for
		proper functionality.

		- qcom,tcss-enable
		Usage: optional
		Value type: bool
		Definition: Enable Termination current based SOC scaling.
		This logic enables SOC scaling to report
		100% at the QG termination current defined by
		qcom,qg-iterm-ma.

		- qcom,tcss-entry-soc
		Usage: optional
		Value type: <u32>
		Definition: SOC threshold at which TCSS starts. The default
		value is 90%. This property is valid only if
		qcom,tcss-enable is defined.

		- qcom,bass-enable
		Usage: optional
		Value type: bool
		Definition: Enable Battery SOC based SOC scaling. This logic
		allows monotonic-SOC scaling at low-temperatures
		when there is variation in system-SOC due to
		changes in the load.

		==========================================================
		Second Level Nodes - Peripherals managed by QGAUGE driver
		==========================================================
		- reg
		Usage: required
		Value type: <prop-encoded-array>
		Definition: Addresses and sizes for the specified peripheral

		- interrupts
		Usage: optional
		Value type: <prop-encoded-array>
		Definition: Interrupt mapping as per the interrupt encoding

		- interrupt-names
		Usage: optional
		Value type: <stringlist>
		Definition: Interrupt names. This list must match up 1-to-1 with the
		interrupts specified in the 'interrupts' property.

		========
		Example
		========

		pmi632_qg: qpnp,qg {
		compatible = "qcom,qpnp-qg";
		qcom,pmic-revid = <&pmi632_revid>;
		qcom,qg-vadc = <&pmi632_vadc>;
		qcom,vbatt-empty-mv = <3200>;
		qcom,vbatt-low-mv = <3500>;
		qcom,vbatt-cutoff-mv = <3400>;
		qcom,qg-iterm-ma = <100>;

		qcom,qgauge@4800 {
		status = "okay";
		reg = <0x4800 0x100>;
		interrupts = <0x2 0x48 0x0 IRQ_TYPE_EDGE_BOTH>,
		<0x2 0x48 0x1 IRQ_TYPE_EDGE_BOTH>,
		<0x2 0x48 0x2 IRQ_TYPE_EDGE_BOTH>,
		<0x2 0x48 0x4 IRQ_TYPE_EDGE_BOTH>,
		<0x2 0x48 0x5 IRQ_TYPE_EDGE_BOTH>,
		<0x2 0x48 0x6 IRQ_TYPE_EDGE_BOTH>;
		interrupt-names = "qg-batt-missing",
		"qg-vbat-low",
		"qg-vbat-empty",
		"qg-fifo-done",
		"qg-good-ocv",
		"qg-fsm-state-chg",
		"qg-event";
		};

		qcom,qg-sdam@b000 {
		status = "okay";
		reg = <0xb000 0x100>;
		};
		};