include/linux/power_supply.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  *  Universal power supply monitor class
   4  *
   5  *  Copyright © 2007  Anton Vorontsov <cbou@mail.ru>
   6  *  Copyright © 2004  Szabolcs Gyurko
   7  *  Copyright © 2003  Ian Molton <spyro@f2s.com>
   8  *
   9  *  Modified: 2004, Oct     Szabolcs Gyurko
  10  */
  11
  12 #ifndef __LINUX_POWER_SUPPLY_H__
  13 #define __LINUX_POWER_SUPPLY_H__
  14
  15 #include <linux/device.h>
  16 #include <linux/workqueue.h>
  17 #include <linux/leds.h>
  18 #include <linux/spinlock.h>
  19 #include <linux/notifier.h>
  20
  21 /*
  22  * All voltages, currents, charges, energies, time and temperatures in uV,
  23  * µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
  24  * stated. It's driver's job to convert its raw values to units in which
  25  * this class operates.
  26  */
  27
  28 /*
  29  * For systems where the charger determines the maximum battery capacity
  30  * the min and max fields should be used to present these values to user
  31  * space. Unused/unknown fields will not appear in sysfs.
  32  */
  33
  34 enum {
  35         POWER_SUPPLY_STATUS_UNKNOWN = 0,
  36         POWER_SUPPLY_STATUS_CHARGING,
  37         POWER_SUPPLY_STATUS_DISCHARGING,
  38         POWER_SUPPLY_STATUS_NOT_CHARGING,
  39         POWER_SUPPLY_STATUS_FULL,
  40 };
  41
  42 /* What algorithm is the charger using? */
  43 enum {
  44         POWER_SUPPLY_CHARGE_TYPE_UNKNOWN = 0,
  45         POWER_SUPPLY_CHARGE_TYPE_NONE,
  46         POWER_SUPPLY_CHARGE_TYPE_TRICKLE,       /* slow speed */
  47         POWER_SUPPLY_CHARGE_TYPE_FAST,          /* fast speed */
  48         POWER_SUPPLY_CHARGE_TYPE_STANDARD,      /* normal speed */
  49         POWER_SUPPLY_CHARGE_TYPE_ADAPTIVE,      /* dynamically adjusted speed */
  50         POWER_SUPPLY_CHARGE_TYPE_CUSTOM,        /* use CHARGE_CONTROL_* props */
  51         POWER_SUPPLY_CHARGE_TYPE_LONGLIFE,      /* slow speed, longer life */
  52 };
  53
  54 enum {
  55         POWER_SUPPLY_HEALTH_UNKNOWN = 0,
  56         POWER_SUPPLY_HEALTH_GOOD,
  57         POWER_SUPPLY_HEALTH_OVERHEAT,
  58         POWER_SUPPLY_HEALTH_DEAD,
  59         POWER_SUPPLY_HEALTH_OVERVOLTAGE,
  60         POWER_SUPPLY_HEALTH_UNSPEC_FAILURE,
  61         POWER_SUPPLY_HEALTH_COLD,
  62         POWER_SUPPLY_HEALTH_WATCHDOG_TIMER_EXPIRE,
  63         POWER_SUPPLY_HEALTH_SAFETY_TIMER_EXPIRE,
  64         POWER_SUPPLY_HEALTH_OVERCURRENT,
  65         POWER_SUPPLY_HEALTH_CALIBRATION_REQUIRED,
  66         POWER_SUPPLY_HEALTH_WARM,
  67         POWER_SUPPLY_HEALTH_COOL,
  68         POWER_SUPPLY_HEALTH_HOT,
  69         POWER_SUPPLY_HEALTH_NO_BATTERY,
  70 };
  71
  72 enum {
  73         POWER_SUPPLY_TECHNOLOGY_UNKNOWN = 0,
  74         POWER_SUPPLY_TECHNOLOGY_NiMH,
  75         POWER_SUPPLY_TECHNOLOGY_LION,
  76         POWER_SUPPLY_TECHNOLOGY_LIPO,
  77         POWER_SUPPLY_TECHNOLOGY_LiFe,
  78         POWER_SUPPLY_TECHNOLOGY_NiCd,
  79         POWER_SUPPLY_TECHNOLOGY_LiMn,
  80 };
  81
  82 enum {
  83         POWER_SUPPLY_CAPACITY_LEVEL_UNKNOWN = 0,
  84         POWER_SUPPLY_CAPACITY_LEVEL_CRITICAL,
  85         POWER_SUPPLY_CAPACITY_LEVEL_LOW,
  86         POWER_SUPPLY_CAPACITY_LEVEL_NORMAL,
  87         POWER_SUPPLY_CAPACITY_LEVEL_HIGH,
  88         POWER_SUPPLY_CAPACITY_LEVEL_FULL,
  89 };
  90
  91 enum {
  92         POWER_SUPPLY_SCOPE_UNKNOWN = 0,
  93         POWER_SUPPLY_SCOPE_SYSTEM,
  94         POWER_SUPPLY_SCOPE_DEVICE,
  95 };
  96
  97 enum power_supply_property {
  98         /* Properties of type `int' */
  99         POWER_SUPPLY_PROP_STATUS = 0,
 100         POWER_SUPPLY_PROP_CHARGE_TYPE,
 101         POWER_SUPPLY_PROP_HEALTH,
 102         POWER_SUPPLY_PROP_PRESENT,
 103         POWER_SUPPLY_PROP_ONLINE,
 104         POWER_SUPPLY_PROP_AUTHENTIC,
 105         POWER_SUPPLY_PROP_TECHNOLOGY,
 106         POWER_SUPPLY_PROP_CYCLE_COUNT,
 107         POWER_SUPPLY_PROP_VOLTAGE_MAX,
 108         POWER_SUPPLY_PROP_VOLTAGE_MIN,
 109         POWER_SUPPLY_PROP_VOLTAGE_MAX_DESIGN,
 110         POWER_SUPPLY_PROP_VOLTAGE_MIN_DESIGN,
 111         POWER_SUPPLY_PROP_VOLTAGE_NOW,
 112         POWER_SUPPLY_PROP_VOLTAGE_AVG,
 113         POWER_SUPPLY_PROP_VOLTAGE_OCV,
 114         POWER_SUPPLY_PROP_VOLTAGE_BOOT,
 115         POWER_SUPPLY_PROP_CURRENT_MAX,
 116         POWER_SUPPLY_PROP_CURRENT_NOW,
 117         POWER_SUPPLY_PROP_CURRENT_AVG,
 118         POWER_SUPPLY_PROP_CURRENT_BOOT,
 119         POWER_SUPPLY_PROP_POWER_NOW,
 120         POWER_SUPPLY_PROP_POWER_AVG,
 121         POWER_SUPPLY_PROP_CHARGE_FULL_DESIGN,
 122         POWER_SUPPLY_PROP_CHARGE_EMPTY_DESIGN,
 123         POWER_SUPPLY_PROP_CHARGE_FULL,
 124         POWER_SUPPLY_PROP_CHARGE_EMPTY,
 125         POWER_SUPPLY_PROP_CHARGE_NOW,
 126         POWER_SUPPLY_PROP_CHARGE_AVG,
 127         POWER_SUPPLY_PROP_CHARGE_COUNTER,
 128         POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT,
 129         POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT_MAX,
 130         POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE,
 131         POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE_MAX,
 132         POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT,
 133         POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT_MAX,
 134         POWER_SUPPLY_PROP_CHARGE_CONTROL_START_THRESHOLD, /* in percents! */
 135         POWER_SUPPLY_PROP_CHARGE_CONTROL_END_THRESHOLD, /* in percents! */
 136         POWER_SUPPLY_PROP_CHARGE_BEHAVIOUR,
 137         POWER_SUPPLY_PROP_INPUT_CURRENT_LIMIT,
 138         POWER_SUPPLY_PROP_INPUT_VOLTAGE_LIMIT,
 139         POWER_SUPPLY_PROP_INPUT_POWER_LIMIT,
 140         POWER_SUPPLY_PROP_ENERGY_FULL_DESIGN,
 141         POWER_SUPPLY_PROP_ENERGY_EMPTY_DESIGN,
 142         POWER_SUPPLY_PROP_ENERGY_FULL,
 143         POWER_SUPPLY_PROP_ENERGY_EMPTY,
 144         POWER_SUPPLY_PROP_ENERGY_NOW,
 145         POWER_SUPPLY_PROP_ENERGY_AVG,
 146         POWER_SUPPLY_PROP_CAPACITY, /* in percents! */
 147         POWER_SUPPLY_PROP_CAPACITY_ALERT_MIN, /* in percents! */
 148         POWER_SUPPLY_PROP_CAPACITY_ALERT_MAX, /* in percents! */
 149         POWER_SUPPLY_PROP_CAPACITY_ERROR_MARGIN, /* in percents! */
 150         POWER_SUPPLY_PROP_CAPACITY_LEVEL,
 151         POWER_SUPPLY_PROP_TEMP,
 152         POWER_SUPPLY_PROP_TEMP_MAX,
 153         POWER_SUPPLY_PROP_TEMP_MIN,
 154         POWER_SUPPLY_PROP_TEMP_ALERT_MIN,
 155         POWER_SUPPLY_PROP_TEMP_ALERT_MAX,
 156         POWER_SUPPLY_PROP_TEMP_AMBIENT,
 157         POWER_SUPPLY_PROP_TEMP_AMBIENT_ALERT_MIN,
 158         POWER_SUPPLY_PROP_TEMP_AMBIENT_ALERT_MAX,
 159         POWER_SUPPLY_PROP_TIME_TO_EMPTY_NOW,
 160         POWER_SUPPLY_PROP_TIME_TO_EMPTY_AVG,
 161         POWER_SUPPLY_PROP_TIME_TO_FULL_NOW,
 162         POWER_SUPPLY_PROP_TIME_TO_FULL_AVG,
 163         POWER_SUPPLY_PROP_TYPE, /* use power_supply.type instead */
 164         POWER_SUPPLY_PROP_USB_TYPE,
 165         POWER_SUPPLY_PROP_SCOPE,
 166         POWER_SUPPLY_PROP_PRECHARGE_CURRENT,
 167         POWER_SUPPLY_PROP_CHARGE_TERM_CURRENT,
 168         POWER_SUPPLY_PROP_CALIBRATE,
 169         POWER_SUPPLY_PROP_MANUFACTURE_YEAR,
 170         POWER_SUPPLY_PROP_MANUFACTURE_MONTH,
 171         POWER_SUPPLY_PROP_MANUFACTURE_DAY,
 172         /* Properties of type `const char *' */
 173         POWER_SUPPLY_PROP_MODEL_NAME,
 174         POWER_SUPPLY_PROP_MANUFACTURER,
 175         POWER_SUPPLY_PROP_SERIAL_NUMBER,
 176 };
 177
 178 enum power_supply_type {
 179         POWER_SUPPLY_TYPE_UNKNOWN = 0,
 180         POWER_SUPPLY_TYPE_BATTERY,
 181         POWER_SUPPLY_TYPE_UPS,
 182         POWER_SUPPLY_TYPE_MAINS,
 183         POWER_SUPPLY_TYPE_USB,                  /* Standard Downstream Port */
 184         POWER_SUPPLY_TYPE_USB_DCP,              /* Dedicated Charging Port */
 185         POWER_SUPPLY_TYPE_USB_CDP,              /* Charging Downstream Port */
 186         POWER_SUPPLY_TYPE_USB_ACA,              /* Accessory Charger Adapters */
 187         POWER_SUPPLY_TYPE_USB_TYPE_C,           /* Type C Port */
 188         POWER_SUPPLY_TYPE_USB_PD,               /* Power Delivery Port */
 189         POWER_SUPPLY_TYPE_USB_PD_DRP,           /* PD Dual Role Port */
 190         POWER_SUPPLY_TYPE_APPLE_BRICK_ID,       /* Apple Charging Method */
 191         POWER_SUPPLY_TYPE_WIRELESS,             /* Wireless */
 192 };
 193
 194 enum power_supply_usb_type {
 195         POWER_SUPPLY_USB_TYPE_UNKNOWN = 0,
 196         POWER_SUPPLY_USB_TYPE_SDP,              /* Standard Downstream Port */
 197         POWER_SUPPLY_USB_TYPE_DCP,              /* Dedicated Charging Port */
 198         POWER_SUPPLY_USB_TYPE_CDP,              /* Charging Downstream Port */
 199         POWER_SUPPLY_USB_TYPE_ACA,              /* Accessory Charger Adapters */
 200         POWER_SUPPLY_USB_TYPE_C,                /* Type C Port */
 201         POWER_SUPPLY_USB_TYPE_PD,               /* Power Delivery Port */
 202         POWER_SUPPLY_USB_TYPE_PD_DRP,           /* PD Dual Role Port */
 203         POWER_SUPPLY_USB_TYPE_PD_PPS,           /* PD Programmable Power Supply */
 204         POWER_SUPPLY_USB_TYPE_APPLE_BRICK_ID,   /* Apple Charging Method */
 205 };
 206
 207 enum power_supply_charge_behaviour {
 208         POWER_SUPPLY_CHARGE_BEHAVIOUR_AUTO = 0,
 209         POWER_SUPPLY_CHARGE_BEHAVIOUR_INHIBIT_CHARGE,
 210         POWER_SUPPLY_CHARGE_BEHAVIOUR_FORCE_DISCHARGE,
 211 };
 212
 213 enum power_supply_notifier_events {
 214         PSY_EVENT_PROP_CHANGED,
 215 };
 216
 217 union power_supply_propval {
 218         int intval;
 219         const char *strval;
 220 };
 221
 222 struct device_node;
 223 struct power_supply;
 224
 225 /* Run-time specific power supply configuration */
 226 struct power_supply_config {
 227         struct device_node *of_node;
 228         struct fwnode_handle *fwnode;
 229
 230         /* Driver private data */
 231         void *drv_data;
 232
 233         /* Device specific sysfs attributes */
 234         const struct attribute_group **attr_grp;
 235
 236         char **supplied_to;
 237         size_t num_supplicants;
 238 };
 239
 240 /* Description of power supply */
 241 struct power_supply_desc {
 242         const char *name;
 243         enum power_supply_type type;
 244         const enum power_supply_usb_type *usb_types;
 245         size_t num_usb_types;
 246         const enum power_supply_property *properties;
 247         size_t num_properties;
 248
 249         /*
 250          * Functions for drivers implementing power supply class.
 251          * These shouldn't be called directly by other drivers for accessing
 252          * this power supply. Instead use power_supply_*() functions (for
 253          * example power_supply_get_property()).
 254          */
 255         int (*get_property)(struct power_supply *psy,
 256                             enum power_supply_property psp,
 257                             union power_supply_propval *val);
 258         int (*set_property)(struct power_supply *psy,
 259                             enum power_supply_property psp,
 260                             const union power_supply_propval *val);
 261         /*
 262          * property_is_writeable() will be called during registration
 263          * of power supply. If this happens during device probe then it must
 264          * not access internal data of device (because probe did not end).
 265          */
 266         int (*property_is_writeable)(struct power_supply *psy,
 267                                      enum power_supply_property psp);
 268         void (*external_power_changed)(struct power_supply *psy);
 269         void (*set_charged)(struct power_supply *psy);
 270
 271         /*
 272          * Set if thermal zone should not be created for this power supply.
 273          * For example for virtual supplies forwarding calls to actual
 274          * sensors or other supplies.
 275          */
 276         bool no_thermal;
 277         /* For APM emulation, think legacy userspace. */
 278         int use_for_apm;
 279 };
 280
 281 struct power_supply {
 282         const struct power_supply_desc *desc;
 283
 284         char **supplied_to;
 285         size_t num_supplicants;
 286
 287         char **supplied_from;
 288         size_t num_supplies;
 289         struct device_node *of_node;
 290
 291         /* Driver private data */
 292         void *drv_data;
 293
 294         /* private */
 295         struct device dev;
 296         struct work_struct changed_work;
 297         struct delayed_work deferred_register_work;
 298         spinlock_t changed_lock;
 299         bool changed;
 300         bool initialized;
 301         bool removing;
 302         atomic_t use_cnt;
 303 #ifdef CONFIG_THERMAL
 304         struct thermal_zone_device *tzd;
 305         struct thermal_cooling_device *tcd;
 306 #endif
 307
 308 #ifdef CONFIG_LEDS_TRIGGERS
 309         struct led_trigger *charging_full_trig;
 310         char *charging_full_trig_name;
 311         struct led_trigger *charging_trig;
 312         char *charging_trig_name;
 313         struct led_trigger *full_trig;
 314         char *full_trig_name;
 315         struct led_trigger *online_trig;
 316         char *online_trig_name;
 317         struct led_trigger *charging_blink_full_solid_trig;
 318         char *charging_blink_full_solid_trig_name;
 319 #endif
 320 };
 321
 322 /*
 323  * This is recommended structure to specify static power supply parameters.
 324  * Generic one, parametrizable for different power supplies. Power supply
 325  * class itself does not use it, but that's what implementing most platform
 326  * drivers, should try reuse for consistency.
 327  */
 328
 329 struct power_supply_info {
 330         const char *name;
 331         int technology;
 332         int voltage_max_design;
 333         int voltage_min_design;
 334         int charge_full_design;
 335         int charge_empty_design;
 336         int energy_full_design;
 337         int energy_empty_design;
 338         int use_for_apm;
 339 };
 340
 341 struct power_supply_battery_ocv_table {
 342         int ocv;        /* microVolts */
 343         int capacity;   /* percent */
 344 };
 345
 346 struct power_supply_resistance_temp_table {
 347         int temp;       /* celsius */
 348         int resistance; /* internal resistance percent */
 349 };
 350
 351 #define POWER_SUPPLY_OCV_TEMP_MAX 20
 352
 353 /**
 354  * struct power_supply_battery_info - information about batteries
 355  * @technology: from the POWER_SUPPLY_TECHNOLOGY_* enum
 356  * @energy_full_design_uwh: energy content when fully charged in microwatt
 357  *   hours
 358  * @charge_full_design_uah: charge content when fully charged in microampere
 359  *   hours
 360  * @voltage_min_design_uv: minimum voltage across the poles when the battery
 361  *   is at minimum voltage level in microvolts. If the voltage drops below this
 362  *   level the battery will need precharging when using CC/CV charging.
 363  * @voltage_max_design_uv: voltage across the poles when the battery is fully
 364  *   charged in microvolts. This is the "nominal voltage" i.e. the voltage
 365  *   printed on the label of the battery.
 366  * @tricklecharge_current_ua: the tricklecharge current used when trickle
 367  *   charging the battery in microamperes. This is the charging phase when the
 368  *   battery is completely empty and we need to carefully trickle in some
 369  *   charge until we reach the precharging voltage.
 370  * @precharge_current_ua: current to use in the precharge phase in microamperes,
 371  *   the precharge rate is limited by limiting the current to this value.
 372  * @precharge_voltage_max_uv: the maximum voltage allowed when precharging in
 373  *   microvolts. When we pass this voltage we will nominally switch over to the
 374  *   CC (constant current) charging phase defined by constant_charge_current_ua
 375  *   and constant_charge_voltage_max_uv.
 376  * @charge_term_current_ua: when the current in the CV (constant voltage)
 377  *   charging phase drops below this value in microamperes the charging will
 378  *   terminate completely and not restart until the voltage over the battery
 379  *   poles reach charge_restart_voltage_uv unless we use maintenance charging.
 380  * @charge_restart_voltage_uv: when the battery has been fully charged by
 381  *   CC/CV charging and charging has been disabled, and the voltage subsequently
 382  *   drops below this value in microvolts, the charging will be restarted
 383  *   (typically using CV charging).
 384  * @overvoltage_limit_uv: If the voltage exceeds the nominal voltage
 385  *   voltage_max_design_uv and we reach this voltage level, all charging must
 386  *   stop and emergency procedures take place, such as shutting down the system
 387  *   in some cases.
 388  * @constant_charge_current_max_ua: current in microamperes to use in the CC
 389  *   (constant current) charging phase. The charging rate is limited
 390  *   by this current. This is the main charging phase and as the current is
 391  *   constant into the battery the voltage slowly ascends to
 392  *   constant_charge_voltage_max_uv.
 393  * @constant_charge_voltage_max_uv: voltage in microvolts signifying the end of
 394  *   the CC (constant current) charging phase and the beginning of the CV
 395  *   (constant voltage) charging phase.
 396  * @factory_internal_resistance_uohm: the internal resistance of the battery
 397  *   at fabrication time, expressed in microohms. This resistance will vary
 398  *   depending on the lifetime and charge of the battery, so this is just a
 399  *   nominal ballpark figure.
 400  * @ocv_temp: array indicating the open circuit voltage (OCV) capacity
 401  *   temperature indices. This is an array of temperatures in degrees Celsius
 402  *   indicating which capacity table to use for a certain temperature, since
 403  *   the capacity for reasons of chemistry will be different at different
 404  *   temperatures. Determining capacity is a multivariate problem and the
 405  *   temperature is the first variable we determine.
 406  * @temp_ambient_alert_min: the battery will go outside of operating conditions
 407  *   when the ambient temperature goes below this temperature in degrees
 408  *   Celsius.
 409  * @temp_ambient_alert_max: the battery will go outside of operating conditions
 410  *   when the ambient temperature goes above this temperature in degrees
 411  *   Celsius.
 412  * @temp_alert_min: the battery should issue an alert if the internal
 413  *   temperature goes below this temperature in degrees Celsius.
 414  * @temp_alert_max: the battery should issue an alert if the internal
 415  *   temperature goes above this temperature in degrees Celsius.
 416  * @temp_min: the battery will go outside of operating conditions when
 417  *   the internal temperature goes below this temperature in degrees Celsius.
 418  *   Normally this means the system should shut down.
 419  * @temp_max: the battery will go outside of operating conditions when
 420  *   the internal temperature goes above this temperature in degrees Celsius.
 421  *   Normally this means the system should shut down.
 422  * @ocv_table: for each entry in ocv_temp there is a corresponding entry in
 423  *   ocv_table and a size for each entry in ocv_table_size. These arrays
 424  *   determine the capacity in percent in relation to the voltage in microvolts
 425  *   at the indexed temperature.
 426  * @ocv_table_size: for each entry in ocv_temp this array is giving the size of
 427  *   each entry in the array of capacity arrays in ocv_table.
 428  * @resist_table: this is a table that correlates a battery temperature to the
 429  *   expected internal resistance at this temperature. The resistance is given
 430  *   as a percentage of factory_internal_resistance_uohm. Knowing the
 431  *   resistance of the battery is usually necessary for calculating the open
 432  *   circuit voltage (OCV) that is then used with the ocv_table to calculate
 433  *   the capacity of the battery. The resist_table must be ordered descending
 434  *   by temperature: highest temperature with lowest resistance first, lowest
 435  *   temperature with highest resistance last.
 436  * @resist_table_size: the number of items in the resist_table.
 437  *
 438  * This is the recommended struct to manage static battery parameters,
 439  * populated by power_supply_get_battery_info(). Most platform drivers should
 440  * use these for consistency.
 441  *
 442  * Its field names must correspond to elements in enum power_supply_property.
 443  * The default field value is -EINVAL.
 444  *
 445  * The charging parameters here assume a CC/CV charging scheme. This method
 446  * is most common with Lithium Ion batteries (other methods are possible) and
 447  * looks as follows:
 448  *
 449  * ^ Battery voltage
 450  * |                                               --- overvoltage_limit_uv
 451  * |
 452  * |                    ...................................................
 453  * |                 .. constant_charge_voltage_max_uv
 454  * |              ..
 455  * |             .
 456  * |            .
 457  * |           .
 458  * |          .
 459  * |         .
 460  * |     .. precharge_voltage_max_uv
 461  * |  ..
 462  * |. (trickle charging)
 463  * +------------------------------------------------------------------> time
 464  *
 465  * ^ Current into the battery
 466  * |
 467  * |      ............. constant_charge_current_max_ua
 468  * |      .            .
 469  * |      .             .
 470  * |      .              .
 471  * |      .               .
 472  * |      .                ..
 473  * |      .                  ....
 474  * |      .                       .....
 475  * |    ... precharge_current_ua       .......  charge_term_current_ua
 476  * |    .                                    .
 477  * |    .                                    .
 478  * |.... tricklecharge_current_ua            .
 479  * |                                         .
 480  * +-----------------------------------------------------------------> time
 481  *
 482  * These diagrams are synchronized on time and the voltage and current
 483  * follow each other.
 484  *
 485  * With CC/CV charging commence over time like this for an empty battery:
 486  *
 487  * 1. When the battery is completely empty it may need to be charged with
 488  *    an especially small current so that electrons just "trickle in",
 489  *    this is the tricklecharge_current_ua.
 490  *
 491  * 2. Next a small initial pre-charge current (precharge_current_ua)
 492  *    is applied if the voltage is below precharge_voltage_max_uv until we
 493  *    reach precharge_voltage_max_uv. CAUTION: in some texts this is referred
 494  *    to as "trickle charging" but the use in the Linux kernel is different
 495  *    see below!
 496  *
 497  * 3. Then the main charging current is applied, which is called the constant
 498  *    current (CC) phase. A current regulator is set up to allow
 499  *    constant_charge_current_max_ua of current to flow into the battery.
 500  *    The chemical reaction in the battery will make the voltage go up as
 501  *    charge goes into the battery. This current is applied until we reach
 502  *    the constant_charge_voltage_max_uv voltage.
 503  *
 504  * 4. At this voltage we switch over to the constant voltage (CV) phase. This
 505  *    means we allow current to go into the battery, but we keep the voltage
 506  *    fixed. This current will continue to charge the battery while keeping
 507  *    the voltage the same. A chemical reaction in the battery goes on
 508  *    storing energy without affecting the voltage. Over time the current
 509  *    will slowly drop and when we reach charge_term_current_ua we will
 510  *    end the constant voltage phase.
 511  *
 512  * After this the battery is fully charged, and if we do not support maintenance
 513  * charging, the charging will not restart until power dissipation makes the
 514  * voltage fall so that we reach charge_restart_voltage_uv and at this point
 515  * we restart charging at the appropriate phase, usually this will be inside
 516  * the CV phase.
 517  *
 518  * If we support maintenance charging the voltage is however kept high after
 519  * the CV phase with a very low current. This is meant to let the same charge
 520  * go in for usage while the charger is still connected, mainly for
 521  * dissipation for the power consuming entity while connected to the
 522  * charger.
 523  *
 524  * All charging MUST terminate if the overvoltage_limit_uv is ever reached.
 525  * Overcharging Lithium Ion cells can be DANGEROUS and lead to fire or
 526  * explosions.
 527  *
 528  * The power supply class itself doesn't use this struct as of now.
 529  */
 530
 531 struct power_supply_battery_info {
 532         unsigned int technology;
 533         int energy_full_design_uwh;
 534         int charge_full_design_uah;
 535         int voltage_min_design_uv;
 536         int voltage_max_design_uv;
 537         int tricklecharge_current_ua;
 538         int precharge_current_ua;
 539         int precharge_voltage_max_uv;
 540         int charge_term_current_ua;
 541         int charge_restart_voltage_uv;
 542         int overvoltage_limit_uv;
 543         int constant_charge_current_max_ua;
 544         int constant_charge_voltage_max_uv;
 545         int factory_internal_resistance_uohm;
 546         int ocv_temp[POWER_SUPPLY_OCV_TEMP_MAX];
 547         int temp_ambient_alert_min;
 548         int temp_ambient_alert_max;
 549         int temp_alert_min;
 550         int temp_alert_max;
 551         int temp_min;
 552         int temp_max;
 553         struct power_supply_battery_ocv_table *ocv_table[POWER_SUPPLY_OCV_TEMP_MAX];
 554         int ocv_table_size[POWER_SUPPLY_OCV_TEMP_MAX];
 555         struct power_supply_resistance_temp_table *resist_table;
 556         int resist_table_size;
 557 };
 558
 559 extern struct atomic_notifier_head power_supply_notifier;
 560 extern int power_supply_reg_notifier(struct notifier_block *nb);
 561 extern void power_supply_unreg_notifier(struct notifier_block *nb);
 562 #if IS_ENABLED(CONFIG_POWER_SUPPLY)
 563 extern struct power_supply *power_supply_get_by_name(const char *name);
 564 extern void power_supply_put(struct power_supply *psy);
 565 #else
 566 static inline void power_supply_put(struct power_supply *psy) {}
 567 static inline struct power_supply *power_supply_get_by_name(const char *name)
 568 { return NULL; }
 569 #endif
 570 #ifdef CONFIG_OF
 571 extern struct power_supply *power_supply_get_by_phandle(struct device_node *np,
 572                                                         const char *property);
 573 extern struct power_supply *devm_power_supply_get_by_phandle(
 574                                     struct device *dev, const char *property);
 575 #else /* !CONFIG_OF */
 576 static inline struct power_supply *
 577 power_supply_get_by_phandle(struct device_node *np, const char *property)
 578 { return NULL; }
 579 static inline struct power_supply *
 580 devm_power_supply_get_by_phandle(struct device *dev, const char *property)
 581 { return NULL; }
 582 #endif /* CONFIG_OF */
 583
 584 extern int power_supply_get_battery_info(struct power_supply *psy,
 585                                          struct power_supply_battery_info **info_out);
 586 extern void power_supply_put_battery_info(struct power_supply *psy,
 587                                           struct power_supply_battery_info *info);
 588 extern int power_supply_ocv2cap_simple(struct power_supply_battery_ocv_table *table,
 589                                        int table_len, int ocv);
 590 extern struct power_supply_battery_ocv_table *
 591 power_supply_find_ocv2cap_table(struct power_supply_battery_info *info,
 592                                 int temp, int *table_len);
 593 extern int power_supply_batinfo_ocv2cap(struct power_supply_battery_info *info,
 594                                         int ocv, int temp);
 595 extern int
 596 power_supply_temp2resist_simple(struct power_supply_resistance_temp_table *table,
 597                                 int table_len, int temp);
 598 extern void power_supply_changed(struct power_supply *psy);
 599 extern int power_supply_am_i_supplied(struct power_supply *psy);
 600 extern int power_supply_set_input_current_limit_from_supplier(
 601                                          struct power_supply *psy);
 602 extern int power_supply_set_battery_charged(struct power_supply *psy);
 603
 604 #ifdef CONFIG_POWER_SUPPLY
 605 extern int power_supply_is_system_supplied(void);
 606 #else
 607 static inline int power_supply_is_system_supplied(void) { return -ENOSYS; }
 608 #endif
 609
 610 extern int power_supply_get_property(struct power_supply *psy,
 611                             enum power_supply_property psp,
 612                             union power_supply_propval *val);
 613 #if IS_ENABLED(CONFIG_POWER_SUPPLY)
 614 extern int power_supply_set_property(struct power_supply *psy,
 615                             enum power_supply_property psp,
 616                             const union power_supply_propval *val);
 617 #else
 618 static inline int power_supply_set_property(struct power_supply *psy,
 619                             enum power_supply_property psp,
 620                             const union power_supply_propval *val)
 621 { return 0; }
 622 #endif
 623 extern int power_supply_property_is_writeable(struct power_supply *psy,
 624                                         enum power_supply_property psp);
 625 extern void power_supply_external_power_changed(struct power_supply *psy);
 626
 627 extern struct power_supply *__must_check
 628 power_supply_register(struct device *parent,
 629                                  const struct power_supply_desc *desc,
 630                                  const struct power_supply_config *cfg);
 631 extern struct power_supply *__must_check
 632 power_supply_register_no_ws(struct device *parent,
 633                                  const struct power_supply_desc *desc,
 634                                  const struct power_supply_config *cfg);
 635 extern struct power_supply *__must_check
 636 devm_power_supply_register(struct device *parent,
 637                                  const struct power_supply_desc *desc,
 638                                  const struct power_supply_config *cfg);
 639 extern struct power_supply *__must_check
 640 devm_power_supply_register_no_ws(struct device *parent,
 641                                  const struct power_supply_desc *desc,
 642                                  const struct power_supply_config *cfg);
 643 extern void power_supply_unregister(struct power_supply *psy);
 644 extern int power_supply_powers(struct power_supply *psy, struct device *dev);
 645
 646 #define to_power_supply(device) container_of(device, struct power_supply, dev)
 647
 648 extern void *power_supply_get_drvdata(struct power_supply *psy);
 649 /* For APM emulation, think legacy userspace. */
 650 extern struct class *power_supply_class;
 651
 652 static inline bool power_supply_is_amp_property(enum power_supply_property psp)
 653 {
 654         switch (psp) {
 655         case POWER_SUPPLY_PROP_CHARGE_FULL_DESIGN:
 656         case POWER_SUPPLY_PROP_CHARGE_EMPTY_DESIGN:
 657         case POWER_SUPPLY_PROP_CHARGE_FULL:
 658         case POWER_SUPPLY_PROP_CHARGE_EMPTY:
 659         case POWER_SUPPLY_PROP_CHARGE_NOW:
 660         case POWER_SUPPLY_PROP_CHARGE_AVG:
 661         case POWER_SUPPLY_PROP_CHARGE_COUNTER:
 662         case POWER_SUPPLY_PROP_PRECHARGE_CURRENT:
 663         case POWER_SUPPLY_PROP_CHARGE_TERM_CURRENT:
 664         case POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT:
 665         case POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT_MAX:
 666         case POWER_SUPPLY_PROP_CURRENT_MAX:
 667         case POWER_SUPPLY_PROP_CURRENT_NOW:
 668         case POWER_SUPPLY_PROP_CURRENT_AVG:
 669         case POWER_SUPPLY_PROP_CURRENT_BOOT:
 670                 return true;
 671         default:
 672                 break;
 673         }
 674
 675         return false;
 676 }
 677
 678 static inline bool power_supply_is_watt_property(enum power_supply_property psp)
 679 {
 680         switch (psp) {
 681         case POWER_SUPPLY_PROP_ENERGY_FULL_DESIGN:
 682         case POWER_SUPPLY_PROP_ENERGY_EMPTY_DESIGN:
 683         case POWER_SUPPLY_PROP_ENERGY_FULL:
 684         case POWER_SUPPLY_PROP_ENERGY_EMPTY:
 685         case POWER_SUPPLY_PROP_ENERGY_NOW:
 686         case POWER_SUPPLY_PROP_ENERGY_AVG:
 687         case POWER_SUPPLY_PROP_VOLTAGE_MAX:
 688         case POWER_SUPPLY_PROP_VOLTAGE_MIN:
 689         case POWER_SUPPLY_PROP_VOLTAGE_MAX_DESIGN:
 690         case POWER_SUPPLY_PROP_VOLTAGE_MIN_DESIGN:
 691         case POWER_SUPPLY_PROP_VOLTAGE_NOW:
 692         case POWER_SUPPLY_PROP_VOLTAGE_AVG:
 693         case POWER_SUPPLY_PROP_VOLTAGE_OCV:
 694         case POWER_SUPPLY_PROP_VOLTAGE_BOOT:
 695         case POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE:
 696         case POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE_MAX:
 697         case POWER_SUPPLY_PROP_POWER_NOW:
 698                 return true;
 699         default:
 700                 break;
 701         }
 702
 703         return false;
 704 }
 705
 706 #ifdef CONFIG_POWER_SUPPLY_HWMON
 707 int power_supply_add_hwmon_sysfs(struct power_supply *psy);
 708 void power_supply_remove_hwmon_sysfs(struct power_supply *psy);
 709 #else
 710 static inline int power_supply_add_hwmon_sysfs(struct power_supply *psy)
 711 {
 712         return 0;
 713 }
 714
 715 static inline
 716 void power_supply_remove_hwmon_sysfs(struct power_supply *psy) {}
 717 #endif
 718
 719 #ifdef CONFIG_SYSFS
 720 ssize_t power_supply_charge_behaviour_show(struct device *dev,
 721                                            unsigned int available_behaviours,
 722                                            enum power_supply_charge_behaviour behaviour,
 723                                            char *buf);
 724
 725 int power_supply_charge_behaviour_parse(unsigned int available_behaviours, const char *buf);
 726 #else
 727 static inline
 728 ssize_t power_supply_charge_behaviour_show(struct device *dev,
 729                                            unsigned int available_behaviours,
 730                                            enum power_supply_charge_behaviour behaviour,
 731                                            char *buf)
 732 {
 733         return -EOPNOTSUPP;
 734 }
 735
 736 static inline int power_supply_charge_behaviour_parse(unsigned int available_behaviours,
 737                                                       const char *buf)
 738 {
 739         return -EOPNOTSUPP;
 740 }
 741 #endif
 742
 743 #endif /* __LINUX_POWER_SUPPLY_H__ */