Root/
1 | 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 | 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). |
83 | |
84 | HEALTH - represents health of the battery, values corresponds to |
85 | POWER_SUPPLY_HEALTH_*, defined in battery.h. |
86 | |
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. |
94 | |
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. |
98 | |
99 | CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when |
100 | battery considered full/empty. |
101 | |
102 | ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy. |
103 | |
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. |
108 | |
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. |
112 | |
113 | ENERGY_FULL, ENERGY_EMPTY - same as above but for energy. |
114 | |
115 | CAPACITY - capacity in percents. |
116 | CAPACITY_LEVEL - capacity level. This corresponds to |
117 | POWER_SUPPLY_CAPACITY_LEVEL_*. |
118 | |
119 | TEMP - temperature of the power supply. |
120 | TEMP_AMBIENT - ambient temperature. |
121 | |
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) |
126 | |
127 | |
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. |
133 | |
134 | For that case, power supply class implements notification mechanism for |
135 | batteries. |
136 | |
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. |
141 | |
142 | |
143 | QA |
144 | ~~ |
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. |
148 | |
149 | The attributes available currently are the ones currently provided by the |
150 | drivers written. |
151 | |
152 | Good candidates to add in future: model/part#, cycle_time, manufacturer, |
153 | etc. |
154 | |
155 | |
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. |
163 | |
164 | |
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. |
171 | |
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. |
181 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9