585 lines
20 KiB
Text
585 lines
20 KiB
Text
Qualcomm Technologies, 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
|
|
|
|
- #thermal-sensor-cells: Should be 0. See thermal.txt for a description.
|
|
|
|
- qcom,rradc-base
|
|
Usage: required
|
|
Value type: <u32>
|
|
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: <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-recharge-voltage
|
|
Usage: optional
|
|
Value type: <u32>
|
|
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: <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-chg-term-base-current
|
|
Usage: optional
|
|
Value type: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <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
|
|
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: <prop-encoded-array>
|
|
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: <prop-encoded-array>
|
|
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: <prop-encoded-array>
|
|
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-timer-shutdown
|
|
Usage: optional
|
|
Value type: <prop-encoded-array>
|
|
Definition: Number of cycles between ESR pulses at/after shutdwon.This is
|
|
defined when TWM (traditional watch mode) is supported.
|
|
Element 0 - Retry value for timer
|
|
Element 1 - Maximum value for timer
|
|
|
|
- qcom,fg-esr-pulse-thresh-ma
|
|
Usage: optional
|
|
Value type: <u32>
|
|
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: <u32>
|
|
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: <empty>
|
|
Definition: Enables the cycle counter feature.
|
|
|
|
- qcom,fg-force-load-profile
|
|
Usage: optional
|
|
Value type: <empty>
|
|
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 (15 C). 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 500 (50 C). 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,battery-thermal-coefficients
|
|
Usage: optional
|
|
Value type: <u8>
|
|
Definition: Byte array of battery thermal coefficients.
|
|
This should be exactly 3 bytes in length.
|
|
|
|
- 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: <empty>
|
|
Definition: A boolean property that when defined holds SOC at 100% when
|
|
the battery is full.
|
|
|
|
- qcom,linearize-soc
|
|
Usage: optional
|
|
Value type: <empty>
|
|
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: <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-low-dischg
|
|
Usage: optional
|
|
Value type: <prop-encoded-array>
|
|
Definition: Array of ki coefficient values for low 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-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.
|
|
|
|
- qcom,ki-coeff-full-dischg
|
|
Usage: optional
|
|
Value type: <u32>
|
|
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-hi-chg
|
|
Usage: optional
|
|
Value type: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <u32>
|
|
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: <empty>
|
|
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: <u32>
|
|
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: <prop-encoded-array>
|
|
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: <u32>
|
|
Definition: The delay in ms for FG to enable BMD after reading RID.
|
|
|
|
- qcom,fg-use-sw-esr
|
|
Usage: optional
|
|
Value type: <empty>
|
|
Definition: A boolean property when defined uses software based
|
|
ESR during charging.
|
|
|
|
- qcom,fg-disable-esr-pull-dn
|
|
Usage: optional
|
|
Value type: <empty>
|
|
Definition: A boolean property which disables ESR pull-down.
|
|
This is to be used for debug purposes only.
|
|
|
|
- qcom,fg-sync-sleep-threshold-ma
|
|
Usage: optional
|
|
Value type: <u32>
|
|
Definition: The minimum battery current for FG to enter into sync-sleep.
|
|
|
|
- qcom,fg-disable-in-twm
|
|
Usage: optional
|
|
Value type: <empty>
|
|
Definition: A boolean property which disables FG during TWM entry.
|
|
|
|
==========================================================
|
|
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,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 = <userspace>;
|
|
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";
|
|
};
|
|
};
|
|
};
|