Documentation/devicetree/bindings/power/qcom-charger/qpnp-fg-gen3.txt

Qualcomm Techonologies, Inc. QPNP PMIC Fuel Gauge Gen3 Device

QPNP PMIC FG Gen3 device provides interface to the clients to read properties
related to the battery. Its main function is to retrieve the State of Charge
(SOC), in percentage scale representing the amount of charge left in the
battery.

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

FG Gen3 device must be described in two levels of device nodes.  The first
level describes the FG Gen3 device.  The second level describes one or more
peripherals managed by FG Gen3 driver. All the peripheral specific parameters
such as base address, interrupts etc., should be under second level node.

====================================
First Level Node - FG Gen3 device
====================================

- compatible
	Usage:      required
	Value type: <string>
	Definition: Should be "qcom,fg-gen3".

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

- io-channels
- io-channel-names
	Usage:      required
	Value type: <phandle>
	Definition: For details about IIO bindings see:
		    Documentation/devicetree/bindings/iio/iio-bindings.txt

- qcom,fg-cutoff-voltage
	Usage:      optional
	Value type: <u32>
	Definition: The voltage (in mV) where the fuel gauge will steer the SOC
		    to be zero. For example, if the cutoff voltage is set to
		    3400mv, the fuel gauge will try to count SoC so that the
		    battery SOC will be 0 when it is 3400mV. If this property
		    is not specified, then the default value used will be
		    3200mV.

- qcom,fg-empty-voltage
	Usage:      optional
	Value type: <u32>
	Definition: The voltage threshold (in mV) based on which the empty soc
		    interrupt will be triggered. When the empty soc interrupt
		    fires, battery soc will be set to 0 and the userspace will
		    be notified via the power supply framework. The userspace
		    will read 0% soc and immediately shutdown. If this property
		    is not specified, then the default value used will be
		    2800mV.

- qcom,fg-vbatt-low-thr
	Usage:      optional
	Value type: <u32>
	Definition: The voltage threshold (in mV) which upon set will be used
		    for configuring the low battery voltage threshold.

- qcom,fg-chg-term-current
	Usage:      optional
	Value type: <u32>
	Definition: Battery current (in mA) at which the fuel gauge will issue
		    an end of charge if the charger is configured to use the
		    fuel gauge ADC for end of charge detection. If this
		    property is not specified, then the default value used
		    will be 100mA.

- qcom,fg-sys-term-current
	Usage:      optional
	Value type: <u32>
	Definition: Battery current (in mA) at which the fuel gauge will try to
		    scale towards 100%. When the charge current goes above this
		    the SOC should be at 100%. If this property is not
		    specified, then the default value used will be -125mA.
		    This value has to be specified in negative values for
		    the charging current.

- qcom,fg-delta-soc-thr
	Usage:      optional
	Value type: <u32>
	Definition: Percentage of monotonic SOC increase upon which the delta
		    SOC interrupt will be triggered. If this property is not
		    specified, then the default value will be 1. Possible
		    values are in the range of 0 to 12.

- qcom,fg-recharge-soc-thr
	Usage:      optional
	Value type: <u32>
	Definition: Percentage of monotonic SOC upon which the charging will
		    will be resumed once the charging is complete. If this
		    property is not specified, then the default value will be
		    95.

- qcom,fg-rsense-sel
	Usage:      optional
	Value type: <u32>
	Definition: Specifies the source of sense resistor.
		    Allowed values are:
		    0 - Rsense is from Battery FET
		    1 - Rsense is external
		    2 - Rsense is Battery FET and SMB
		    Option 2 can be used only when a parallel charger is
		    present. If this property is not specified, then the
		    default value will be 2.

- qcom,fg-jeita-thresholds
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: A list of integers which holds the jeita thresholds (degC)
		    in the following order. Allowed size is 4.
		    Element 0 - JEITA cold threshold
		    Element 1 - JEITA cool threshold
		    Element 2 - JEITA warm threshold
		    Element 3 - JEITA hot threshold
		    If these parameters are not specified, then the default
		    values used will be 0, 5, 45, 50.

- qcom,fg-esr-timer-charging
	Usage:      optional
	Value type: <u32>
	Definition: Number of cycles between ESR pulses while the battery is
		    charging.

