| 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,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-soc node required properties: |
| - reg : offset and length of the PMIC peripheral register map. |
| - interrupts : the interrupt mappings. |
| The format should be |
| <slave-id peripheral-id interrupt-number>. |
| - 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 |
| <slave-id peripheral-id interrupt-number>. |
| - 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>; |
| }; |
| }; |