1
Linux power supply class
2
========================
6
Power supply class used to represent battery, UPS, AC or DC power supply
7
properties to user-space.
9
It defines core set of attributes, which should be applicable to (almost)
10
every power supply out there. Attributes are available via sysfs and uevent
13
Each attribute has well defined meaning, up to unit of measure used. While
14
the attributes provided are believed to be universally applicable to any
15
power supply, specific monitoring hardware may not be able to provide them
16
all, so any of them may be skipped.
18
Power supply class is extensible, and allows to define drivers own attributes.
19
The core attribute set is subject to the standard Linux evolution (i.e.
20
if it will be found that some attribute is applicable to many power supply
21
types or their drivers, it can be added to the core set).
23
It also integrates with LED framework, for the purpose of providing
24
typically expected feedback of battery charging/fully charged status and
25
AC/USB power supply online status. (Note that specific details of the
26
indication (including whether to use it at all) are fully controllable by
27
user and/or specific machine defaults, per design principles of LED
33
Power supply class has predefined set of attributes, this eliminates code
34
duplication across drivers. Power supply class insist on reusing its
35
predefined attributes *and* their units.
37
So, userspace gets predictable set of attributes and their units for any
38
kind of power supply, and can process/present them to a user in consistent
39
manner. Results for different power supplies and machines are also directly
42
See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
43
example how to declare and handle attributes.
48
Quoting include/linux/power_supply.h:
50
All voltages, currents, charges, energies, time and temperatures in µV,
51
µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
52
stated. It's driver's job to convert its raw values to units in which
56
Attributes/properties detailed
57
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
~ ~ ~ ~ ~ ~ ~ Charge/Energy/Capacity - how to not confuse ~ ~ ~ ~ ~ ~ ~
61
~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity" ~
62
~ of battery, this class distinguish these terms. Don't mix them! ~
64
~ CHARGE_* attributes represents capacity in µAh only. ~
65
~ ENERGY_* attributes represents capacity in µWh only. ~
66
~ CAPACITY attribute represents capacity in *percents*, from 0 to 100. ~
68
~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
71
_AVG - *hardware* averaged value, use it if your hardware is really able to
72
report averaged values.
73
_NOW - momentary/instantaneous values.
75
STATUS - this attribute represents operating status (charging, full,
76
discharging (i.e. powering a load), etc.). This corresponds to
77
BATTERY_STATUS_* values, as defined in battery.h.
79
CHARGE_TYPE - batteries can typically charge at different rates.
80
This defines trickle and fast charges. For batteries that
81
are already charged or discharging, 'n/a' can be displayed (or
82
'unknown', if the status is not known).
84
HEALTH - represents health of the battery, values corresponds to
85
POWER_SUPPLY_HEALTH_*, defined in battery.h.
87
VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
88
minimal power supply voltages. Maximal/minimal means values of voltages
89
when battery considered "full"/"empty" at normal conditions. Yes, there is
90
no direct relation between voltage and battery capacity, but some dumb
91
batteries use voltage for very approximated calculation of capacity.
92
Battery driver also can use this attribute just to inform userspace
93
about maximal and minimal voltage thresholds of a given battery.
95
VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
96
these ones should be used if hardware could only guess (measure and
97
retain) the thresholds of a given power supply.
99
CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
100
battery considered full/empty.
102
ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
104
CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
105
of charge when battery became full/empty". It also could mean "value of
106
charge when battery considered full/empty at given conditions (temperature,
107
age)". I.e. these attributes represents real thresholds, not design values.
109
CHARGE_COUNTER - the current charge counter (in µAh). This could easily
110
be negative; there is no empty or full value. It is only useful for
111
relative, time-based measurements.
113
ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
115
CAPACITY - capacity in percents.
116
CAPACITY_LEVEL - capacity level. This corresponds to
117
POWER_SUPPLY_CAPACITY_LEVEL_*.
119
TEMP - temperature of the power supply.
120
TEMP_AMBIENT - ambient temperature.
122
TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
123
while battery powers a load)
124
TIME_TO_FULL - seconds left for battery to be considered full (i.e.
125
while battery is charging)
128
Battery <-> external power supply interaction
129
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
130
Often power supplies are acting as supplies and supplicants at the same
131
time. Batteries are good example. So, batteries usually care if they're
132
externally powered or not.
134
For that case, power supply class implements notification mechanism for
137
External power supply (AC) lists supplicants (batteries) names in
138
"supplied_to" struct member, and each power_supply_changed() call
139
issued by external power supply will notify supplicants via
140
external_power_changed callback.
145
Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
146
A: If you cannot find attribute suitable for your driver needs, feel free
147
to add it and send patch along with your driver.
149
The attributes available currently are the ones currently provided by the
152
Good candidates to add in future: model/part#, cycle_time, manufacturer,
156
Q: I have some very specific attribute (e.g. battery color), should I add
157
this attribute to standard ones?
158
A: Most likely, no. Such attribute can be placed in the driver itself, if
159
it is useful. Of course, if the attribute in question applicable to
160
large set of batteries, provided by many drivers, and/or comes from
161
some general battery specification/standard, it may be a candidate to
162
be added to the core attribute set.
165
Q: Suppose, my battery monitoring chip/firmware does not provides capacity
166
in percents, but provides charge_{now,full,empty}. Should I calculate
167
percentage capacity manually, inside the driver, and register CAPACITY
168
attribute? The same question about time_to_empty/time_to_full.
169
A: Most likely, no. This class is designed to export properties which are
170
directly measurable by the specific hardware available.
172
Inferring not available properties using some heuristics or mathematical
173
model is not subject of work for a battery driver. Such functionality
174
should be factored out, and in fact, apm_power, the driver to serve
175
legacy APM API on top of power supply class, uses a simple heuristic of
176
approximating remaining battery capacity based on its charge, current,
177
voltage and so on. But full-fledged battery model is likely not subject
178
for kernel at all, as it would require floating point calculation to deal
179
with things like differential equations and Kalman filters. This is
180
better be handled by batteryd/libbattery, yet to be written.