- qcom,fg-esr-timer-awake
	Usage:      optional
	Value type: <u32>
	Definition: Number of cycles between ESR pulses while the system is
		    awake and the battery is discharging.

- qcom,fg-esr-timer-asleep
	Usage:      optional
	Value type: <u32>
	Definition: Number of cycles between ESR pulses while the system is
		    asleep and the battery is discharging. This option requires
		    qcom,fg-esr-timer-awake to be defined.

- qcom,cycle-counter-en
	Usage:      optional
	Value type: <bool>
	Definition: Enables the cycle counter feature.

- qcom,fg-force-load-profile
	Usage:      optional
	Value type: <bool>
	Definition: If set, battery profile will be force loaded if the profile
		    loaded earlier by bootloader doesn't match with the profile
		    available in the device tree.

- qcom,cl-start-capacity
	Usage:      optional
	Value type: <u32>
	Definition: Battery SOC threshold to start the capacity learning.
		    If this is not specified, then the default value used
		    will be 15.

- 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. 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 450 (45C). 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,fg-jeita-hyst-temp
	Usage:      optional
	Value type: <u32>
	Definition: Hysteresis applied to Jeita temperature comparison.
		    Possible values are:
			0 - No hysteresis
			1,2,3 - Value in Celsius.

- qcom,fg-batt-temp-delta
	Usage:      optional
	Value type: <u32>
	Definition: Battery temperature delta interrupt threshold. Possible
		    values are: 2, 4, 6 and 10. Unit is in Kelvin.

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

- qcom,ki-coeff-soc-dischg:
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: Array of monotonic SOC threshold values to change the ki
		    coefficient for medium discharge current during discharge.
		    This should be defined in the ascending order and in the
		    range of 0-100. Array limit is set to 3.

- qcom,ki-coeff-med-dischg:
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: Array of ki coefficient values for medium discharge current
		    during discharge. These values will be applied when the
		    monotonic SOC goes below the SOC threshold specified under
		    qcom,ki-coeff-soc-dischg. Array limit is set to 3. This
		    property should be specified if qcom,ki-coeff-soc-dischg
		    is specified to make it fully functional. Value has no
		    unit. Allowed range is 0 to 62200 in micro units.

- qcom,ki-coeff-hi-dischg:
	Usage:      optional
	Value type: <prop-encoded-array>
	Definition: Array of ki coefficient values for high discharge current
		    during discharge. These values will be applied when the
		    monotonic SOC goes below the SOC threshold specified under
		    qcom,ki-coeff-soc-dischg. Array limit is set to 3. This
		    property should be specified if qcom,ki-coeff-soc-dischg
		    is specified to make it fully functional. Value has no
		    unit. Allowed range is 0 to 62200 in micro units.

==========================================================
Second Level Nodes - Peripherals managed by FG Gen3 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
========

pmi8998_fg: qpnp,fg {
	compatible = "qcom,fg-gen3";
	#address-cells = <1>;
	#size-cells = <1>;
	qcom,pmic-revid = <&pmi8998_revid>;
	io-channels = <&pmi8998_rradc 3>;
	io-channel-names = "rradc_batt_id";
	qcom,ki-coeff-soc-dischg = <30 60 90>;
	qcom,ki-coeff-med-dischg = <800 1000 1400>;
	qcom,ki-coeff-hi-dischg = <1200 1500 2100>;
	status = "okay";

	qcom,fg-batt-soc@4000 {
		status = "okay";
		reg = <0x4000 0x100>;
		interrupts = <0x2 0x40 0x0 IRQ_TYPE_EDGE_BOTH>,
			     <0x2 0x40 0x1 IRQ_TYPE_EDGE_BOTH>,
			     <0x2 0x40 0x2 IRQ_TYPE_EDGE_BOTH>,
			     <0x2 0x40 0x3 IRQ_TYPE_EDGE_BOTH>;
		interrupt-names = "soc-update",
				  "soc-ready",
				  "bsoc-delta",
				  "msoc-delta";

	};

	qcom,fg-batt-info@4100 {
		status = "okay";
		reg = <0x4100 0x100>;
		interrupts = <0x2 0x41 0x3 IRQ_TYPE_EDGE_BOTH>;
		interrupt-names = "batt-missing";
	};

	qcom,fg-memif@4400 {
		status = "okay";
		reg = <0x4400 0x100>;
	};
};