Subbaraman Narayanamurthy | 6accb26 | 2016-03-14 16:41:16 -0700 | [diff] [blame] | 1 | Qualcomm Techonologies, Inc. QPNP PMIC Fuel Gauge Gen3 Device |
| 2 | |
| 3 | QPNP PMIC FG Gen3 device provides interface to the clients to read properties |
| 4 | related to the battery. Its main function is to retrieve the State of Charge |
| 5 | (SOC), in percentage scale representing the amount of charge left in the |
| 6 | battery. |
| 7 | |
| 8 | ======================= |
| 9 | Required Node Structure |
| 10 | ======================= |
| 11 | |
| 12 | FG Gen3 device must be described in two levels of device nodes. The first |
| 13 | level describes the FG Gen3 device. The second level describes one or more |
| 14 | peripherals managed by FG Gen3 driver. All the peripheral specific parameters |
| 15 | such as base address, interrupts etc., should be under second level node. |
| 16 | |
| 17 | ==================================== |
| 18 | First Level Node - FG Gen3 device |
| 19 | ==================================== |
| 20 | |
| 21 | - compatible |
| 22 | Usage: required |
| 23 | Value type: <string> |
| 24 | Definition: Should be "qcom,fg-gen3". |
| 25 | |
| 26 | - qcom,pmic-revid |
| 27 | Usage: required |
| 28 | Value type: <phandle> |
| 29 | Definition: Should specify the phandle of PMIC revid module. This is |
| 30 | used to identify the PMIC subtype. |
| 31 | |
| 32 | - io-channels |
| 33 | - io-channel-names |
| 34 | Usage: required |
| 35 | Value type: <phandle> |
| 36 | Definition: For details about IIO bindings see: |
| 37 | Documentation/devicetree/bindings/iio/iio-bindings.txt |
| 38 | |
| 39 | - qcom,fg-cutoff-voltage |
| 40 | Usage: optional |
| 41 | Value type: <u32> |
| 42 | Definition: The voltage (in mV) where the fuel gauge will steer the SOC |
| 43 | to be zero. For example, if the cutoff voltage is set to |
| 44 | 3400mv, the fuel gauge will try to count SoC so that the |
| 45 | battery SOC will be 0 when it is 3400mV. If this property |
| 46 | is not specified, then the default value used will be |
| 47 | 3200mV. |
| 48 | |
| 49 | - qcom,fg-empty-voltage |
| 50 | Usage: optional |
| 51 | Value type: <u32> |
| 52 | Definition: The voltage threshold (in mV) based on which the empty soc |
| 53 | interrupt will be triggered. When the empty soc interrupt |
| 54 | fires, battery soc will be set to 0 and the userspace will |
| 55 | be notified via the power supply framework. The userspace |
| 56 | will read 0% soc and immediately shutdown. If this property |
| 57 | is not specified, then the default value used will be |
| 58 | 3100mV. |
| 59 | |
| 60 | - qcom,fg-vbatt-low-thr |
| 61 | Usage: optional |
| 62 | Value type: <u32> |
| 63 | Definition: The voltage threshold (in mV) which upon set will be used |
| 64 | for configuring the low battery voltage threshold. |
| 65 | |
| 66 | - qcom,fg-chg-term-current |
| 67 | Usage: optional |
| 68 | Value type: <u32> |
| 69 | Definition: Battery current (in mA) at which the fuel gauge will issue |
| 70 | an end of charge if the charger is configured to use the |
| 71 | fuel gauge ADC for end of charge detection. If this |
| 72 | property is not specified, then the default value used |
| 73 | will be 100mA. |
| 74 | |
| 75 | - qcom,fg-sys-term-current |
| 76 | Usage: optional |
| 77 | Value type: <u32> |
| 78 | Definition: Battery current (in mA) at which the fuel gauge will try to |
| 79 | scale towards 100%. When the charge current goes above this |
| 80 | the SOC should be at 100%. If this property is not |
Subbaraman Narayanamurthy | 4bf3ce2 | 2016-09-19 11:17:59 -0700 | [diff] [blame] | 81 | specified, then the default value used will be -125mA. |
| 82 | This value has to be specified in negative values for |
| 83 | the charging current. |
Subbaraman Narayanamurthy | 6accb26 | 2016-03-14 16:41:16 -0700 | [diff] [blame] | 84 | |
| 85 | - qcom,fg-delta-soc-thr |
| 86 | Usage: optional |
| 87 | Value type: <u32> |
| 88 | Definition: Percentage of monotonic SOC increase upon which the delta |
| 89 | SOC interrupt will be triggered. If this property is not |
Subbaraman Narayanamurthy | 6234f34 | 2016-09-22 18:11:42 -0700 | [diff] [blame] | 90 | specified, then the default value will be 1. Possible |
| 91 | values are in the range of 0 to 12. |
Subbaraman Narayanamurthy | 6accb26 | 2016-03-14 16:41:16 -0700 | [diff] [blame] | 92 | |
| 93 | - qcom,fg-recharge-soc-thr |
| 94 | Usage: optional |
| 95 | Value type: <u32> |
| 96 | Definition: Percentage of monotonic SOC upon which the charging will |
| 97 | will be resumed once the charging is complete. If this |
| 98 | property is not specified, then the default value will be |
| 99 | 95. |
| 100 | |
| 101 | - qcom,fg-rsense-sel |
| 102 | Usage: optional |
| 103 | Value type: <u32> |
| 104 | Definition: Specifies the source of sense resistor. |
| 105 | Allowed values are: |
| 106 | 0 - Rsense is from Battery FET |
| 107 | 1 - Rsense is external |
| 108 | 2 - Rsense is Battery FET and SMB |
| 109 | Option 2 can be used only when a parallel charger is |
| 110 | present. If this property is not specified, then the |
| 111 | default value will be 2. |
| 112 | |
| 113 | - qcom,fg-jeita-thresholds |
| 114 | Usage: optional |
| 115 | Value type: <prop-encoded-array> |
| 116 | Definition: A list of integers which holds the jeita thresholds (degC) |
| 117 | in the following order. Allowed size is 4. |
| 118 | Element 0 - JEITA cold threshold |
| 119 | Element 1 - JEITA cool threshold |
| 120 | Element 2 - JEITA warm threshold |
| 121 | Element 3 - JEITA hot threshold |
| 122 | If these parameters are not specified, then the default |
| 123 | values used will be 0, 5, 45, 50. |
| 124 | |
Nicholas Troast | dcf8fe6 | 2016-08-04 14:30:02 -0700 | [diff] [blame] | 125 | - qcom,fg-esr-timer-charging |
| 126 | Usage: optional |
| 127 | Value type: <u32> |
| 128 | Definition: Number of cycles between ESR pulses while the battery is |
| 129 | charging. |
| 130 | |
| 131 | - qcom,fg-esr-timer-awake |
| 132 | Usage: optional |
| 133 | Value type: <u32> |
| 134 | Definition: Number of cycles between ESR pulses while the system is |
| 135 | awake and the battery is discharging. |
| 136 | |
| 137 | - qcom,fg-esr-timer-asleep |
| 138 | Usage: optional |
| 139 | Value type: <u32> |
| 140 | Definition: Number of cycles between ESR pulses while the system is |
| 141 | asleep and the battery is discharging. This option requires |
| 142 | qcom,fg-esr-timer-awake to be defined. |
| 143 | |
Nicholas Troast | e29dec9 | 2016-08-24 09:35:11 -0700 | [diff] [blame] | 144 | - qcom,cycle-counter-en |
| 145 | Usage: optional |
| 146 | Value type: <bool> |
| 147 | Definition: Enables the cycle counter feature. |
| 148 | |
Subbaraman Narayanamurthy | 6da170e | 2016-09-21 12:36:03 -0700 | [diff] [blame] | 149 | - qcom,fg-force-load-profile |
| 150 | Usage: optional |
| 151 | Value type: <bool> |
| 152 | Definition: If set, battery profile will be force loaded if the profile |
| 153 | loaded earlier by bootloader doesn't match with the profile |
| 154 | available in the device tree. |
| 155 | |
Subbaraman Narayanamurthy | 07be919 | 2016-09-14 14:48:49 -0700 | [diff] [blame] | 156 | - qcom,cl-start-capacity |
| 157 | Usage: optional |
| 158 | Value type: <u32> |
| 159 | Definition: Battery SOC threshold to start the capacity learning. |
| 160 | If this is not specified, then the default value used |
| 161 | will be 15. |
| 162 | |
| 163 | - qcom,cl-min-temp |
| 164 | Usage: optional |
| 165 | Value type: <u32> |
| 166 | Definition: Lower limit of battery temperature to start the capacity |
| 167 | learning. If this is not specified, then the default value |
| 168 | used will be 150. Unit is in decidegC. |
| 169 | |
| 170 | - qcom,cl-max-temp |
| 171 | Usage: optional |
| 172 | Value type: <u32> |
| 173 | Definition: Upper limit of battery temperature to start the capacity |
| 174 | learning. If this is not specified, then the default value |
| 175 | used will be 450 (45C). Unit is in decidegC. |
| 176 | |
| 177 | - qcom,cl-max-increment |
| 178 | Usage: optional |
| 179 | Value type: <u32> |
| 180 | Definition: Maximum capacity increment allowed per capacity learning |
| 181 | cycle. If this is not specified, then the default value |
| 182 | used will be 5 (0.5%). Unit is in decipercentage. |
| 183 | |
| 184 | - qcom,cl-max-decrement |
| 185 | Usage: optional |
| 186 | Value type: <u32> |
| 187 | Definition: Maximum capacity decrement allowed per capacity learning |
| 188 | cycle. If this is not specified, then the default value |
| 189 | used will be 100 (10%). Unit is in decipercentage. |
| 190 | |
| 191 | - qcom,cl-min-limit |
| 192 | Usage: optional |
| 193 | Value type: <u32> |
| 194 | Definition: Minimum limit that the capacity cannot go below in a |
| 195 | capacity learning cycle. If this is not specified, then |
| 196 | the default value is 0. Unit is in decipercentage. |
| 197 | |
| 198 | - qcom,cl-max-limit |
| 199 | Usage: optional |
| 200 | Value type: <u32> |
| 201 | Definition: Maximum limit that the capacity cannot go above in a |
| 202 | capacity learning cycle. If this is not specified, then |
| 203 | the default value is 0. Unit is in decipercentage. |
| 204 | |
Subbaraman Narayanamurthy | 65ff45e | 2016-09-23 19:11:17 -0700 | [diff] [blame^] | 205 | - qcom,fg-jeita-hyst-temp |
| 206 | Usage: optional |
| 207 | Value type: <u32> |
| 208 | Definition: Hysteresis applied to Jeita temperature comparison. |
| 209 | Possible values are: |
| 210 | 0 - No hysteresis |
| 211 | 1,2,3 - Value in Celsius. |
| 212 | |
Subbaraman Narayanamurthy | 6accb26 | 2016-03-14 16:41:16 -0700 | [diff] [blame] | 213 | ========================================================== |
| 214 | Second Level Nodes - Peripherals managed by FG Gen3 driver |
| 215 | ========================================================== |
| 216 | - reg |
| 217 | Usage: required |
| 218 | Value type: <prop-encoded-array> |
| 219 | Definition: Addresses and sizes for the specified peripheral |
| 220 | |
| 221 | - interrupts |
| 222 | Usage: optional |
| 223 | Value type: <prop-encoded-array> |
| 224 | Definition: Interrupt mapping as per the interrupt encoding |
| 225 | |
| 226 | - interrupt-names |
| 227 | Usage: optional |
| 228 | Value type: <stringlist> |
| 229 | Definition: Interrupt names. This list must match up 1-to-1 with the |
| 230 | interrupts specified in the 'interrupts' property. |
| 231 | |
| 232 | ======== |
| 233 | Example |
| 234 | ======== |
| 235 | |
| 236 | pmicobalt_fg: qpnp,fg { |
| 237 | compatible = "qcom,fg-gen3"; |
| 238 | #address-cells = <1>; |
| 239 | #size-cells = <1>; |
| 240 | qcom,pmic-revid = <&pmicobalt_revid>; |
| 241 | io-channels = <&pmicobalt_rradc 3>; |
| 242 | io-channel-names = "rradc_batt_id"; |
| 243 | status = "okay"; |
| 244 | |
| 245 | qcom,fg-batt-soc@4000 { |
| 246 | status = "okay"; |
| 247 | reg = <0x4000 0x100>; |
| 248 | interrupts = <0x2 0x40 0x0 IRQ_TYPE_EDGE_BOTH>, |
| 249 | <0x2 0x40 0x1 IRQ_TYPE_EDGE_BOTH>, |
| 250 | <0x2 0x40 0x2 IRQ_TYPE_EDGE_BOTH>, |
| 251 | <0x2 0x40 0x3 IRQ_TYPE_EDGE_BOTH>; |
| 252 | interrupt-names = "soc-update", |
| 253 | "soc-ready", |
| 254 | "bsoc-delta", |
| 255 | "msoc-delta"; |
| 256 | |
| 257 | }; |
| 258 | |
| 259 | qcom,fg-batt-info@4100 { |
| 260 | status = "okay"; |
| 261 | reg = <0x4100 0x100>; |
| 262 | interrupts = <0x2 0x41 0x3 IRQ_TYPE_EDGE_BOTH>; |
| 263 | interrupt-names = "batt-missing"; |
| 264 | }; |
| 265 | |
| 266 | qcom,fg-memif@4400 { |
| 267 | status = "okay"; |
| 268 | reg = <0x4400 0x100>; |
| 269 | }; |
| 270 | }; |