QTI's QPNP PMIC Fuel Gauge Device QPNP PMIC FG provides interface to clients to read properties related to the battery. Its main function is to retrieve 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 FG driver, both implemented as subnodes in the example. These peripherals must not be disabled if the FG device is to enabled: - qcom,fg-soc : The main FG device. Supports battery fuel gauge controls and sensors. - qcom,fg-batt : The FG battery device supports interrupts and controls with respect to the state of the connected battery.For example: the peripheral informs the driver if the battery has been identified by the fuel gauge based on a given battery resistance range. Optionally ADC nodes can be added - qcom,revid-tp-rev: A subnode with a register address for the TP_REV register in the REVID peripheral. This is used to apply workarounds that may depend on the trim program. - qcom,fg-adc-vbat : A subnode with a register address for the FG_ADC_USR peripheral which is used mainly for battery current limiting (BCL). This node maps out the VBAT reading register which allows to have a +/- 32 mV accurate reading of VBAT. - qcom,fg-adc-ibat : A subnode with a register address for the FG_ADC_USR peripheral which is used mainly for battery current limiting (BCL). This node maps out the IBAT current reading register which allows to have a +/- 32 mA accurate reading of IBAT. Parent node required properties: - compatible : should be "qcom,qpnp-fg" for the FG driver. - qcom,pmic-revid : Should specify the phandle of PMIC revid module. This is used to identify the PMIC subtype. Parent node optional properties: - qcom,warm-bat-decidegc: Warm battery temperature in decidegC. - qcom,cool-bat-decidegc: Cool battery temperature in decidegC. - qcom,hot-bat-decidegc: Hot battery temperature in decidegC. - qcom,cold-bat-decidegc: Cold battery temperature in decidegC. - qcom,cold-hot-jeita-hysteresis: A tuple of 2. Index[0] is cold hysteresis and index[1] is hot hysterisis(in decidegC). - qcom,ext-sense-type: Current sense channel used by the FG. Set this to use external rsense. - qcom,thermal-coefficients: Byte array of thermal coefficients for reading battery thermistor. This should be exactly 6 bytes in length. Example: [01 02 03 04 05 06] - qcom,resume-soc: soc to resume charging in percentage. - qcom,resume-soc-raw: soc to resume charging in the scale of [0-255]. This overrides qcom,resume-soc if defined. - qcom,hold-soc-while-full: A boolean property that when defined holds SOC at 100% when the battery is full. - qcom,bcl-lm-threshold-ma: BCL LPM to MPM mode transition threshold in milliAmpere. - qcom,bcl-mh-threshold-ma: BCL MPM to HPM mode transition threshold in milliAmpere. - qcom,use-otp-profile: Specify this flag to avoid RAM loading any battery profile. - qcom,sw-rbias-control: Boolean property which defines whether the Rbias needs to be controlled by software. If this is not set, it will be controlled by hardware (default). - qcom,fg-iterm-ma: Battery current at which the fuel gauge will try to scale 100% towards. When the charge current goes above this, the SoC should be at 100%. - qcom,fg-chg-iterm-ma: Battery current at which the fuel gauge will issue end of charge if the charger is configured to use the fuel gauge ADCs for end of charge detection. This property is in milliamps and should be positive (e.g. 100mA to terminate at -100mA). - qcom,irq-volt-empty-mv: The voltage threshold that the empty soc interrupt will be triggered. When the empty soc interrupt fires, battery soc will be pulled to 0 and the userspace will be notified via the power supply framework. The userspace will read 0% soc and immediately shutdown. - qcom,fg-cutoff-voltage-mv: The voltage 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. - qcom,fg-vbat-estimate-diff-mv: If the estimated voltage based on SoC and battery current/resistance differs from the actual voltage by more than this amount, the fuel gauge will redo the first SoC estimate when the driver probes. - qcom,fg-delta-soc: How many percent the monotonic SoC must change before a new delta_soc interrupt is asserted. If this value is raised above 3-4, some period workarounds may not function well, so it's best to leave this at 1 or 2%. - qcom,fg-vbatt-low-threshold: Voltage (in mV) which upon set will be used for configuring the low battery voltage threshold. Interrupt will be asserted and handled based upon this. If this property is not specified, low battery voltage threshold will be configured to 4200 mV. - qcom,fg-rconn-mohm: Battery connector resistance (Rconn) in milliohms. If Rconn is specified, then Rslow values will be updated to account it for an accurate ESR. - qcom,cycle-counter-en: Boolean property which enables the cycle counter feature. If this property is present, then the following properties to specify low and high soc thresholds should be defined. - qcom,capacity-learning-on: A boolean property to have the fuel gauge driver attempt to learn the battery capacity when charging. Takes precedence over capacity-estimation-on. - qcom,capacity-learning-feedback: A boolean property to have the fuel gauge driver to feedback the learned capacity into the capacity learning algorithm. This has to be used only if the property "qcom,capacity-learning-on" is specified. - qcom,cl-max-increment-deciperc: The maximum percent that the capacity can rise as the result of a single charge cycle. This property corresponds to .1% increments. - qcom,cl-max-decrement-deciperc: The maximum percent that the capacity can fall as the result of a single charge cycle. This property corresponds to .1% decrements. - qcom,cl-max-temp-decidegc: Above this temperature, capacity learning will be canceled. - qcom,cl-mix-temp-decidegc: Below this temperature, capacity learning will be canceled. - qcom,cl-max-start-soc: The battery soc has to be below this value at the start of a charge cycle for capacity learning to be run. - qcom,cl-vbat-est-thr-uv: The maximum difference between the battery voltage shadow and the current predicted voltage in uV to initiate capacity learning. - qcom,cl-max-limit-deciperc: The maximum percent that the capacity cannot go above during any capacity learning cycle. This property is in the unit of .1% increments. - qcom,cl-min-limit-deciperc: The minimum percent that the capacity cannot go below during any capacity learning cycle. This property is in the unit of .1% increments. - qcom,capacity-estimation-on: A boolean property to have the fuel gauge driver attempt to estimate the battery capacity using battery resistance. - qcom,aging-eval-current-ma: Current used to evaluate battery aging. This value should be around the steady state current drawn from the battery when the phone is low on battery. - qcom,fg-cc-cv-threshold-mv: Voltage threshold in mV for configuring constant charge (CC) to constant voltage (CV) setpoint in FG upon which the battery EOC status will be determined. This value should be 10 mV less than the float voltage configured in the charger. This property should only be specified if "qcom,autoadjust-vfloat" property is specified in the charger driver to ensure a proper operation. - qcom,bad-battery-detection-enable: A boolean property to enable the fuel gauge driver to detect the damaged battery when the safety-timer expires by using the coulomb count. - qcom,fg-therm-delay-us: The time in microseconds to delay battery thermistor biasing. - qcom,esr-pulse-tuning-en: A boolean property to enable ESR pulse tuning feature. If this is enabled, ESR pulse extraction will be disabled when state of charge (SOC) is less than 2%. It will be enabled back when SOC gets above 2%. In addition, for SOC between 2% and 5%, ESR pulse timing settings will be different from default. Once SOC crosses 5%, ESR pulse timings will be restored back to default. - qcom,fg-control-slope-limiter: A boolean property to specify if SOC slope limiter coefficients needs to be modified based on charging status and battery temperature threshold. - qcom,fg-slope-limit-temp-threshold: Temperature threshold in decidegC used for applying the slope coefficient based on charging status and battery temperature. If this property is not specified, a default value of 100 (10C) will be applied by default. - qcom,fg-slope-limit-low-temp-chg: When the temperature goes below the specified temperature threshold and battery is charging, slope coefficient specified with this property will be applied. If this property is not specified, a default value of 45 will be applied. - qcom,fg-slope-limit-low-temp-dischg: Same as "qcom,fg-slope-limit-low-temp-chg" except this is when the battery is discharging. - qcom,fg-slope-limit-high-temp-chg: When the temperature goes above the specified temperature threshold and battery is charging, slope coefficient specified with this property will be applied. If this property is not specified, a default value of 2 will be applied. - qcom,fg-slope-limit-high-temp-dischg: Same as "qcom,fg-slope-limit-high-temp-chg" except this is when the battery is discharging. - qcom,fg-dischg-voltage-gain-ctrl: A boolean property to specify if the voltage gain needs to be modified during discharging based on monotonic soc. - qcom,fg-dischg-voltage-gain-soc: Array of monotonic SOC threshold values to change the voltage gain settings during discharge. This should be defined in the ascending order and in the range of 0-100. Array limit is set to 3. If qcom,fg-dischg-voltage-gain-ctrl is set, then this property should be specified to apply the gain settings. - qcom,fg-dischg-med-voltage-gain: Array of voltage gain values that needs to be applied to medC voltage gain when the monotonic SOC goes below the SOC threshold specified under qcom,fg-dischg-voltage-gain-soc. Array limit is set to 3. If qcom,fg-dischg-voltage-gain-ctrl is set, then this property should be specified to apply the gain setting. - qcom,fg-dischg-high-voltage-gain: Array of voltage gain values that needs to be applied to highC voltage gain when the monotonic SOC goes below the SOC threshold specified under qcom,fg-dischg-voltage-gain-soc. Array limit is set to 3. If qcom,fg-dischg-voltage-gain-ctrl is set, then this property should be specified to apply the gain setting. - qcom,fg-use-vbat-low-empty-soc: A boolean property to specify whether vbatt-low interrupt is used to handle empty battery condition. If this is not specified, empty battery condition is detected by empty-soc interrupt. - qcom,fg-batt-temp-low-limit: Battery temperature (in decidegC) low limit which will be used to validate the battery temperature reading from FG. If the battery temperature goes below this limit, last read good temperature will be notified to userspace. If this limit is not specified, then the default limit would be -60C. - qcom,fg-batt-temp-high-limit: Battery temperature (in decidegC) high limit which will be used to validate the battery temperature reading from FG. If the battery temperature goes above this limit, last read good temperature will be notified to userspace. If this limit is not specified, then the default limit would be 150C. - qcom,fg-cc-soc-limit-pct: Percentage of CC_SOC before resetting FG and restore the full CC_SOC value. - qcom,fg-restore-batt-info: A boolean property to specify whether battery parameters needs to be restored. If this feature is enabled, then validating the battery parameters by OCV/battery SOC, validation range in percentage should be specified via appropriate module parameters to make it work properly. qcom,fg-soc node required properties: - reg : offset and length of the PMIC peripheral register map. - interrupts : the interrupt mappings. The format should be . - interrupt-names : names for the mapped fg soc interrupts The following interrupts are required: 0: high-soc 1: low-soc 2: full-soc 3: empty-soc 4: delta-soc 5: first-est-done 6: sw-fallbk-ocv 7: sw-fallbk-new-batt qcom,fg-memif node required properties: - reg : offset and length of the PMIC peripheral register map. - interrupts : the interrupt mappings. The format should be . - interrupt-names : names for the mapped fg adc interrupts The following interrupts are required: 0: mem-avail Example: pmi8994_fg: qcom,fg { compatible = "qcom,qpnp-fg"; #address-cells = <1>; #size-cells = <1>; status = "disabled"; qcom,pmic-revid = <&pmi8994_revid>; qcom,fg-soc@4000 { reg = <0x4000 0x100>; interrupts = <0x2 0x40 0x0>, <0x2 0x40 0x1>, <0x2 0x40 0x2>, <0x2 0x40 0x3>, <0x2 0x40 0x4>, <0x2 0x40 0x5>, <0x2 0x40 0x6>, <0x2 0x40 0x7>; interrupt-names = "high-soc", "low-soc", "full-soc", "empty-soc", "delta-soc", "first-est-done", "sw-fallbk-ocv", "sw-fallbk-new-batt"; }; qcom,fg-batt@4100 { reg = <0x4100 0x100>; interrupts = <0x2 0x41 0x0>, <0x2 0x41 0x1>, <0x2 0x41 0x2>, <0x2 0x41 0x3>, <0x2 0x41 0x4>, <0x2 0x41 0x5>, <0x2 0x41 0x6>, <0x2 0x41 0x7>; interrupt-names = "soft-cold", "soft-hot", "vbatt-low", "batt-ided", "batt-id-req", "batt-unknown", "batt-missing", "batt-match"; }; qcom,fg-adc-vbat@4254 { reg = <0x4254 0x1>; }; qcom,fg-adc-ibat@4255 { reg = <0x4255 0x1>; }; qcom,fg-memif@4400 { reg = <0x4400 0x100>; interrupts = <0x2 0x44 0x0>, <0x2 0x44 0x1>; interrupt-names = "mem-avail", "data-rcvry-sug"; qcom,cold-hot-jeita-hysteresis = <30 50>; }; };