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,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,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,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 { spmi-dev-container; 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>; }; };