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: Definition: Should be "qcom,fg-gen3". - qcom,pmic-revid Usage: required Value type: 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: Definition: For details about IIO bindings see: Documentation/devicetree/bindings/iio/iio-bindings.txt - #thermal-sensor-cells: Should be 0. See thermal.txt for a description. - qcom,rradc-base Usage: required Value type: Definition: Should specify the base address of RR_ADC peripheral. This is used for reading certain peripheral registers under it. - qcom,fg-cutoff-voltage Usage: optional Value type: 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: 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: Definition: The voltage threshold (in mV) which upon set will be used for configuring the low battery voltage threshold. - qcom,fg-recharge-voltage Usage: optional Value type: Definition: The voltage threshold (in mV) based on which the charging will be resumed once the charging is complete. If this property is not specified, then the default value will be 4250mV. - qcom,fg-chg-term-current Usage: optional Value type: 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: 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-chg-term-base-current Usage: optional Value type: Definition: Battery current (in mA) upper boundary at which the fuel gauge will issue an end of charge during discharging. If this property is not specified, then the default value used will be 75mA. - qcom,fg-cutoff-current Usage: optional Value type: Definition: Minimum Battery current (in mA) used for cutoff SOC estimate. If this property is not specified, then a default value of 500 mA will be applied. - qcom,fg-delta-soc-thr Usage: optional Value type: Definition: Percentage of SOC increase upon which the delta monotonic & battery SOC interrupts 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: 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: Definition: Specifies the source of sense resistor. Allowed values are: 0 - Rsense is from Battery FET 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: 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: Definition: Number of cycles between ESR pulses while the battery is charging. Array of 2 elements if specified. Element 0 - Retry value for timer Element 1 - Maximum value for timer - qcom,fg-esr-timer-awake Usage: optional Value type: Definition: Number of cycles between ESR pulses while the system is awake and the battery is discharging. Array of 2 elements if specified. Element 0 - Retry value for timer Element 1 - Maximum value for timer - qcom,fg-esr-timer-asleep Usage: optional Value type: 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. Array of 2 elements if specified. Element 0 - Retry value for timer Element 1 - Maximum value for timer - qcom,fg-esr-pulse-thresh-ma Usage: optional Value type: Definition: ESR pulse qualification threshold in mA. If this is not specified, a default value of 110 mA will be configured. Allowed values are from 1 to 997. - qcom,fg-esr-meas-curr-ma Usage: optional Value type: Definition: ESR measurement current in mA. If this is not specified, a default value of 120 mA will be configured. Allowed values are 60, 120, 180 and 240. - qcom,cycle-counter-en Usage: optional Value type: Definition: Enables the cycle counter feature. - qcom,fg-force-load-profile Usage: optional Value type: 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: 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: 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: 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: 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: 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: 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: 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,battery-thermal-coefficients Usage: optional Value type: Definition: Byte array of battery thermal coefficients. This should be exactly 3 bytes in length. - qcom,fg-jeita-hyst-temp Usage: optional Value type: 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: 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: Definition: A boolean property that when defined holds SOC at 100% when the battery is full. - qcom,linearize-soc Usage: optional Value type: 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,ki-coeff-soc-dischg Usage: optional Value type: 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: 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: 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. - qcom,ki-coeff-full-dischg Usage: optional Value type: Definition: Ki coefficient full SOC value that will be applied during discharging. If not specified, a value of 0 will be set. Allowed range is from 245 to 62256. - qcom,ki-coeff-low-dischg Usage: optional Value type: Definition: Ki coefficient value for low discharge current during discharging. Value has no unit. Allowed range is 0-62200 in micro units. - qcom,ki-coeff-hi-chg Usage: optional Value type: Definition: Ki coefficient value for high charge current during charging. Value has no unit. Allowed range is 0-62200 in micro units. - qcom,fg-rconn-mohms Usage: optional Value type: Definition: Battery connector resistance (Rconn) in milliohms. If Rconn is specified, then ESR to Rslow scaling factors will be updated to account it for an accurate ESR. - qcom,fg-esr-clamp-mohms Usage: optional Value type: Definition: Equivalent series resistance (ESR) in milliohms. If this is specified, then ESR will be clamped to this value when ESR is found to be dropping below this. Default value is 20. - qcom,fg-esr-filter-switch-temp Usage: optional Value type: Definition: Battery temperature threshold below which low temperature ESR filter coefficients will be switched to normal temperature ESR filter coefficients. If this is not specified, then the default value used will be 100. Unit is in decidegC. - qcom,fg-esr-tight-filter-micro-pct Usage: optional Value type: Definition: Value in micro percentage for ESR tight filter. If this is not specified, then a default value of 3907 (0.39 %) will be used. Lowest possible value is 1954 (0.19 %). - qcom,fg-esr-broad-filter-micro-pct Usage: optional Value type: Definition: Value in micro percentage for ESR broad filter. If this is not specified, then a default value of 99610 (9.96 %) will be used. Lowest possible value is 1954 (0.19 %). - qcom,fg-esr-tight-lt-filter-micro-pct Usage: optional Value type: Definition: Value in micro percentage for low temperature ESR tight filter. If this is not specified, then a default value of 30000 (3 %) will be used. Lowest possible value is 1954 (0.19 %). - qcom,fg-esr-broad-lt-filter-micro-pct Usage: optional Value type: Definition: Value in micro percentage for low temperature ESR broad filter. If this is not specified, then a default value of 30000 (3 %) will be used. Lowest possible value is 1954 (0.19 %). - qcom,fg-esr-rt-filter-switch-temp Usage: optional Value type: Definition: Battery temperature threshold below which ESR relax filter coefficients will be applied after a certain number of delta battery temperature interrupts firing in an interval of time. This will be applied only when Qnovo is enabled. If this is not specified, then the default value used will be -100. Unit is in decidegC. - qcom,fg-esr-tight-rt-filter-micro-pct Usage: optional Value type: Definition: Value in micro percentage for relax temperature ESR tight filter. If this is not specified, then a default value of 5860 will be used. Lowest possible value is 1954 (0.19 %). This will be applied only if Qnovo is enabled. - qcom,fg-esr-broad-rt-filter-micro-pct Usage: optional Value type: Definition: Value in micro percentage for relax temperature ESR broad filter. If this is not specified, then a default value of 156250 will be used. Lowest possible value is 1954 (0.19 %). This will be applied only if Qnovo is enabled. - qcom,fg-auto-recharge-soc Usage: optional Value type: Definition: A boolean property when defined will configure automatic recharge SOC threshold. If not specified, automatic recharge voltage threshold will be configured. This has to be configured in conjunction with the charger side configuration for proper functionality. - qcom,slope-limit-temp-threshold Usage: optional Value type: Definition: Battery temperature threshold to decide when slope limit coefficients should be applied along with charging status. Unit is in decidegC. - qcom,slope-limit-coeffs Usage: optional Value type: Definition: A list of integers which holds the slope limit coefficients in the following order. Allowed size is 4. Possible values are from 0 to 31. Unit is in decipercentage. Element 0 - Low temperature discharging Element 1 - Low temperature charging Element 2 - High temperature discharging Element 3 - High temperature charging These coefficients have to be specified along with the property "qcom,slope-limit-temp-threshold" to make dynamic slope limit adjustment functional. - qcom,fg-bmd-en-delay-ms Usage: optional Value type: Definition: The delay in ms for FG to enable BMD after reading RID. ========================================================== Second Level Nodes - Peripherals managed by FG Gen3 driver ========================================================== - reg Usage: required Value type: Definition: Addresses and sizes for the specified peripheral - interrupts Usage: optional Value type: Definition: Interrupt mapping as per the interrupt encoding - interrupt-names Usage: optional Value type: 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,rradc-base = <0x4500>; qcom,ki-coeff-soc-dischg = <30 60 90>; qcom,ki-coeff-med-dischg = <800 1000 1400>; qcom,ki-coeff-hi-dischg = <1200 1500 2100>; qcom,slope-limit-temp-threshold = <100>; qcom,slope-limit-coeffs = <10 11 12 13>; qcom,battery-thermal-coefficients = [9d 50 ff]; #thermal-sensor-cells = <0>; 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>; }; }; ====================================== Example for thermal zone configuration ====================================== thermal_zones { pmi8998_fg { polling-delay-passive = <200>; polling-delay = <200>; thermal-governor = ; thermal-sensors = <&pmi8998_fg>; pmi8998_fg_trip1: pmi8998-fg-trip0 { temperature = <45000>; hysteresis = <0>; type = "passive"; }; pmi8998_fg_trip2: pmi8998-fg-trip2 { temperature = <50000>; hysteresis = <0>; type = "hot"; }; pmi8998_fg_trip3: pmi8998-fg-trip3 { temperature = <60000>; hysteresis = <0>; type = "alert"; }; }; };