1 // SPDX-License-Identifier: GPL-2.0+ 2 /* 3 * Helper for batteries with accurate current and voltage measurement, but 4 * without temperature measurement or without a "resistance-temp-table". 5 * 6 * Some fuel-gauges are not full-featured autonomous fuel-gauges. 7 * These fuel-gauges offer accurate current and voltage measurements but 8 * their coulomb-counters are intended to work together with an always on 9 * micro-controller monitoring the fuel-gauge. 10 * 11 * This adc-battery-helper code offers open-circuit-voltage (ocv) and through 12 * that capacity estimation for devices where such limited functionality 13 * fuel-gauges are exposed directly to Linux. 14 * 15 * This helper requires the hw to provide accurate battery current_now and 16 * voltage_now measurement and this helper the provides the following properties 17 * based on top of those readings: 18 * 19 * POWER_SUPPLY_PROP_STATUS 20 * POWER_SUPPLY_PROP_VOLTAGE_OCV 21 * POWER_SUPPLY_PROP_VOLTAGE_NOW 22 * POWER_SUPPLY_PROP_CURRENT_NOW 23 * POWER_SUPPLY_PROP_CAPACITY 24 * 25 * As well as optional the following properties assuming an always present 26 * system-scope battery, allowing direct use of adc_battery_helper_get_prop() 27 * in this common case: 28 * POWER_SUPPLY_PROP_PRESENT 29 * POWER_SUPPLY_PROP_SCOPE 30 * 31 * Using this helper is as simple as: 32 * 33 * 1. Embed a struct adc_battery_helper this MUST be the first member of 34 * the battery driver's data struct. 35 * 2. Use adc_battery_helper_props[] or add the above properties to 36 * the list of properties in power_supply_desc 37 * 3. Call adc_battery_helper_init() after registering the power_supply and 38 * before returning from the probe() function 39 * 4. Use adc_battery_helper_get_prop() as the power-supply's get_property() 40 * method, or call it for the above properties. 41 * 5. Use adc_battery_helper_external_power_changed() as the power-supply's 42 * external_power_changed() method or call it from that method. 43 * 6. Use adc_battery_helper_[suspend|resume]() as suspend-resume methods or 44 * call them from the driver's suspend-resume methods. 45 * 46 * The provided get_voltage_and_current_now() method will be called by this 47 * helper at adc_battery_helper_init() time and later. 48 * 49 * Copyright (c) 2021-2025 Hans de Goede <hansg@kernel.org> 50 */ 51 52 #include <linux/cleanup.h> 53 #include <linux/devm-helpers.h> 54 #include <linux/gpio/consumer.h> 55 #include <linux/mutex.h> 56 #include <linux/power_supply.h> 57 #include <linux/workqueue.h> 58 59 #include "adc-battery-helper.h" 60 61 #define MOV_AVG_WINDOW_SIZE ADC_BAT_HELPER_MOV_AVG_WINDOW_SIZE 62 #define INIT_POLL_TIME (5 * HZ) 63 #define POLL_TIME (30 * HZ) 64 #define SETTLE_TIME (1 * HZ) 65 66 #define INIT_POLL_COUNT 30 67 68 #define CURR_HYST_UA 65000 69 70 #define LOW_BAT_UV 3700000 71 #define FULL_BAT_HYST_UV 38000 72 73 #define AMBIENT_TEMP_CELSIUS 25 74 75 static int adc_battery_helper_get_status(struct adc_battery_helper *help) 76 { 77 int full_uv = 78 help->psy->battery_info->constant_charge_voltage_max_uv - FULL_BAT_HYST_UV; 79 80 if (help->curr_ua > CURR_HYST_UA) 81 return POWER_SUPPLY_STATUS_CHARGING; 82 83 if (help->curr_ua < -CURR_HYST_UA) 84 return POWER_SUPPLY_STATUS_DISCHARGING; 85 86 if (help->supplied) { 87 bool full; 88 89 if (help->charge_finished) 90 full = gpiod_get_value_cansleep(help->charge_finished); 91 else 92 full = help->ocv_avg_uv > full_uv; 93 94 if (full) 95 return POWER_SUPPLY_STATUS_FULL; 96 } 97 98 return POWER_SUPPLY_STATUS_NOT_CHARGING; 99 } 100 101 static void adc_battery_helper_work(struct work_struct *work) 102 { 103 struct adc_battery_helper *help = container_of(work, struct adc_battery_helper, 104 work.work); 105 int i, curr_diff_ua, volt_diff_uv, res_mohm, ret, win_size; 106 struct device *dev = help->psy->dev.parent; 107 int volt_uv, prev_volt_uv = help->volt_uv; 108 int curr_ua, prev_curr_ua = help->curr_ua; 109 bool prev_supplied = help->supplied; 110 int prev_status = help->status; 111 112 guard(mutex)(&help->lock); 113 114 ret = help->get_voltage_and_current_now(help->psy, &volt_uv, &curr_ua); 115 if (ret) 116 goto out; 117 118 help->volt_uv = volt_uv; 119 help->curr_ua = curr_ua; 120 121 help->ocv_uv[help->ocv_avg_index] = 122 help->volt_uv - help->curr_ua * help->intern_res_avg_mohm / 1000; 123 dev_dbg(dev, "volt-now: %d, curr-now: %d, volt-ocv: %d\n", 124 help->volt_uv, help->curr_ua, help->ocv_uv[help->ocv_avg_index]); 125 help->ocv_avg_index = (help->ocv_avg_index + 1) % MOV_AVG_WINDOW_SIZE; 126 help->poll_count++; 127 128 help->ocv_avg_uv = 0; 129 win_size = min(help->poll_count, MOV_AVG_WINDOW_SIZE); 130 for (i = 0; i < win_size; i++) 131 help->ocv_avg_uv += help->ocv_uv[i]; 132 help->ocv_avg_uv /= win_size; 133 134 help->supplied = power_supply_am_i_supplied(help->psy); 135 help->status = adc_battery_helper_get_status(help); 136 if (help->status == POWER_SUPPLY_STATUS_FULL) 137 help->capacity = 100; 138 else 139 help->capacity = power_supply_batinfo_ocv2cap(help->psy->battery_info, 140 help->ocv_avg_uv, 141 AMBIENT_TEMP_CELSIUS); 142 143 /* 144 * Skip internal resistance calc on charger [un]plug and 145 * when the battery is almost empty (voltage low). 146 */ 147 if (help->supplied != prev_supplied || 148 help->volt_uv < LOW_BAT_UV || 149 help->poll_count < 2) 150 goto out; 151 152 /* 153 * Assuming that the OCV voltage does not change significantly 154 * between 2 polls, then we can calculate the internal resistance 155 * on a significant current change by attributing all voltage 156 * change between the 2 readings to the internal resistance. 157 */ 158 curr_diff_ua = abs(help->curr_ua - prev_curr_ua); 159 if (curr_diff_ua < CURR_HYST_UA) 160 goto out; 161 162 volt_diff_uv = abs(help->volt_uv - prev_volt_uv); 163 res_mohm = volt_diff_uv * 1000 / curr_diff_ua; 164 165 if ((res_mohm < (help->intern_res_avg_mohm * 2 / 3)) || 166 (res_mohm > (help->intern_res_avg_mohm * 4 / 3))) { 167 dev_dbg(dev, "Ignoring outlier internal resistance %d mOhm\n", res_mohm); 168 goto out; 169 } 170 171 dev_dbg(dev, "Internal resistance %d mOhm\n", res_mohm); 172 173 help->intern_res_mohm[help->intern_res_avg_index] = res_mohm; 174 help->intern_res_avg_index = (help->intern_res_avg_index + 1) % MOV_AVG_WINDOW_SIZE; 175 help->intern_res_poll_count++; 176 177 help->intern_res_avg_mohm = 0; 178 win_size = min(help->intern_res_poll_count, MOV_AVG_WINDOW_SIZE); 179 for (i = 0; i < win_size; i++) 180 help->intern_res_avg_mohm += help->intern_res_mohm[i]; 181 help->intern_res_avg_mohm /= win_size; 182 183 out: 184 queue_delayed_work(system_percpu_wq, &help->work, 185 (help->poll_count <= INIT_POLL_COUNT) ? 186 INIT_POLL_TIME : POLL_TIME); 187 188 if (help->status != prev_status) 189 power_supply_changed(help->psy); 190 } 191 192 const enum power_supply_property adc_battery_helper_properties[] = { 193 POWER_SUPPLY_PROP_STATUS, 194 POWER_SUPPLY_PROP_VOLTAGE_NOW, 195 POWER_SUPPLY_PROP_VOLTAGE_OCV, 196 POWER_SUPPLY_PROP_CURRENT_NOW, 197 POWER_SUPPLY_PROP_CAPACITY, 198 POWER_SUPPLY_PROP_PRESENT, 199 POWER_SUPPLY_PROP_SCOPE, 200 }; 201 EXPORT_SYMBOL_GPL(adc_battery_helper_properties); 202 203 static_assert(ARRAY_SIZE(adc_battery_helper_properties) == 204 ADC_HELPER_NUM_PROPERTIES); 205 206 int adc_battery_helper_get_property(struct power_supply *psy, 207 enum power_supply_property psp, 208 union power_supply_propval *val) 209 { 210 struct adc_battery_helper *help = power_supply_get_drvdata(psy); 211 int dummy, ret = 0; 212 213 /* 214 * Avoid racing with adc_battery_helper_work() while it is updating 215 * variables and avoid calling get_voltage_and_current_now() reentrantly. 216 */ 217 guard(mutex)(&help->lock); 218 219 switch (psp) { 220 case POWER_SUPPLY_PROP_STATUS: 221 val->intval = help->status; 222 break; 223 case POWER_SUPPLY_PROP_VOLTAGE_NOW: 224 ret = help->get_voltage_and_current_now(psy, &val->intval, &dummy); 225 break; 226 case POWER_SUPPLY_PROP_VOLTAGE_OCV: 227 val->intval = help->ocv_avg_uv; 228 break; 229 case POWER_SUPPLY_PROP_CURRENT_NOW: 230 ret = help->get_voltage_and_current_now(psy, &dummy, &val->intval); 231 break; 232 case POWER_SUPPLY_PROP_CAPACITY: 233 val->intval = help->capacity; 234 break; 235 case POWER_SUPPLY_PROP_PRESENT: 236 val->intval = 1; 237 break; 238 case POWER_SUPPLY_PROP_SCOPE: 239 val->intval = POWER_SUPPLY_SCOPE_SYSTEM; 240 break; 241 default: 242 return -EINVAL; 243 } 244 245 return ret; 246 } 247 EXPORT_SYMBOL_GPL(adc_battery_helper_get_property); 248 249 void adc_battery_helper_external_power_changed(struct power_supply *psy) 250 { 251 struct adc_battery_helper *help = power_supply_get_drvdata(psy); 252 253 dev_dbg(help->psy->dev.parent, "external power changed\n"); 254 mod_delayed_work(system_percpu_wq, &help->work, SETTLE_TIME); 255 } 256 EXPORT_SYMBOL_GPL(adc_battery_helper_external_power_changed); 257 258 static void adc_battery_helper_start_work(struct adc_battery_helper *help) 259 { 260 help->poll_count = 0; 261 help->ocv_avg_index = 0; 262 263 queue_delayed_work(system_percpu_wq, &help->work, 0); 264 flush_delayed_work(&help->work); 265 } 266 267 int adc_battery_helper_init(struct adc_battery_helper *help, struct power_supply *psy, 268 adc_battery_helper_get_func get_voltage_and_current_now, 269 struct gpio_desc *charge_finished_gpio) 270 { 271 struct device *dev = psy->dev.parent; 272 int ret; 273 274 help->psy = psy; 275 help->get_voltage_and_current_now = get_voltage_and_current_now; 276 help->charge_finished = charge_finished_gpio; 277 278 ret = devm_mutex_init(dev, &help->lock); 279 if (ret) 280 return ret; 281 282 ret = devm_delayed_work_autocancel(dev, &help->work, adc_battery_helper_work); 283 if (ret) 284 return ret; 285 286 if (!help->psy->battery_info || 287 help->psy->battery_info->factory_internal_resistance_uohm == -EINVAL || 288 help->psy->battery_info->constant_charge_voltage_max_uv == -EINVAL || 289 !psy->battery_info->ocv_table[0]) { 290 dev_err(dev, "error required properties are missing\n"); 291 return -ENODEV; 292 } 293 294 /* Use provided internal resistance as start point (in milli-ohm) */ 295 help->intern_res_avg_mohm = 296 help->psy->battery_info->factory_internal_resistance_uohm / 1000; 297 /* Also add it to the internal resistance moving average window */ 298 help->intern_res_mohm[0] = help->intern_res_avg_mohm; 299 help->intern_res_avg_index = 1; 300 help->intern_res_poll_count = 1; 301 302 adc_battery_helper_start_work(help); 303 return 0; 304 } 305 EXPORT_SYMBOL_GPL(adc_battery_helper_init); 306 307 int adc_battery_helper_suspend(struct device *dev) 308 { 309 struct adc_battery_helper *help = dev_get_drvdata(dev); 310 311 cancel_delayed_work_sync(&help->work); 312 return 0; 313 } 314 EXPORT_SYMBOL_GPL(adc_battery_helper_suspend); 315 316 int adc_battery_helper_resume(struct device *dev) 317 { 318 struct adc_battery_helper *help = dev_get_drvdata(dev); 319 320 adc_battery_helper_start_work(help); 321 return 0; 322 } 323 EXPORT_SYMBOL_GPL(adc_battery_helper_resume); 324 325 MODULE_AUTHOR("Hans de Goede <hansg@kernel.org>"); 326 MODULE_DESCRIPTION("ADC battery capacity estimation helper"); 327 MODULE_LICENSE("GPL"); 328