adc-battery-helper.c

  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
 75static 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
101static 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
183out:
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
192const 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};
201EXPORT_SYMBOL_GPL(adc_battery_helper_properties);
202
203static_assert(ARRAY_SIZE(adc_battery_helper_properties) ==
204	      ADC_HELPER_NUM_PROPERTIES);
205
206int 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}
247EXPORT_SYMBOL_GPL(adc_battery_helper_get_property);
248
249void 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}
256EXPORT_SYMBOL_GPL(adc_battery_helper_external_power_changed);
257
258static 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
267int 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}
305EXPORT_SYMBOL_GPL(adc_battery_helper_init);
306
307int 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}
314EXPORT_SYMBOL_GPL(adc_battery_helper_suspend);
315
316int 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}
323EXPORT_SYMBOL_GPL(adc_battery_helper_resume);
324
325MODULE_AUTHOR("Hans de Goede <hansg@kernel.org>");
326MODULE_DESCRIPTION("ADC battery capacity estimation helper");
327MODULE_LICENSE("GPL");