xref: /openbmc/linux/include/linux/power_supply.h (revision c94b731d)
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__ */
744