Documentation/power/power_supply_class.rst

   1 ========================
   2 Linux power supply class
   3 ========================
   4
   5 Synopsis
   6 ~~~~~~~~
   7 Power supply class used to represent battery, UPS, AC or DC power supply
   8 properties to user-space.
   9
  10 It defines core set of attributes, which should be applicable to (almost)
  11 every power supply out there. Attributes are available via sysfs and uevent
  12 interfaces.
  13
  14 Each attribute has well defined meaning, up to unit of measure used. While
  15 the attributes provided are believed to be universally applicable to any
  16 power supply, specific monitoring hardware may not be able to provide them
  17 all, so any of them may be skipped.
  18
  19 Power supply class is extensible, and allows to define drivers own attributes.
  20 The core attribute set is subject to the standard Linux evolution (i.e.
  21 if it will be found that some attribute is applicable to many power supply
  22 types or their drivers, it can be added to the core set).
  23
  24 It also integrates with LED framework, for the purpose of providing
  25 typically expected feedback of battery charging/fully charged status and
  26 AC/USB power supply online status. (Note that specific details of the
  27 indication (including whether to use it at all) are fully controllable by
  28 user and/or specific machine defaults, per design principles of LED
  29 framework).
  30
  31
  32 Attributes/properties
  33 ~~~~~~~~~~~~~~~~~~~~~
  34 Power supply class has predefined set of attributes, this eliminates code
  35 duplication across drivers. Power supply class insist on reusing its
  36 predefined attributes *and* their units.
  37
  38 So, userspace gets predictable set of attributes and their units for any
  39 kind of power supply, and can process/present them to a user in consistent
  40 manner. Results for different power supplies and machines are also directly
  41 comparable.
  42
  43 See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
  44 for the example how to declare and handle attributes.
  45
  46
  47 Units
  48 ~~~~~
  49 Quoting 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
  57 Attributes/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
  74 Postfixes:
  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
  82 STATUS
  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
  87 CHARGE_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
  93 AUTHENTIC
  94   indicates the power supply (battery or charger) connected
  95   to the platform is authentic(1) or non authentic(0).
  96
  97 HEALTH
  98   represents health of the battery, values corresponds to
  99   POWER_SUPPLY_HEALTH_*, defined in battery.h.
 100
 101 VOLTAGE_OCV
 102   open circuit voltage of the battery.
 103
 104 VOLTAGE_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
 113 VOLTAGE_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
 118 VOLTAGE_BOOT
 119   Reports the voltage measured during boot
 120
 121 CURRENT_BOOT
 122   Reports the current measured during boot
 123
 124 CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN
 125   design charge values, when battery considered full/empty.
 126
 127 ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN
 128   same as above but for energy.
 129
 130 CHARGE_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
 136 ENERGY_FULL, ENERGY_EMPTY
 137   same as above but for energy.
 138
 139 CHARGE_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
 144 PRECHARGE_CURRENT
 145   the maximum charge current during precharge phase of charge cycle
 146   (typically 20% of battery capacity).
 147
 148 CHARGE_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
 153 CONSTANT_CHARGE_CURRENT
 154   constant charge current programmed by charger.
 155
 156
 157 CONSTANT_CHARGE_CURRENT_MAX
 158   maximum charge current supported by the power supply object.
 159
 160 CONSTANT_CHARGE_VOLTAGE
 161   constant charge voltage programmed by charger.
 162 CONSTANT_CHARGE_VOLTAGE_MAX
 163   maximum charge voltage supported by the power supply object.
 164
 165 INPUT_CURRENT_LIMIT
 166   input current limit programmed by charger. Indicates
 167   the current drawn from a charging source.
 168 INPUT_VOLTAGE_LIMIT
 169   input voltage limit programmed by charger. Indicates
 170   the voltage limit from a charging source.
 171 INPUT_POWER_LIMIT
 172   input power limit programmed by charger. Indicates
 173   the power limit from a charging source.
 174
 175 CHARGE_CONTROL_LIMIT
 176   current charge control limit setting
 177 CHARGE_CONTROL_LIMIT_MAX
 178   maximum charge control limit setting
 179
 180 CALIBRATE
 181   battery or coulomb counter calibration status
 182
 183 CAPACITY
 184   capacity in percents.
 185 CAPACITY_ALERT_MIN
 186   minimum capacity alert value in percents.
 187 CAPACITY_ALERT_MAX
 188   maximum capacity alert value in percents.
 189 CAPACITY_LEVEL
 190   capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*.
 191
 192 TEMP
 193   temperature of the power supply.
 194 TEMP_ALERT_MIN
 195   minimum battery temperature alert.
 196 TEMP_ALERT_MAX
 197   maximum battery temperature alert.
 198 TEMP_AMBIENT
 199   ambient temperature.
 200 TEMP_AMBIENT_ALERT_MIN
 201   minimum ambient temperature alert.
 202 TEMP_AMBIENT_ALERT_MAX
 203   maximum ambient temperature alert.
 204 TEMP_MIN
 205   minimum operatable temperature
 206 TEMP_MAX
 207   maximum operatable temperature
 208
 209 TIME_TO_EMPTY
 210   seconds left for battery to be considered empty
 211   (i.e. while battery powers a load)
 212 TIME_TO_FULL
 213   seconds left for battery to be considered full
 214   (i.e. while battery is charging)
 215
 216
 217 Battery <-> external power supply interaction
 218 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 219 Often power supplies are acting as supplies and supplicants at the same
 220 time. Batteries are good example. So, batteries usually care if they're
 221 externally powered or not.
 222
 223 For that case, power supply class implements notification mechanism for
 224 batteries.
 225
 226 External power supply (AC) lists supplicants (batteries) names in
 227 "supplied_to" struct member, and each power_supply_changed() call
 228 issued by external power supply will notify supplicants via
 229 external_power_changed callback.
 230
 231
 232 Devicetree battery characteristics
 233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 234 Drivers should call power_supply_get_battery_info() to obtain battery
 235 characteristics from a devicetree battery node, defined in
 236 Documentation/devicetree/bindings/power/supply/battery.yaml. This is
 237 implemented in drivers/power/supply/bq27xxx_battery.c.
 238
 239 Properties in struct power_supply_battery_info and their counterparts in the
 240 battery node have names corresponding to elements in enum power_supply_property,
 241 for naming consistency between sysfs attributes and battery node properties.
 242
 243
 244 QA
 245 ~~
 246
 247 Q:
 248    Where is POWER_SUPPLY_PROP_XYZ attribute?
 249 A:
 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
 260 Q:
 261    I have some very specific attribute (e.g. battery color), should I add
 262    this attribute to standard ones?
 263 A:
 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
 271 Q:
 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.
 276 A:
 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.