// SPDX-License-Identifier: GPL-2.0+
/*
 * Helper for batteries with accurate current and voltage measurement, but
 * without temperature measurement or without a "resistance-temp-table".
 *
 * Some fuel-gauges are not full-featured autonomous fuel-gauges.
 * These fuel-gauges offer accurate current and voltage measurements but
 * their coulomb-counters are intended to work together with an always on
 * micro-controller monitoring the fuel-gauge.
 *
 * This adc-battery-helper code offers open-circuit-voltage (ocv) and through
 * that capacity estimation for devices where such limited functionality
 * fuel-gauges are exposed directly to Linux.
 *
 * This helper requires the hw to provide accurate battery current_now and
 * voltage_now measurement and this helper the provides the following properties
 * based on top of those readings:
 *
 *      POWER_SUPPLY_PROP_STATUS
 *      POWER_SUPPLY_PROP_VOLTAGE_OCV
 *      POWER_SUPPLY_PROP_VOLTAGE_NOW
 *      POWER_SUPPLY_PROP_CURRENT_NOW
 *      POWER_SUPPLY_PROP_CAPACITY
 *
 * As well as optional the following properties assuming an always present
 * system-scope battery, allowing direct use of adc_battery_helper_get_prop()
 * in this common case:
 *      POWER_SUPPLY_PROP_PRESENT
 *      POWER_SUPPLY_PROP_SCOPE
 *
 * Using this helper is as simple as:
 *
 * 1. Embed a struct adc_battery_helper this MUST be the first member of
 *    the battery driver's data struct.
 * 2. Use adc_battery_helper_props[] or add the above properties to
 *    the list of properties in power_supply_desc
 * 3. Call adc_battery_helper_init() after registering the power_supply and
 *    before returning from the probe() function
 * 4. Use adc_battery_helper_get_prop() as the power-supply's get_property()
 *    method, or call it for the above properties.
 * 5. Use adc_battery_helper_external_power_changed() as the power-supply's
 *    external_power_changed() method or call it from that method.
 * 6. Use adc_battery_helper_[suspend|resume]() as suspend-resume methods or
 *    call them from the driver's suspend-resume methods.
 *
 * The provided get_voltage_and_current_now() method will be called by this
 * helper at adc_battery_helper_init() time and later.
 *
 * Copyright (c) 2021-2025 Hans de Goede <hansg@kernel.org>
 */

#include <linux/cleanup.h>
#include <linux/devm-helpers.h>
#include <linux/gpio/consumer.h>
#include <linux/mutex.h>
#include <linux/power_supply.h>
#include <linux/workqueue.h>

#include "adc-battery-helper.h"

#define MOV_AVG_WINDOW_SIZE                     ADC_BAT_HELPER_MOV_AVG_WINDOW_SIZE
#define INIT_POLL_TIME                          (5 * HZ)
#define POLL_TIME                               (30 * HZ)
#define SETTLE_TIME                             (1 * HZ)

#define INIT_POLL_COUNT                         30

#define CURR_HYST_UA                            65000

#define LOW_BAT_UV                              3700000
#define FULL_BAT_HYST_UV                        38000

#define AMBIENT_TEMP_CELSIUS                    25

static int adc_battery_helper_get_status(struct adc_battery_helper *help)
{
        int full_uv =
                help->psy->battery_info->constant_charge_voltage_max_uv - FULL_BAT_HYST_UV;

        if (help->curr_ua > CURR_HYST_UA)
                return POWER_SUPPLY_STATUS_CHARGING;

        if (help->curr_ua < -CURR_HYST_UA)
                return POWER_SUPPLY_STATUS_DISCHARGING;

        if (help->supplied) {
                bool full;

                if (help->charge_finished)
                        full = gpiod_get_value_cansleep(help->charge_finished);
                else
                        full = help->ocv_avg_uv > full_uv;

                if (full)
                        return POWER_SUPPLY_STATUS_FULL;
        }

        return POWER_SUPPLY_STATUS_NOT_CHARGING;
}

