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 };
  52
  53 enum {
  54         POWER_SUPPLY_HEALTH_UNKNOWN = 0,
  55         POWER_SUPPLY_HEALTH_GOOD,
  56         POWER_SUPPLY_HEALTH_OVERHEAT,
  57         POWER_SUPPLY_HEALTH_DEAD,
  58         POWER_SUPPLY_HEALTH_OVERVOLTAGE,
  59         POWER_SUPPLY_HEALTH_UNSPEC_FAILURE,
  60         POWER_SUPPLY_HEALTH_COLD,
  61         POWER_SUPPLY_HEALTH_WATCHDOG_TIMER_EXPIRE,
  62         POWER_SUPPLY_HEALTH_SAFETY_TIMER_EXPIRE,
  63         POWER_SUPPLY_HEALTH_OVERCURRENT,
  64 };
  65
  66 enum {
  67         POWER_SUPPLY_TECHNOLOGY_UNKNOWN = 0,
  68         POWER_SUPPLY_TECHNOLOGY_NiMH,
  69         POWER_SUPPLY_TECHNOLOGY_LION,
  70         POWER_SUPPLY_TECHNOLOGY_LIPO,
  71         POWER_SUPPLY_TECHNOLOGY_LiFe,
  72         POWER_SUPPLY_TECHNOLOGY_NiCd,
  73         POWER_SUPPLY_TECHNOLOGY_LiMn,
  74 };
  75
  76 enum {
  77         POWER_SUPPLY_CAPACITY_LEVEL_UNKNOWN = 0,
  78         POWER_SUPPLY_CAPACITY_LEVEL_CRITICAL,
  79         POWER_SUPPLY_CAPACITY_LEVEL_LOW,
  80         POWER_SUPPLY_CAPACITY_LEVEL_NORMAL,
  81         POWER_SUPPLY_CAPACITY_LEVEL_HIGH,
  82         POWER_SUPPLY_CAPACITY_LEVEL_FULL,
  83 };
  84
  85 enum {
  86         POWER_SUPPLY_SCOPE_UNKNOWN = 0,
  87         POWER_SUPPLY_SCOPE_SYSTEM,
  88         POWER_SUPPLY_SCOPE_DEVICE,
  89 };
  90
  91 enum power_supply_property {
  92         /* Properties of type `int' */
  93         POWER_SUPPLY_PROP_STATUS = 0,
  94         POWER_SUPPLY_PROP_CHARGE_TYPE,
  95         POWER_SUPPLY_PROP_HEALTH,
  96         POWER_SUPPLY_PROP_PRESENT,
  97         POWER_SUPPLY_PROP_ONLINE,
  98         POWER_SUPPLY_PROP_AUTHENTIC,
  99         POWER_SUPPLY_PROP_TECHNOLOGY,
 100         POWER_SUPPLY_PROP_CYCLE_COUNT,
 101         POWER_SUPPLY_PROP_VOLTAGE_MAX,
 102         POWER_SUPPLY_PROP_VOLTAGE_MIN,
 103         POWER_SUPPLY_PROP_VOLTAGE_MAX_DESIGN,
 104         POWER_SUPPLY_PROP_VOLTAGE_MIN_DESIGN,
 105         POWER_SUPPLY_PROP_VOLTAGE_NOW,
 106         POWER_SUPPLY_PROP_VOLTAGE_AVG,
 107         POWER_SUPPLY_PROP_VOLTAGE_OCV,
 108         POWER_SUPPLY_PROP_VOLTAGE_BOOT,
 109         POWER_SUPPLY_PROP_CURRENT_MAX,
 110         POWER_SUPPLY_PROP_CURRENT_NOW,
 111         POWER_SUPPLY_PROP_CURRENT_AVG,
 112         POWER_SUPPLY_PROP_CURRENT_BOOT,
 113         POWER_SUPPLY_PROP_POWER_NOW,
 114         POWER_SUPPLY_PROP_POWER_AVG,
 115         POWER_SUPPLY_PROP_CHARGE_FULL_DESIGN,
 116         POWER_SUPPLY_PROP_CHARGE_EMPTY_DESIGN,
 117         POWER_SUPPLY_PROP_CHARGE_FULL,
 118         POWER_SUPPLY_PROP_CHARGE_EMPTY,
 119         POWER_SUPPLY_PROP_CHARGE_NOW,
 120         POWER_SUPPLY_PROP_CHARGE_AVG,
 121         POWER_SUPPLY_PROP_CHARGE_COUNTER,
 122         POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT,
 123         POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT_MAX,
 124         POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE,
 125         POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE_MAX,
 126         POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT,
 127         POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT_MAX,
 128         POWER_SUPPLY_PROP_CHARGE_CONTROL_START_THRESHOLD, /* in percents! */
 129         POWER_SUPPLY_PROP_CHARGE_CONTROL_END_THRESHOLD, /* in percents! */
 130         POWER_SUPPLY_PROP_INPUT_CURRENT_LIMIT,
 131         POWER_SUPPLY_PROP_ENERGY_FULL_DESIGN,
 132         POWER_SUPPLY_PROP_ENERGY_EMPTY_DESIGN,
 133         POWER_SUPPLY_PROP_ENERGY_FULL,
 134         POWER_SUPPLY_PROP_ENERGY_EMPTY,
 135         POWER_SUPPLY_PROP_ENERGY_NOW,
 136         POWER_SUPPLY_PROP_ENERGY_AVG,
 137         POWER_SUPPLY_PROP_CAPACITY, /* in percents! */
 138         POWER_SUPPLY_PROP_CAPACITY_ALERT_MIN, /* in percents! */
 139         POWER_SUPPLY_PROP_CAPACITY_ALERT_MAX, /* in percents! */
 140         POWER_SUPPLY_PROP_CAPACITY_LEVEL,
 141         POWER_SUPPLY_PROP_TEMP,
 142         POWER_SUPPLY_PROP_TEMP_MAX,
 143         POWER_SUPPLY_PROP_TEMP_MIN,
 144         POWER_SUPPLY_PROP_TEMP_ALERT_MIN,
 145         POWER_SUPPLY_PROP_TEMP_ALERT_MAX,
 146         POWER_SUPPLY_PROP_TEMP_AMBIENT,
 147         POWER_SUPPLY_PROP_TEMP_AMBIENT_ALERT_MIN,
 148         POWER_SUPPLY_PROP_TEMP_AMBIENT_ALERT_MAX,
 149         POWER_SUPPLY_PROP_TIME_TO_EMPTY_NOW,
 150         POWER_SUPPLY_PROP_TIME_TO_EMPTY_AVG,
 151         POWER_SUPPLY_PROP_TIME_TO_FULL_NOW,
 152         POWER_SUPPLY_PROP_TIME_TO_FULL_AVG,
 153         POWER_SUPPLY_PROP_TYPE, /* use power_supply.type instead */
 154         POWER_SUPPLY_PROP_USB_TYPE,
 155         POWER_SUPPLY_PROP_SCOPE,
 156         POWER_SUPPLY_PROP_PRECHARGE_CURRENT,
 157         POWER_SUPPLY_PROP_CHARGE_TERM_CURRENT,
 158         POWER_SUPPLY_PROP_CALIBRATE,
 159         /* Properties of type `const char *' */
 160         POWER_SUPPLY_PROP_MODEL_NAME,
 161         POWER_SUPPLY_PROP_MANUFACTURER,
 162         POWER_SUPPLY_PROP_SERIAL_NUMBER,
 163 };
 164
 165 enum power_supply_type {
 166         POWER_SUPPLY_TYPE_UNKNOWN = 0,
 167         POWER_SUPPLY_TYPE_BATTERY,
 168         POWER_SUPPLY_TYPE_UPS,
 169         POWER_SUPPLY_TYPE_MAINS,
 170         POWER_SUPPLY_TYPE_USB,                  /* Standard Downstream Port */
 171         POWER_SUPPLY_TYPE_USB_DCP,              /* Dedicated Charging Port */
 172         POWER_SUPPLY_TYPE_USB_CDP,              /* Charging Downstream Port */
 173         POWER_SUPPLY_TYPE_USB_ACA,              /* Accessory Charger Adapters */
 174         POWER_SUPPLY_TYPE_USB_TYPE_C,           /* Type C Port */
 175         POWER_SUPPLY_TYPE_USB_PD,               /* Power Delivery Port */
 176         POWER_SUPPLY_TYPE_USB_PD_DRP,           /* PD Dual Role Port */
 177         POWER_SUPPLY_TYPE_APPLE_BRICK_ID,       /* Apple Charging Method */
 178 };
 179
 180 enum power_supply_usb_type {
 181         POWER_SUPPLY_USB_TYPE_UNKNOWN = 0,
 182         POWER_SUPPLY_USB_TYPE_SDP,              /* Standard Downstream Port */
 183         POWER_SUPPLY_USB_TYPE_DCP,              /* Dedicated Charging Port */
 184         POWER_SUPPLY_USB_TYPE_CDP,              /* Charging Downstream Port */
 185         POWER_SUPPLY_USB_TYPE_ACA,              /* Accessory Charger Adapters */
 186         POWER_SUPPLY_USB_TYPE_C,                /* Type C Port */
 187         POWER_SUPPLY_USB_TYPE_PD,               /* Power Delivery Port */
 188         POWER_SUPPLY_USB_TYPE_PD_DRP,           /* PD Dual Role Port */
 189         POWER_SUPPLY_USB_TYPE_PD_PPS,           /* PD Programmable Power Supply */
 190         POWER_SUPPLY_USB_TYPE_APPLE_BRICK_ID,   /* Apple Charging Method */
 191 };
 192
 193 enum power_supply_notifier_events {
 194         PSY_EVENT_PROP_CHANGED,
 195 };
 196
 197 union power_supply_propval {
 198         int intval;
 199         const char *strval;
 200 };
 201
 202 struct device_node;
 203 struct power_supply;
 204
 205 /* Run-time specific power supply configuration */
 206 struct power_supply_config {
 207         struct device_node *of_node;
 208         struct fwnode_handle *fwnode;
 209
 210         /* Driver private data */
 211         void *drv_data;
 212
 213         /* Device specific sysfs attributes */
 214         const struct attribute_group **attr_grp;
 215
 216         char **supplied_to;
 217         size_t num_supplicants;
 218 };
 219
 220 /* Description of power supply */
 221 struct power_supply_desc {
 222         const char *name;
 223         enum power_supply_type type;
 224         enum power_supply_usb_type *usb_types;
 225         size_t num_usb_types;
 226         enum power_supply_property *properties;
 227         size_t num_properties;
 228
 229         /*
 230          * Functions for drivers implementing power supply class.
 231          * These shouldn't be called directly by other drivers for accessing
 232          * this power supply. Instead use power_supply_*() functions (for
 233          * example power_supply_get_property()).
 234          */
 235         int (*get_property)(struct power_supply *psy,
 236                             enum power_supply_property psp,
 237                             union power_supply_propval *val);
 238         int (*set_property)(struct power_supply *psy,
 239                             enum power_supply_property psp,
 240                             const union power_supply_propval *val);
 241         /*
 242          * property_is_writeable() will be called during registration
 243          * of power supply. If this happens during device probe then it must
 244          * not access internal data of device (because probe did not end).
 245          */
 246         int (*property_is_writeable)(struct power_supply *psy,
 247                                      enum power_supply_property psp);
 248         void (*external_power_changed)(struct power_supply *psy);
 249         void (*set_charged)(struct power_supply *psy);
 250
 251         /*
 252          * Set if thermal zone should not be created for this power supply.
 253          * For example for virtual supplies forwarding calls to actual
 254          * sensors or other supplies.
 255          */
 256         bool no_thermal;
 257         /* For APM emulation, think legacy userspace. */
 258         int use_for_apm;
 259 };
 260
 261 struct power_supply {
 262         const struct power_supply_desc *desc;
 263
 264         char **supplied_to;
 265         size_t num_supplicants;
 266
 267         char **supplied_from;
 268         size_t num_supplies;
 269         struct device_node *of_node;
 270
 271         /* Driver private data */
 272         void *drv_data;
 273
 274         /* private */
 275         struct device dev;
 276         struct work_struct changed_work;
 277         struct delayed_work deferred_register_work;
 278         spinlock_t changed_lock;
 279         bool changed;
 280         bool initialized;
 281         bool removing;
 282         atomic_t use_cnt;
 283 #ifdef CONFIG_THERMAL
 284         struct thermal_zone_device *tzd;
 285         struct thermal_cooling_device *tcd;
 286 #endif
 287
 288 #ifdef CONFIG_LEDS_TRIGGERS
 289         struct led_trigger *charging_full_trig;
 290         char *charging_full_trig_name;
 291         struct led_trigger *charging_trig;
 292         char *charging_trig_name;
 293         struct led_trigger *full_trig;
 294         char *full_trig_name;
 295         struct led_trigger *online_trig;
 296         char *online_trig_name;
 297         struct led_trigger *charging_blink_full_solid_trig;
 298         char *charging_blink_full_solid_trig_name;
 299 #endif
 300 };
 301
 302 /*
 303  * This is recommended structure to specify static power supply parameters.
 304  * Generic one, parametrizable for different power supplies. Power supply
 305  * class itself does not use it, but that's what implementing most platform
 306  * drivers, should try reuse for consistency.
 307  */
 308
 309 struct power_supply_info {
 310         const char *name;
 311         int technology;
 312         int voltage_max_design;
 313         int voltage_min_design;
 314         int charge_full_design;
 315         int charge_empty_design;
 316         int energy_full_design;
 317         int energy_empty_design;
 318         int use_for_apm;
 319 };
 320
 321 struct power_supply_battery_ocv_table {
 322         int ocv;        /* microVolts */
 323         int capacity;   /* percent */
 324 };
 325
 326 #define POWER_SUPPLY_OCV_TEMP_MAX 20
 327
 328 /*
 329  * This is the recommended struct to manage static battery parameters,
 330  * populated by power_supply_get_battery_info(). Most platform drivers should
 331  * use these for consistency.
 332  * Its field names must correspond to elements in enum power_supply_property.
 333  * The default field value is -EINVAL.
 334  * Power supply class itself doesn't use this.
 335  */
 336
 337 struct power_supply_battery_info {
 338         int energy_full_design_uwh;         /* microWatt-hours */
 339         int charge_full_design_uah;         /* microAmp-hours */
 340         int voltage_min_design_uv;          /* microVolts */
 341         int voltage_max_design_uv;          /* microVolts */
 342         int precharge_current_ua;           /* microAmps */
 343         int charge_term_current_ua;         /* microAmps */
 344         int constant_charge_current_max_ua; /* microAmps */
 345         int constant_charge_voltage_max_uv; /* microVolts */
 346         int factory_internal_resistance_uohm;   /* microOhms */
 347         int ocv_temp[POWER_SUPPLY_OCV_TEMP_MAX];/* celsius */
 348         struct power_supply_battery_ocv_table *ocv_table[POWER_SUPPLY_OCV_TEMP_MAX];
 349         int ocv_table_size[POWER_SUPPLY_OCV_TEMP_MAX];
 350 };
 351
 352 extern struct atomic_notifier_head power_supply_notifier;
 353 extern int power_supply_reg_notifier(struct notifier_block *nb);
 354 extern void power_supply_unreg_notifier(struct notifier_block *nb);
 355 extern struct power_supply *power_supply_get_by_name(const char *name);
 356 extern void power_supply_put(struct power_supply *psy);
 357 #ifdef CONFIG_OF
 358 extern struct power_supply *power_supply_get_by_phandle(struct device_node *np,
 359                                                         const char *property);
 360 extern struct power_supply *devm_power_supply_get_by_phandle(
 361                                     struct device *dev, const char *property);
 362 #else /* !CONFIG_OF */
 363 static inline struct power_supply *
 364 power_supply_get_by_phandle(struct device_node *np, const char *property)
 365 { return NULL; }
 366 static inline struct power_supply *
 367 devm_power_supply_get_by_phandle(struct device *dev, const char *property)
 368 { return NULL; }
 369 #endif /* CONFIG_OF */
 370
 371 extern int power_supply_get_battery_info(struct power_supply *psy,
 372                                          struct power_supply_battery_info *info);
 373 extern void power_supply_put_battery_info(struct power_supply *psy,
 374                                           struct power_supply_battery_info *info);
 375 extern int power_supply_ocv2cap_simple(struct power_supply_battery_ocv_table *table,
 376                                        int table_len, int ocv);
 377 extern struct power_supply_battery_ocv_table *
 378 power_supply_find_ocv2cap_table(struct power_supply_battery_info *info,
 379                                 int temp, int *table_len);
 380 extern int power_supply_batinfo_ocv2cap(struct power_supply_battery_info *info,
 381                                         int ocv, int temp);
 382 extern void power_supply_changed(struct power_supply *psy);
 383 extern int power_supply_am_i_supplied(struct power_supply *psy);
 384 extern int power_supply_set_input_current_limit_from_supplier(
 385                                          struct power_supply *psy);
 386 extern int power_supply_set_battery_charged(struct power_supply *psy);
 387
 388 #ifdef CONFIG_POWER_SUPPLY
 389 extern int power_supply_is_system_supplied(void);
 390 #else
 391 static inline int power_supply_is_system_supplied(void) { return -ENOSYS; }
 392 #endif
 393
 394 extern int power_supply_get_property(struct power_supply *psy,
 395                             enum power_supply_property psp,
 396                             union power_supply_propval *val);
 397 extern int power_supply_set_property(struct power_supply *psy,
 398                             enum power_supply_property psp,
 399                             const union power_supply_propval *val);
 400 extern int power_supply_property_is_writeable(struct power_supply *psy,
 401                                         enum power_supply_property psp);
 402 extern void power_supply_external_power_changed(struct power_supply *psy);
 403
 404 extern struct power_supply *__must_check
 405 power_supply_register(struct device *parent,
 406                                  const struct power_supply_desc *desc,
 407                                  const struct power_supply_config *cfg);
 408 extern struct power_supply *__must_check
 409 power_supply_register_no_ws(struct device *parent,
 410                                  const struct power_supply_desc *desc,
 411                                  const struct power_supply_config *cfg);
 412 extern struct power_supply *__must_check
 413 devm_power_supply_register(struct device *parent,
 414                                  const struct power_supply_desc *desc,
 415                                  const struct power_supply_config *cfg);
 416 extern struct power_supply *__must_check
 417 devm_power_supply_register_no_ws(struct device *parent,
 418                                  const struct power_supply_desc *desc,
 419                                  const struct power_supply_config *cfg);
 420 extern void power_supply_unregister(struct power_supply *psy);
 421 extern int power_supply_powers(struct power_supply *psy, struct device *dev);
 422
 423 #define to_power_supply(device) container_of(device, struct power_supply, dev)
 424
 425 extern void *power_supply_get_drvdata(struct power_supply *psy);
 426 /* For APM emulation, think legacy userspace. */
 427 extern struct class *power_supply_class;
 428
 429 static inline bool power_supply_is_amp_property(enum power_supply_property psp)
 430 {
 431         switch (psp) {
 432         case POWER_SUPPLY_PROP_CHARGE_FULL_DESIGN:
 433         case POWER_SUPPLY_PROP_CHARGE_EMPTY_DESIGN:
 434         case POWER_SUPPLY_PROP_CHARGE_FULL:
 435         case POWER_SUPPLY_PROP_CHARGE_EMPTY:
 436         case POWER_SUPPLY_PROP_CHARGE_NOW:
 437         case POWER_SUPPLY_PROP_CHARGE_AVG:
 438         case POWER_SUPPLY_PROP_CHARGE_COUNTER:
 439         case POWER_SUPPLY_PROP_PRECHARGE_CURRENT:
 440         case POWER_SUPPLY_PROP_CHARGE_TERM_CURRENT:
 441         case POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT:
 442         case POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT_MAX:
 443         case POWER_SUPPLY_PROP_CURRENT_MAX:
 444         case POWER_SUPPLY_PROP_CURRENT_NOW:
 445         case POWER_SUPPLY_PROP_CURRENT_AVG:
 446         case POWER_SUPPLY_PROP_CURRENT_BOOT:
 447                 return 1;
 448         default:
 449                 break;
 450         }
 451
 452         return 0;
 453 }
 454
 455 static inline bool power_supply_is_watt_property(enum power_supply_property psp)
 456 {
 457         switch (psp) {
 458         case POWER_SUPPLY_PROP_ENERGY_FULL_DESIGN:
 459         case POWER_SUPPLY_PROP_ENERGY_EMPTY_DESIGN:
 460         case POWER_SUPPLY_PROP_ENERGY_FULL:
 461         case POWER_SUPPLY_PROP_ENERGY_EMPTY:
 462         case POWER_SUPPLY_PROP_ENERGY_NOW:
 463         case POWER_SUPPLY_PROP_ENERGY_AVG:
 464         case POWER_SUPPLY_PROP_VOLTAGE_MAX:
 465         case POWER_SUPPLY_PROP_VOLTAGE_MIN:
 466         case POWER_SUPPLY_PROP_VOLTAGE_MAX_DESIGN:
 467         case POWER_SUPPLY_PROP_VOLTAGE_MIN_DESIGN:
 468         case POWER_SUPPLY_PROP_VOLTAGE_NOW:
 469         case POWER_SUPPLY_PROP_VOLTAGE_AVG:
 470         case POWER_SUPPLY_PROP_VOLTAGE_OCV:
 471         case POWER_SUPPLY_PROP_VOLTAGE_BOOT:
 472         case POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE:
 473         case POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE_MAX:
 474         case POWER_SUPPLY_PROP_POWER_NOW:
 475                 return 1;
 476         default:
 477                 break;
 478         }
 479
 480         return 0;
 481 }
 482
 483 #endif /* __LINUX_POWER_SUPPLY_H__ */