forked from Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
288 lines
10 KiB
288 lines
10 KiB
======================== |
|
Linux power supply class |
|
======================== |
|
|
|
Synopsis |
|
~~~~~~~~ |
|
Power supply class used to represent battery, UPS, AC or DC power supply |
|
properties to user-space. |
|
|
|
It defines core set of attributes, which should be applicable to (almost) |
|
every power supply out there. Attributes are available via sysfs and uevent |
|
interfaces. |
|
|
|
Each attribute has well defined meaning, up to unit of measure used. While |
|
the attributes provided are believed to be universally applicable to any |
|
power supply, specific monitoring hardware may not be able to provide them |
|
all, so any of them may be skipped. |
|
|
|
Power supply class is extensible, and allows to define drivers own attributes. |
|
The core attribute set is subject to the standard Linux evolution (i.e. |
|
if it will be found that some attribute is applicable to many power supply |
|
types or their drivers, it can be added to the core set). |
|
|
|
It also integrates with LED framework, for the purpose of providing |
|
typically expected feedback of battery charging/fully charged status and |
|
AC/USB power supply online status. (Note that specific details of the |
|
indication (including whether to use it at all) are fully controllable by |
|
user and/or specific machine defaults, per design principles of LED |
|
framework). |
|
|
|
|
|
Attributes/properties |
|
~~~~~~~~~~~~~~~~~~~~~ |
|
Power supply class has predefined set of attributes, this eliminates code |
|
duplication across drivers. Power supply class insist on reusing its |
|
predefined attributes *and* their units. |
|
|
|
So, userspace gets predictable set of attributes and their units for any |
|
kind of power supply, and can process/present them to a user in consistent |
|
manner. Results for different power supplies and machines are also directly |
|
comparable. |
|
|
|
See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c |
|
for the example how to declare and handle attributes. |
|
|
|
|
|
Units |
|
~~~~~ |
|
Quoting include/linux/power_supply.h: |
|
|
|
All voltages, currents, charges, energies, time and temperatures in µV, |
|
µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise |
|
stated. It's driver's job to convert its raw values to units in which |
|
this class operates. |
|
|
|
|
|
Attributes/properties detailed |
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
|
|
+--------------------------------------------------------------------------+ |
|
| **Charge/Energy/Capacity - how to not confuse** | |
|
+--------------------------------------------------------------------------+ |
|
| **Because both "charge" (µAh) and "energy" (µWh) represents "capacity" | |
|
| of battery, this class distinguish these terms. Don't mix them!** | |
|
| | |
|
| - `CHARGE_*` | |
|
| attributes represents capacity in µAh only. | |
|
| - `ENERGY_*` | |
|
| attributes represents capacity in µWh only. | |
|
| - `CAPACITY` | |
|
| attribute represents capacity in *percents*, from 0 to 100. | |
|
+--------------------------------------------------------------------------+ |
|
|
|
Postfixes: |
|
|
|
_AVG |
|
*hardware* averaged value, use it if your hardware is really able to |
|
report averaged values. |
|
_NOW |
|
momentary/instantaneous values. |
|
|
|
STATUS |
|
this attribute represents operating status (charging, full, |
|
discharging (i.e. powering a load), etc.). This corresponds to |
|
`BATTERY_STATUS_*` values, as defined in battery.h. |
|
|
|
CHARGE_TYPE |
|
batteries can typically charge at different rates. |
|
This defines trickle and fast charges. For batteries that |
|
are already charged or discharging, 'n/a' can be displayed (or |
|
'unknown', if the status is not known). |
|
|
|
AUTHENTIC |
|
indicates the power supply (battery or charger) connected |
|
to the platform is authentic(1) or non authentic(0). |
|
|
|
HEALTH |
|
represents health of the battery, values corresponds to |
|
POWER_SUPPLY_HEALTH_*, defined in battery.h. |
|
|
|
VOLTAGE_OCV |
|
open circuit voltage of the battery. |
|
|
|
VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN |
|
design values for maximal and minimal power supply voltages. |
|
Maximal/minimal means values of voltages when battery considered |
|
"full"/"empty" at normal conditions. Yes, there is no direct relation |
|
between voltage and battery capacity, but some dumb |
|
batteries use voltage for very approximated calculation of capacity. |
|
Battery driver also can use this attribute just to inform userspace |
|
about maximal and minimal voltage thresholds of a given battery. |
|
|
|
VOLTAGE_MAX, VOLTAGE_MIN |
|
same as _DESIGN voltage values except that these ones should be used |
|
if hardware could only guess (measure and retain) the thresholds of a |
|
given power supply. |
|
|
|
VOLTAGE_BOOT |
|
Reports the voltage measured during boot |
|
|
|
CURRENT_BOOT |
|
Reports the current measured during boot |
|
|
|
CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN |
|
design charge values, when battery considered full/empty. |
|
|
|
ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN |
|
same as above but for energy. |
|
|
|
CHARGE_FULL, CHARGE_EMPTY |
|
These attributes means "last remembered value of charge when battery |
|
became full/empty". It also could mean "value of charge when battery |
|
considered full/empty at given conditions (temperature, age)". |
|
I.e. these attributes represents real thresholds, not design values. |
|
|
|
ENERGY_FULL, ENERGY_EMPTY |
|
same as above but for energy. |
|
|
|
CHARGE_COUNTER |
|
the current charge counter (in µAh). This could easily |
|
be negative; there is no empty or full value. It is only useful for |
|
relative, time-based measurements. |
|
|
|
PRECHARGE_CURRENT |
|
the maximum charge current during precharge phase of charge cycle |
|
(typically 20% of battery capacity). |
|
|
|
CHARGE_TERM_CURRENT |
|
Charge termination current. The charge cycle terminates when battery |
|
voltage is above recharge threshold, and charge current is below |
|
this setting (typically 10% of battery capacity). |
|
|
|
CONSTANT_CHARGE_CURRENT |
|
constant charge current programmed by charger. |
|
|
|
|
|
CONSTANT_CHARGE_CURRENT_MAX |
|
maximum charge current supported by the power supply object. |
|
|
|
CONSTANT_CHARGE_VOLTAGE |
|
constant charge voltage programmed by charger. |
|
CONSTANT_CHARGE_VOLTAGE_MAX |
|
maximum charge voltage supported by the power supply object. |
|
|
|
INPUT_CURRENT_LIMIT |
|
input current limit programmed by charger. Indicates |
|
the current drawn from a charging source. |
|
INPUT_VOLTAGE_LIMIT |
|
input voltage limit programmed by charger. Indicates |
|
the voltage limit from a charging source. |
|
INPUT_POWER_LIMIT |
|
input power limit programmed by charger. Indicates |
|
the power limit from a charging source. |
|
|
|
CHARGE_CONTROL_LIMIT |
|
current charge control limit setting |
|
CHARGE_CONTROL_LIMIT_MAX |
|
maximum charge control limit setting |
|
|
|
CALIBRATE |
|
battery or coulomb counter calibration status |
|
|
|
CAPACITY |
|
capacity in percents. |
|
CAPACITY_ALERT_MIN |
|
minimum capacity alert value in percents. |
|
CAPACITY_ALERT_MAX |
|
maximum capacity alert value in percents. |
|
CAPACITY_LEVEL |
|
capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*. |
|
|
|
TEMP |
|
temperature of the power supply. |
|
TEMP_ALERT_MIN |
|
minimum battery temperature alert. |
|
TEMP_ALERT_MAX |
|
maximum battery temperature alert. |
|
TEMP_AMBIENT |
|
ambient temperature. |
|
TEMP_AMBIENT_ALERT_MIN |
|
minimum ambient temperature alert. |
|
TEMP_AMBIENT_ALERT_MAX |
|
maximum ambient temperature alert. |
|
TEMP_MIN |
|
minimum operatable temperature |
|
TEMP_MAX |
|
maximum operatable temperature |
|
|
|
TIME_TO_EMPTY |
|
seconds left for battery to be considered empty |
|
(i.e. while battery powers a load) |
|
TIME_TO_FULL |
|
seconds left for battery to be considered full |
|
(i.e. while battery is charging) |
|
|
|
|
|
Battery <-> external power supply interaction |
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
Often power supplies are acting as supplies and supplicants at the same |
|
time. Batteries are good example. So, batteries usually care if they're |
|
externally powered or not. |
|
|
|
For that case, power supply class implements notification mechanism for |
|
batteries. |
|
|
|
External power supply (AC) lists supplicants (batteries) names in |
|
"supplied_to" struct member, and each power_supply_changed() call |
|
issued by external power supply will notify supplicants via |
|
external_power_changed callback. |
|
|
|
|
|
Devicetree battery characteristics |
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
Drivers should call power_supply_get_battery_info() to obtain battery |
|
characteristics from a devicetree battery node, defined in |
|
Documentation/devicetree/bindings/power/supply/battery.yaml. This is |
|
implemented in drivers/power/supply/bq27xxx_battery.c. |
|
|
|
Properties in struct power_supply_battery_info and their counterparts in the |
|
battery node have names corresponding to elements in enum power_supply_property, |
|
for naming consistency between sysfs attributes and battery node properties. |
|
|
|
|
|
QA |
|
~~ |
|
|
|
Q: |
|
Where is POWER_SUPPLY_PROP_XYZ attribute? |
|
A: |
|
If you cannot find attribute suitable for your driver needs, feel free |
|
to add it and send patch along with your driver. |
|
|
|
The attributes available currently are the ones currently provided by the |
|
drivers written. |
|
|
|
Good candidates to add in future: model/part#, cycle_time, manufacturer, |
|
etc. |
|
|
|
|
|
Q: |
|
I have some very specific attribute (e.g. battery color), should I add |
|
this attribute to standard ones? |
|
A: |
|
Most likely, no. Such attribute can be placed in the driver itself, if |
|
it is useful. Of course, if the attribute in question applicable to |
|
large set of batteries, provided by many drivers, and/or comes from |
|
some general battery specification/standard, it may be a candidate to |
|
be added to the core attribute set. |
|
|
|
|
|
Q: |
|
Suppose, my battery monitoring chip/firmware does not provides capacity |
|
in percents, but provides charge_{now,full,empty}. Should I calculate |
|
percentage capacity manually, inside the driver, and register CAPACITY |
|
attribute? The same question about time_to_empty/time_to_full. |
|
A: |
|
Most likely, no. This class is designed to export properties which are |
|
directly measurable by the specific hardware available. |
|
|
|
Inferring not available properties using some heuristics or mathematical |
|
model is not subject of work for a battery driver. Such functionality |
|
should be factored out, and in fact, apm_power, the driver to serve |
|
legacy APM API on top of power supply class, uses a simple heuristic of |
|
approximating remaining battery capacity based on its charge, current, |
|
voltage and so on. But full-fledged battery model is likely not subject |
|
for kernel at all, as it would require floating point calculation to deal |
|
with things like differential equations and Kalman filters. This is |
|
better be handled by batteryd/libbattery, yet to be written.
|
|
|