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

Qualcomm Techonologies, 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".

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

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