1 |
3 |
xianfeng |
Linux power supply class
|
2 |
|
|
========================
|
3 |
|
|
|
4 |
|
|
Synopsis
|
5 |
|
|
~~~~~~~~
|
6 |
|
|
Power supply class used to represent battery, UPS, AC or DC power supply
|
7 |
|
|
properties to user-space.
|
8 |
|
|
|
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
|
11 |
|
|
interfaces.
|
12 |
|
|
|
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.
|
17 |
|
|
|
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).
|
22 |
|
|
|
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
|
28 |
|
|
framework).
|
29 |
|
|
|
30 |
|
|
|
31 |
|
|
Attributes/properties
|
32 |
|
|
~~~~~~~~~~~~~~~~~~~~~
|
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.
|
36 |
|
|
|
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
|
40 |
|
|
comparable.
|
41 |
|
|
|
42 |
|
|
See drivers/power/ds2760_battery.c and drivers/power/pda_power.c for the
|
43 |
|
|
example how to declare and handle attributes.
|
44 |
|
|
|
45 |
|
|
|
46 |
|
|
Units
|
47 |
|
|
~~~~~
|
48 |
|
|
Quoting include/linux/power_supply.h:
|
49 |
|
|
|
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
|
53 |
|
|
this class operates.
|
54 |
|
|
|
55 |
|
|
|
56 |
|
|
Attributes/properties detailed
|
57 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
58 |
|
|
|
59 |
|
|
~ ~ ~ ~ ~ ~ ~ Charge/Energy/Capacity - how to not confuse ~ ~ ~ ~ ~ ~ ~
|
60 |
|
|
~ ~
|
61 |
|
|
~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity" ~
|
62 |
|
|
~ of battery, this class distinguish these terms. Don't mix them! ~
|
63 |
|
|
~ ~
|
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. ~
|
67 |
|
|
~ ~
|
68 |
|
|
~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
|
69 |
|
|
|
70 |
|
|
Postfixes:
|
71 |
|
|
_AVG - *hardware* averaged value, use it if your hardware is really able to
|
72 |
|
|
report averaged values.
|
73 |
|
|
_NOW - momentary/instantaneous values.
|
74 |
|
|
|
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.
|
78 |
|
|
|
79 |
|
|
HEALTH - represents health of the battery, values corresponds to
|
80 |
|
|
POWER_SUPPLY_HEALTH_*, defined in battery.h.
|
81 |
|
|
|
82 |
|
|
VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
|
83 |
|
|
minimal power supply voltages. Maximal/minimal means values of voltages
|
84 |
|
|
when battery considered "full"/"empty" at normal conditions. Yes, there is
|
85 |
|
|
no direct relation between voltage and battery capacity, but some dumb
|
86 |
|
|
batteries use voltage for very approximated calculation of capacity.
|
87 |
|
|
Battery driver also can use this attribute just to inform userspace
|
88 |
|
|
about maximal and minimal voltage thresholds of a given battery.
|
89 |
|
|
|
90 |
|
|
CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
|
91 |
|
|
battery considered full/empty.
|
92 |
|
|
|
93 |
|
|
ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
|
94 |
|
|
|
95 |
|
|
CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
|
96 |
|
|
of charge when battery became full/empty". It also could mean "value of
|
97 |
|
|
charge when battery considered full/empty at given conditions (temperature,
|
98 |
|
|
age)". I.e. these attributes represents real thresholds, not design values.
|
99 |
|
|
|
100 |
|
|
ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
|
101 |
|
|
|
102 |
|
|
CAPACITY - capacity in percents.
|
103 |
|
|
CAPACITY_LEVEL - capacity level. This corresponds to
|
104 |
|
|
POWER_SUPPLY_CAPACITY_LEVEL_*.
|
105 |
|
|
|
106 |
|
|
TEMP - temperature of the power supply.
|
107 |
|
|
TEMP_AMBIENT - ambient temperature.
|
108 |
|
|
|
109 |
|
|
TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
|
110 |
|
|
while battery powers a load)
|
111 |
|
|
TIME_TO_FULL - seconds left for battery to be considered full (i.e.
|
112 |
|
|
while battery is charging)
|
113 |
|
|
|
114 |
|
|
|
115 |
|
|
Battery <-> external power supply interaction
|
116 |
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
117 |
|
|
Often power supplies are acting as supplies and supplicants at the same
|
118 |
|
|
time. Batteries are good example. So, batteries usually care if they're
|
119 |
|
|
externally powered or not.
|
120 |
|
|
|
121 |
|
|
For that case, power supply class implements notification mechanism for
|
122 |
|
|
batteries.
|
123 |
|
|
|
124 |
|
|
External power supply (AC) lists supplicants (batteries) names in
|
125 |
|
|
"supplied_to" struct member, and each power_supply_changed() call
|
126 |
|
|
issued by external power supply will notify supplicants via
|
127 |
|
|
external_power_changed callback.
|
128 |
|
|
|
129 |
|
|
|
130 |
|
|
QA
|
131 |
|
|
~~
|
132 |
|
|
Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
|
133 |
|
|
A: If you cannot find attribute suitable for your driver needs, feel free
|
134 |
|
|
to add it and send patch along with your driver.
|
135 |
|
|
|
136 |
|
|
The attributes available currently are the ones currently provided by the
|
137 |
|
|
drivers written.
|
138 |
|
|
|
139 |
|
|
Good candidates to add in future: model/part#, cycle_time, manufacturer,
|
140 |
|
|
etc.
|
141 |
|
|
|
142 |
|
|
|
143 |
|
|
Q: I have some very specific attribute (e.g. battery color), should I add
|
144 |
|
|
this attribute to standard ones?
|
145 |
|
|
A: Most likely, no. Such attribute can be placed in the driver itself, if
|
146 |
|
|
it is useful. Of course, if the attribute in question applicable to
|
147 |
|
|
large set of batteries, provided by many drivers, and/or comes from
|
148 |
|
|
some general battery specification/standard, it may be a candidate to
|
149 |
|
|
be added to the core attribute set.
|
150 |
|
|
|
151 |
|
|
|
152 |
|
|
Q: Suppose, my battery monitoring chip/firmware does not provides capacity
|
153 |
|
|
in percents, but provides charge_{now,full,empty}. Should I calculate
|
154 |
|
|
percentage capacity manually, inside the driver, and register CAPACITY
|
155 |
|
|
attribute? The same question about time_to_empty/time_to_full.
|
156 |
|
|
A: Most likely, no. This class is designed to export properties which are
|
157 |
|
|
directly measurable by the specific hardware available.
|
158 |
|
|
|
159 |
|
|
Inferring not available properties using some heuristics or mathematical
|
160 |
|
|
model is not subject of work for a battery driver. Such functionality
|
161 |
|
|
should be factored out, and in fact, apm_power, the driver to serve
|
162 |
|
|
legacy APM API on top of power supply class, uses a simple heuristic of
|
163 |
|
|
approximating remaining battery capacity based on its charge, current,
|
164 |
|
|
voltage and so on. But full-fledged battery model is likely not subject
|
165 |
|
|
for kernel at all, as it would require floating point calculation to deal
|
166 |
|
|
with things like differential equations and Kalman filters. This is
|
167 |
|
|
better be handled by batteryd/libbattery, yet to be written.
|