1========================
2Linux power supply class
3========================
4
5Synopsis
6~~~~~~~~
7Power supply class used to represent battery, UPS, AC or DC power supply
8properties to user-space.
9
10It defines core set of attributes, which should be applicable to (almost)
11every power supply out there. Attributes are available via sysfs and uevent
12interfaces.
13
14Each attribute has well defined meaning, up to unit of measure used. While
15the attributes provided are believed to be universally applicable to any
16power supply, specific monitoring hardware may not be able to provide them
17all, so any of them may be skipped.
18
19Power supply class is extensible, and allows to define drivers own attributes.
20The core attribute set is subject to the standard Linux evolution (i.e.
21if it will be found that some attribute is applicable to many power supply
22types or their drivers, it can be added to the core set).
23
24It also integrates with LED framework, for the purpose of providing
25typically expected feedback of battery charging/fully charged status and
26AC/USB power supply online status. (Note that specific details of the
27indication (including whether to use it at all) are fully controllable by
28user and/or specific machine defaults, per design principles of LED
29framework).
30
31
32Attributes/properties
33~~~~~~~~~~~~~~~~~~~~~
34Power supply class has predefined set of attributes, this eliminates code
35duplication across drivers. Power supply class insist on reusing its
36predefined attributes *and* their units.
37
38So, userspace gets predictable set of attributes and their units for any
39kind of power supply, and can process/present them to a user in consistent
40manner. Results for different power supplies and machines are also directly
41comparable.
42
43See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
44for the example how to declare and handle attributes.
45
46
47Units
48~~~~~
49Quoting include/linux/power_supply.h:
50
51  All voltages, currents, charges, energies, time and temperatures in µV,
52  µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
53  stated. It's driver's job to convert its raw values to units in which
54  this class operates.
55
56
57Attributes/properties detailed
58~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
60+--------------------------------------------------------------------------+
61|               **Charge/Energy/Capacity - how to not confuse**            |
62+--------------------------------------------------------------------------+
63| **Because both "charge" (µAh) and "energy" (µWh) represents "capacity"   |
64| of battery, this class distinguish these terms. Don't mix them!**        |
65|                                                                          |
66| - `CHARGE_*`                                                             |
67|	attributes represents capacity in µAh only.                        |
68| - `ENERGY_*`                                                             |
69|	attributes represents capacity in µWh only.                        |
70| - `CAPACITY`                                                             |
71|	attribute represents capacity in *percents*, from 0 to 100.        |
72+--------------------------------------------------------------------------+
73
74Postfixes:
75
76_AVG
77  *hardware* averaged value, use it if your hardware is really able to
78  report averaged values.
79_NOW
80  momentary/instantaneous values.
81
82STATUS
83  this attribute represents operating status (charging, full,
84  discharging (i.e. powering a load), etc.). This corresponds to
85  `BATTERY_STATUS_*` values, as defined in battery.h.
86
87CHARGE_TYPE
88  batteries can typically charge at different rates.
89  This defines trickle and fast charges.  For batteries that
90  are already charged or discharging, 'n/a' can be displayed (or
91  'unknown', if the status is not known).
92
93AUTHENTIC
94  indicates the power supply (battery or charger) connected
95  to the platform is authentic(1) or non authentic(0).
96
97HEALTH
98  represents health of the battery, values corresponds to
99  POWER_SUPPLY_HEALTH_*, defined in battery.h.
100
101VOLTAGE_OCV
102  open circuit voltage of the battery.
103
104VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN
105  design values for maximal and minimal power supply voltages.
106  Maximal/minimal means values of voltages when battery considered
107  "full"/"empty" at normal conditions. Yes, there is no direct relation
108  between voltage and battery capacity, but some dumb
109  batteries use voltage for very approximated calculation of capacity.
110  Battery driver also can use this attribute just to inform userspace
111  about maximal and minimal voltage thresholds of a given battery.
112
113VOLTAGE_MAX, VOLTAGE_MIN
114  same as _DESIGN voltage values except that these ones should be used
115  if hardware could only guess (measure and retain) the thresholds of a
116  given power supply.
117
118VOLTAGE_BOOT
119  Reports the voltage measured during boot
120
121CURRENT_BOOT
122  Reports the current measured during boot
123
124CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN
125  design charge values, when battery considered full/empty.
126
127ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN
128  same as above but for energy.
129
130CHARGE_FULL, CHARGE_EMPTY
131  These attributes means "last remembered value of charge when battery
132  became full/empty". It also could mean "value of charge when battery
133  considered full/empty at given conditions (temperature, age)".
134  I.e. these attributes represents real thresholds, not design values.
135
136ENERGY_FULL, ENERGY_EMPTY
137  same as above but for energy.
138
139CHARGE_COUNTER
140  the current charge counter (in µAh).  This could easily
141  be negative; there is no empty or full value.  It is only useful for
142  relative, time-based measurements.
143
144PRECHARGE_CURRENT
145  the maximum charge current during precharge phase of charge cycle
146  (typically 20% of battery capacity).
147
148CHARGE_TERM_CURRENT
149  Charge termination current. The charge cycle terminates when battery
150  voltage is above recharge threshold, and charge current is below
151  this setting (typically 10% of battery capacity).
152
153CONSTANT_CHARGE_CURRENT
154  constant charge current programmed by charger.
155
156
157CONSTANT_CHARGE_CURRENT_MAX
158  maximum charge current supported by the power supply object.
159
160CONSTANT_CHARGE_VOLTAGE
161  constant charge voltage programmed by charger.
162CONSTANT_CHARGE_VOLTAGE_MAX
163  maximum charge voltage supported by the power supply object.
164
165INPUT_CURRENT_LIMIT
166  input current limit programmed by charger. Indicates
167  the current drawn from a charging source.
168INPUT_VOLTAGE_LIMIT
169  input voltage limit programmed by charger. Indicates
170  the voltage limit from a charging source.
171INPUT_POWER_LIMIT
172  input power limit programmed by charger. Indicates
173  the power limit from a charging source.
174
175CHARGE_CONTROL_LIMIT
176  current charge control limit setting
177CHARGE_CONTROL_LIMIT_MAX
178  maximum charge control limit setting
179
180CALIBRATE
181  battery or coulomb counter calibration status
182
183CAPACITY
184  capacity in percents.
185CAPACITY_ALERT_MIN
186  minimum capacity alert value in percents.
187CAPACITY_ALERT_MAX
188  maximum capacity alert value in percents.
189CAPACITY_LEVEL
190  capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*.
191
192TEMP
193  temperature of the power supply.
194TEMP_ALERT_MIN
195  minimum battery temperature alert.
196TEMP_ALERT_MAX
197  maximum battery temperature alert.
198TEMP_AMBIENT
199  ambient temperature.
200TEMP_AMBIENT_ALERT_MIN
201  minimum ambient temperature alert.
202TEMP_AMBIENT_ALERT_MAX
203  maximum ambient temperature alert.
204TEMP_MIN
205  minimum operatable temperature
206TEMP_MAX
207  maximum operatable temperature
208
209TIME_TO_EMPTY
210  seconds left for battery to be considered empty
211  (i.e. while battery powers a load)
212TIME_TO_FULL
213  seconds left for battery to be considered full
214  (i.e. while battery is charging)
215
216
217Battery <-> external power supply interaction
218~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219Often power supplies are acting as supplies and supplicants at the same
220time. Batteries are good example. So, batteries usually care if they're
221externally powered or not.
222
223For that case, power supply class implements notification mechanism for
224batteries.
225
226External power supply (AC) lists supplicants (batteries) names in
227"supplied_to" struct member, and each power_supply_changed() call
228issued by external power supply will notify supplicants via
229external_power_changed callback.
230
231
232Devicetree battery characteristics
233~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
234Drivers should call power_supply_get_battery_info() to obtain battery
235characteristics from a devicetree battery node, defined in
236Documentation/devicetree/bindings/power/supply/battery.yaml. This is
237implemented in drivers/power/supply/bq27xxx_battery.c.
238
239Properties in struct power_supply_battery_info and their counterparts in the
240battery node have names corresponding to elements in enum power_supply_property,
241for naming consistency between sysfs attributes and battery node properties.
242
243
244QA
245~~
246
247Q:
248   Where is POWER_SUPPLY_PROP_XYZ attribute?
249A:
250   If you cannot find attribute suitable for your driver needs, feel free
251   to add it and send patch along with your driver.
252
253   The attributes available currently are the ones currently provided by the
254   drivers written.
255
256   Good candidates to add in future: model/part#, cycle_time, manufacturer,
257   etc.
258
259
260Q:
261   I have some very specific attribute (e.g. battery color), should I add
262   this attribute to standard ones?
263A:
264   Most likely, no. Such attribute can be placed in the driver itself, if
265   it is useful. Of course, if the attribute in question applicable to
266   large set of batteries, provided by many drivers, and/or comes from
267   some general battery specification/standard, it may be a candidate to
268   be added to the core attribute set.
269
270
271Q:
272   Suppose, my battery monitoring chip/firmware does not provides capacity
273   in percents, but provides charge_{now,full,empty}. Should I calculate
274   percentage capacity manually, inside the driver, and register CAPACITY
275   attribute? The same question about time_to_empty/time_to_full.
276A:
277   Most likely, no. This class is designed to export properties which are
278   directly measurable by the specific hardware available.
279
280   Inferring not available properties using some heuristics or mathematical
281   model is not subject of work for a battery driver. Such functionality
282   should be factored out, and in fact, apm_power, the driver to serve
283   legacy APM API on top of power supply class, uses a simple heuristic of
284   approximating remaining battery capacity based on its charge, current,
285   voltage and so on. But full-fledged battery model is likely not subject
286   for kernel at all, as it would require floating point calculation to deal
287   with things like differential equations and Kalman filters. This is
288   better be handled by batteryd/libbattery, yet to be written.
289