static void adc_battery_helper_work(struct work_struct *work)
{
        struct adc_battery_helper *help = container_of(work, struct adc_battery_helper,
                                                       work.work);
        int i, curr_diff_ua, volt_diff_uv, res_mohm, ret, win_size;
        struct device *dev = help->psy->dev.parent;
        int volt_uv, prev_volt_uv = help->volt_uv;
        int curr_ua, prev_curr_ua = help->curr_ua;
        bool prev_supplied = help->supplied;
        int prev_status = help->status;

        guard(mutex)(&help->lock);

        ret = help->get_voltage_and_current_now(help->psy, &volt_uv, &curr_ua);
        if (ret)
                goto out;

        help->volt_uv = volt_uv;
        help->curr_ua = curr_ua;

        help->ocv_uv[help->ocv_avg_index] =
                help->volt_uv - help->curr_ua * help->intern_res_avg_mohm / 1000;
        dev_dbg(dev, "volt-now: %d, curr-now: %d, volt-ocv: %d\n",
                help->volt_uv, help->curr_ua, help->ocv_uv[help->ocv_avg_index]);
        help->ocv_avg_index = (help->ocv_avg_index + 1) % MOV_AVG_WINDOW_SIZE;
        help->poll_count++;

        help->ocv_avg_uv = 0;
        win_size = min(help->poll_count, MOV_AVG_WINDOW_SIZE);
        for (i = 0; i < win_size; i++)
                help->ocv_avg_uv += help->ocv_uv[i];
        help->ocv_avg_uv /= win_size;

        help->supplied = power_supply_am_i_supplied(help->psy);
        help->status = adc_battery_helper_get_status(help);
        if (help->status == POWER_SUPPLY_STATUS_FULL)
                help->capacity = 100;
        else
                help->capacity = power_supply_batinfo_ocv2cap(help->psy->battery_info,
                                                              help->ocv_avg_uv,
                                                              AMBIENT_TEMP_CELSIUS);

        /*
         * Skip internal resistance calc on charger [un]plug and
         * when the battery is almost empty (voltage low).
         */
        if (help->supplied != prev_supplied ||
            help->volt_uv < LOW_BAT_UV ||
            help->poll_count < 2)
                goto out;

        /*
         * Assuming that the OCV voltage does not change significantly
         * between 2 polls, then we can calculate the internal resistance
         * on a significant current change by attributing all voltage
         * change between the 2 readings to the internal resistance.
         */
        curr_diff_ua = abs(help->curr_ua - prev_curr_ua);
        if (curr_diff_ua < CURR_HYST_UA)
                goto out;

        volt_diff_uv = abs(help->volt_uv - prev_volt_uv);
        res_mohm = volt_diff_uv * 1000 / curr_diff_ua;

        if ((res_mohm < (help->intern_res_avg_mohm * 2 / 3)) ||
            (res_mohm > (help->intern_res_avg_mohm * 4 / 3))) {
                dev_dbg(dev, "Ignoring outlier internal resistance %d mOhm\n", res_mohm);
                goto out;
        }

        dev_dbg(dev, "Internal resistance %d mOhm\n", res_mohm);

        help->intern_res_mohm[help->intern_res_avg_index] = res_mohm;
        help->intern_res_avg_index = (help->intern_res_avg_index + 1) % MOV_AVG_WINDOW_SIZE;
        help->intern_res_poll_count++;

        help->intern_res_avg_mohm = 0;
        win_size = min(help->intern_res_poll_count, MOV_AVG_WINDOW_SIZE);
        for (i = 0; i < win_size; i++)
                help->intern_res_avg_mohm += help->intern_res_mohm[i];
        help->intern_res_avg_mohm /= win_size;

out:
        queue_delayed_work(system_percpu_wq, &help->work,
                           (help->poll_count <= INIT_POLL_COUNT) ?
                                        INIT_POLL_TIME : POLL_TIME);

        if (help->status != prev_status)
                power_supply_changed(help->psy);
}

const enum power_supply_property adc_battery_helper_properties[] = {
        POWER_SUPPLY_PROP_STATUS,
        POWER_SUPPLY_PROP_VOLTAGE_NOW,
        POWER_SUPPLY_PROP_VOLTAGE_OCV,
        POWER_SUPPLY_PROP_CURRENT_NOW,
        POWER_SUPPLY_PROP_CAPACITY,
        POWER_SUPPLY_PROP_PRESENT,
        POWER_SUPPLY_PROP_SCOPE,
};
EXPORT_SYMBOL_GPL(adc_battery_helper_properties);

static_assert(ARRAY_SIZE(adc_battery_helper_properties) ==
              ADC_HELPER_NUM_PROPERTIES);

