Synopsis¶

Power supply class used to represent battery, UPS, AC or DC power supplyproperties to user-space.

It defines a core set of attributes which should be applicable to (almost)every power supply out there. Attributes are available via sysfs and ueventinterfaces.

Each attribute has a well-defined meaning, up to the unit of measure used. Whilethe attributes provided are believed to be universally applicable to anypower supply, specific monitoring hardware may not be able to provide themall, so any of them may be skipped.

The power supply class is extensible and allows drivers to define their ownattributes. The core attribute set is subject to the standard Linux evolution(i.e., if some attribute is found to be applicable to many powersupply types or their drivers, it can be added to the core set).

It also integrates with the LED framework, for the purpose of providingtypically expected feedback of battery charging/fully charged status andAC/USB power supply online status. (Note that specific details of theindication (including whether to use it at all) are fully controllable byuser and/or specific machine defaults, per design principles of the LEDframework.)

Attributes/properties¶

The power supply class has a predefined set of attributes. This eliminates codeduplication across drivers. The power supply class insists on reusing itspredefined attributesand their units.

So, userspace gets a predictable set of attributes and their units for anykind of power supply, and can process/present them to a user in consistentmanner. Results for different power supplies and machines are also directlycomparable.

See drivers/power/supply/ds2760_battery.c for the example how to declareand 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 otherwisestated. It’s driver’s job to convert its raw values to units in whichthis class operates.

Attributes/properties detailed¶

Postfixes:

_AVG

hardware averaged value, use it if your hardware is really able toreport averaged values.

_NOW

momentary/instantaneous values.

STATUS

this attribute represents operating status (charging, full,discharging (i.e., powering a load), etc.). This corresponds toBATTERY_STATUS_* values, as defined in battery.h.

CHARGE_TYPE

batteries can typically charge at different rates.This defines trickle and fast charges. For batteries thatare 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) connectedto the platform is authentic(1) or non-authentic(0).

HEALTH

represents health of the battery. Values corresponds toPOWER_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 is considered“full”/”empty” at normal conditions. Yes, there is no direct relationbetween voltage and battery capacity, but some dumbbatteries use voltage for very approximated calculation of capacity.A battery driver also can use this attribute just to inform userspaceabout maximal and minimal voltage thresholds of a given battery.

VOLTAGE_MAX, VOLTAGE_MIN

same as _DESIGN voltage values except that these ones should be usedif hardware could only guess (measure and retain) the thresholds of agiven 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 is considered full/empty.

ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN

same as above but for energy.

CHARGE_FULL, CHARGE_EMPTY

These attributes mean “last remembered value of charge when batterybecame full/empty”. They also could mean “value of charge when battery isconsidered 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 easilybe negative; there is no empty or full value. It is only useful forrelative, 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 batteryvoltage is above recharge threshold, and charge current is belowthis 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. Indicatesthe current drawn from a charging source.

INPUT_VOLTAGE_LIMIT

input voltage limit programmed by charger. Indicatesthe voltage limit from a charging source.

INPUT_POWER_LIMIT

input power limit programmed by charger. Indicatesthe 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 sametime. Batteries are good example. So, batteries usually care if they’reexternally powered or not.

For that case, the power supply class implements a notification mechanism forbatteries.

An external power supply (AC) lists supplicants (batteries) names in“supplied_to”structmember, and eachpower_supply_changed() callissued by an external power supply will notify supplicants viathe external_power_changed callback.

Devicetree battery characteristics¶

Drivers should callpower_supply_get_battery_info() to obtain batterycharacteristics from a devicetree battery node, defined inDocumentation/devicetree/bindings/power/supply/battery.yaml. This isimplemented in drivers/power/supply/bq27xxx_battery.c.

Properties instructpower_supply_battery_info and their counterparts in thebattery node have names corresponding to elements inenumpower_supply_property,for naming consistency between sysfs attributes and battery node properties.

Q&A¶

Q:

Where is POWER_SUPPLY_PROP_XYZ attribute?

A:

If you cannot find an attribute suitable for your driver needs, feel freeto add it and send a patch along with your driver.

The attributes available currently are the ones currently provided by thedrivers 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 addthis attribute to standard ones?

A:

Most likely, no. Such attribute can be placed in the driver itself, ifit is useful. Of course, if the attribute in question is applicable toa large set of batteries, provided by many drivers, and/or comes fromsome general battery specification/standard, it may be a candidate tobe added to the core attribute set.

Q:

Suppose my battery monitoring chip/firmware does not provide capacityin percents, but provides charge_{now,full,empty}. Should I calculatepercentage capacity manually, inside the driver, and register CAPACITYattribute? The same question about time_to_empty/time_to_full.

A:

Most likely, no. This class is designed to export properties which aredirectly measurable by the specific hardware available.

Inferring not available properties using some heuristics or mathematicalmodel is not a subject of work for a battery driver. Such functionalityshould be factored out, and in fact, apm_power, the driver to servelegacy APM API on top of the power supply class, uses a simple heuristic ofapproximating remaining battery capacity based on its charge, current,voltage and so on. But a full-fledged battery model is likely not a subjectfor the kernel at all, as it would require floating point calculations todeal with things like differential equations and Kalman filters. This isbetter be handled by batteryd/libbattery, yet to be written.