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
adc_battery_helper_get_status(struct adc_battery_helper * help)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
adc_battery_helper_work(struct work_struct * work)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
adc_battery_helper_get_property(struct power_supply * psy,enum power_supply_property psp,union power_supply_propval * val)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
adc_battery_helper_external_power_changed(struct power_supply * psy)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
adc_battery_helper_start_work(struct adc_battery_helper * help)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
adc_battery_helper_init(struct adc_battery_helper * help,struct power_supply * psy,adc_battery_helper_get_func get_voltage_and_current_now,struct gpio_desc * charge_finished_gpio)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
adc_battery_helper_suspend(struct device * dev)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
adc_battery_helper_resume(struct device * dev)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