int adc_battery_helper_get_property(struct power_supply *psy,
                                    enum power_supply_property psp,
                                    union power_supply_propval *val)
{
        struct adc_battery_helper *help = power_supply_get_drvdata(psy);
        int dummy, ret = 0;

        /*
         * Avoid racing with adc_battery_helper_work() while it is updating
         * variables and avoid calling get_voltage_and_current_now() reentrantly.
         */
        guard(mutex)(&help->lock);

        switch (psp) {
        case POWER_SUPPLY_PROP_STATUS:
                val->intval = help->status;
                break;
        case POWER_SUPPLY_PROP_VOLTAGE_NOW:
                ret = help->get_voltage_and_current_now(psy, &val->intval, &dummy);
                break;
        case POWER_SUPPLY_PROP_VOLTAGE_OCV:
                val->intval = help->ocv_avg_uv;
                break;
        case POWER_SUPPLY_PROP_CURRENT_NOW:
                ret = help->get_voltage_and_current_now(psy, &dummy, &val->intval);
                break;
        case POWER_SUPPLY_PROP_CAPACITY:
                val->intval = help->capacity;
                break;
        case POWER_SUPPLY_PROP_PRESENT:
                val->intval = 1;
                break;
        case POWER_SUPPLY_PROP_SCOPE:
                val->intval = POWER_SUPPLY_SCOPE_SYSTEM;
                break;
        default:
                return -EINVAL;
        }

        return ret;
}
EXPORT_SYMBOL_GPL(adc_battery_helper_get_property);

void adc_battery_helper_external_power_changed(struct power_supply *psy)
{
        struct adc_battery_helper *help = power_supply_get_drvdata(psy);

        dev_dbg(help->psy->dev.parent, "external power changed\n");
        mod_delayed_work(system_percpu_wq, &help->work, SETTLE_TIME);
}
EXPORT_SYMBOL_GPL(adc_battery_helper_external_power_changed);

static void adc_battery_helper_start_work(struct adc_battery_helper *help)
{
        help->poll_count = 0;
        help->ocv_avg_index = 0;

        queue_delayed_work(system_percpu_wq, &help->work, 0);
        flush_delayed_work(&help->work);
}

int 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)
{
        struct device *dev = psy->dev.parent;
        int ret;

        help->psy = psy;
        help->get_voltage_and_current_now = get_voltage_and_current_now;
        help->charge_finished = charge_finished_gpio;

        ret = devm_mutex_init(dev, &help->lock);
        if (ret)
                return ret;

        ret = devm_delayed_work_autocancel(dev, &help->work, adc_battery_helper_work);
        if (ret)
                return ret;

        if (!help->psy->battery_info ||
            help->psy->battery_info->factory_internal_resistance_uohm == -EINVAL ||
            help->psy->battery_info->constant_charge_voltage_max_uv == -EINVAL ||
            !psy->battery_info->ocv_table[0]) {
                dev_err(dev, "error required properties are missing\n");
                return -ENODEV;
        }

        /* Use provided internal resistance as start point (in milli-ohm) */
        help->intern_res_avg_mohm =
                help->psy->battery_info->factory_internal_resistance_uohm / 1000;
        /* Also add it to the internal resistance moving average window */
        help->intern_res_mohm[0] = help->intern_res_avg_mohm;
        help->intern_res_avg_index = 1;
        help->intern_res_poll_count = 1;

        adc_battery_helper_start_work(help);
        return 0;
}
EXPORT_SYMBOL_GPL(adc_battery_helper_init);

int adc_battery_helper_suspend(struct device *dev)
{
        struct adc_battery_helper *help = dev_get_drvdata(dev);

        cancel_delayed_work_sync(&help->work);
        return 0;
}
EXPORT_SYMBOL_GPL(adc_battery_helper_suspend);

int adc_battery_helper_resume(struct device *dev)
{
        struct adc_battery_helper *help = dev_get_drvdata(dev);

        adc_battery_helper_start_work(help);
        return 0;
}
EXPORT_SYMBOL_GPL(adc_battery_helper_resume);

MODULE_AUTHOR("Hans de Goede <hansg@kernel.org>");
MODULE_DESCRIPTION("ADC battery capacity estimation helper");
MODULE_LICENSE("GPL");