Anton Vorontsov | 4a11b59 | 2007-05-04 00:27:45 +0400 | [diff] [blame] | 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 | |
Andres Salomon | ee8076e | 2009-07-02 09:45:18 -0400 | [diff] [blame] | 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 | |
Ramakrishna Pallala | b1b5687 | 2012-08-23 06:50:21 +0530 | [diff] [blame] | 84 | AUTHENTIC - indicates the power supply (battery or charger) connected |
| 85 | to the platform is authentic(1) or non authentic(0). |
| 86 | |
Anton Vorontsov | 4a11b59 | 2007-05-04 00:27:45 +0400 | [diff] [blame] | 87 | HEALTH - represents health of the battery, values corresponds to |
| 88 | POWER_SUPPLY_HEALTH_*, defined in battery.h. |
| 89 | |
Ramakrishna Pallala | a2ebfe2 | 2012-04-10 16:21:20 +0530 | [diff] [blame] | 90 | VOLTAGE_OCV - open circuit voltage of the battery. |
| 91 | |
Anton Vorontsov | 4a11b59 | 2007-05-04 00:27:45 +0400 | [diff] [blame] | 92 | VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and |
| 93 | minimal power supply voltages. Maximal/minimal means values of voltages |
| 94 | when battery considered "full"/"empty" at normal conditions. Yes, there is |
| 95 | no direct relation between voltage and battery capacity, but some dumb |
| 96 | batteries use voltage for very approximated calculation of capacity. |
| 97 | Battery driver also can use this attribute just to inform userspace |
| 98 | about maximal and minimal voltage thresholds of a given battery. |
| 99 | |
Dmitry Baryshkov | c7cc930 | 2008-01-07 04:12:41 +0300 | [diff] [blame] | 100 | VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that |
| 101 | these ones should be used if hardware could only guess (measure and |
| 102 | retain) the thresholds of a given power supply. |
| 103 | |
Anton Vorontsov | 4a11b59 | 2007-05-04 00:27:45 +0400 | [diff] [blame] | 104 | CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when |
| 105 | battery considered full/empty. |
| 106 | |
| 107 | ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy. |
| 108 | |
| 109 | CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value |
| 110 | of charge when battery became full/empty". It also could mean "value of |
| 111 | charge when battery considered full/empty at given conditions (temperature, |
| 112 | age)". I.e. these attributes represents real thresholds, not design values. |
| 113 | |
Andres Salomon | 8e552c3 | 2008-05-12 21:46:29 -0400 | [diff] [blame] | 114 | CHARGE_COUNTER - the current charge counter (in µAh). This could easily |
| 115 | be negative; there is no empty or full value. It is only useful for |
| 116 | relative, time-based measurements. |
| 117 | |
Ramakrishna Pallala | 3824c47 | 2012-05-06 18:16:44 +0530 | [diff] [blame] | 118 | CONSTANT_CHARGE_CURRENT - constant charge current programmed by charger. |
Ramakrishna Pallala | 2815b78 | 2012-07-30 12:49:21 +0530 | [diff] [blame] | 119 | CONSTANT_CHARGE_CURRENT_MAX - maximum charge current supported by the |
| 120 | power supply object. |
Ramakrishna Pallala | 3824c47 | 2012-05-06 18:16:44 +0530 | [diff] [blame] | 121 | |
| 122 | CONSTANT_CHARGE_VOLTAGE - constant charge voltage programmed by charger. |
Ramakrishna Pallala | 2815b78 | 2012-07-30 12:49:21 +0530 | [diff] [blame] | 123 | CONSTANT_CHARGE_VOLTAGE_MAX - maximum charge voltage supported by the |
| 124 | power supply object. |
Ramakrishna Pallala | 3824c47 | 2012-05-06 18:16:44 +0530 | [diff] [blame] | 125 | |
Ramakrishna Pallala | ea2ce92 | 2012-10-09 22:25:29 +0530 | [diff] [blame] | 126 | CHARGE_CONTROL_LIMIT - current charge control limit setting |
| 127 | CHARGE_CONTROL_LIMIT_MAX - maximum charge control limit setting |
| 128 | |
Anton Vorontsov | 4a11b59 | 2007-05-04 00:27:45 +0400 | [diff] [blame] | 129 | ENERGY_FULL, ENERGY_EMPTY - same as above but for energy. |
| 130 | |
| 131 | CAPACITY - capacity in percents. |
Ramakrishna Pallala | e908c41 | 2012-07-05 16:59:12 +0530 | [diff] [blame] | 132 | CAPACITY_ALERT_MIN - minimum capacity alert value in percents. |
| 133 | CAPACITY_ALERT_MAX - maximum capacity alert value in percents. |
Andres Salomon | b294a29 | 2009-06-30 02:13:01 -0400 | [diff] [blame] | 134 | CAPACITY_LEVEL - capacity level. This corresponds to |
| 135 | POWER_SUPPLY_CAPACITY_LEVEL_*. |
Anton Vorontsov | 4a11b59 | 2007-05-04 00:27:45 +0400 | [diff] [blame] | 136 | |
| 137 | TEMP - temperature of the power supply. |
Ramakrishna Pallala | e908c41 | 2012-07-05 16:59:12 +0530 | [diff] [blame] | 138 | TEMP_ALERT_MIN - minimum battery temperature alert value in milli centigrade. |
| 139 | TEMP_ALERT_MAX - maximum battery temperature alert value in milli centigrade. |
Anton Vorontsov | 4a11b59 | 2007-05-04 00:27:45 +0400 | [diff] [blame] | 140 | TEMP_AMBIENT - ambient temperature. |
Ramakrishna Pallala | e908c41 | 2012-07-05 16:59:12 +0530 | [diff] [blame] | 141 | TEMP_AMBIENT_ALERT_MIN - minimum ambient temperature alert value in milli centigrade. |
| 142 | TEMP_AMBIENT_ALERT_MAX - maximum ambient temperature alert value in milli centigrade. |
Anton Vorontsov | 4a11b59 | 2007-05-04 00:27:45 +0400 | [diff] [blame] | 143 | |
| 144 | TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e. |
| 145 | while battery powers a load) |
| 146 | TIME_TO_FULL - seconds left for battery to be considered full (i.e. |
| 147 | while battery is charging) |
| 148 | |
| 149 | |
| 150 | Battery <-> external power supply interaction |
| 151 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 152 | Often power supplies are acting as supplies and supplicants at the same |
| 153 | time. Batteries are good example. So, batteries usually care if they're |
| 154 | externally powered or not. |
| 155 | |
| 156 | For that case, power supply class implements notification mechanism for |
| 157 | batteries. |
| 158 | |
| 159 | External power supply (AC) lists supplicants (batteries) names in |
| 160 | "supplied_to" struct member, and each power_supply_changed() call |
| 161 | issued by external power supply will notify supplicants via |
| 162 | external_power_changed callback. |
| 163 | |
| 164 | |
| 165 | QA |
| 166 | ~~ |
| 167 | Q: Where is POWER_SUPPLY_PROP_XYZ attribute? |
| 168 | A: If you cannot find attribute suitable for your driver needs, feel free |
| 169 | to add it and send patch along with your driver. |
| 170 | |
| 171 | The attributes available currently are the ones currently provided by the |
| 172 | drivers written. |
| 173 | |
| 174 | Good candidates to add in future: model/part#, cycle_time, manufacturer, |
| 175 | etc. |
| 176 | |
| 177 | |
| 178 | Q: I have some very specific attribute (e.g. battery color), should I add |
| 179 | this attribute to standard ones? |
| 180 | A: Most likely, no. Such attribute can be placed in the driver itself, if |
| 181 | it is useful. Of course, if the attribute in question applicable to |
| 182 | large set of batteries, provided by many drivers, and/or comes from |
| 183 | some general battery specification/standard, it may be a candidate to |
| 184 | be added to the core attribute set. |
| 185 | |
| 186 | |
| 187 | Q: Suppose, my battery monitoring chip/firmware does not provides capacity |
| 188 | in percents, but provides charge_{now,full,empty}. Should I calculate |
| 189 | percentage capacity manually, inside the driver, and register CAPACITY |
| 190 | attribute? The same question about time_to_empty/time_to_full. |
| 191 | A: Most likely, no. This class is designed to export properties which are |
| 192 | directly measurable by the specific hardware available. |
| 193 | |
| 194 | Inferring not available properties using some heuristics or mathematical |
| 195 | model is not subject of work for a battery driver. Such functionality |
| 196 | should be factored out, and in fact, apm_power, the driver to serve |
| 197 | legacy APM API on top of power supply class, uses a simple heuristic of |
| 198 | approximating remaining battery capacity based on its charge, current, |
| 199 | voltage and so on. But full-fledged battery model is likely not subject |
| 200 | for kernel at all, as it would require floating point calculation to deal |
| 201 | with things like differential equations and Kalman filters. This is |
| 202 | better be handled by batteryd/libbattery, yet to be written. |