요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
========================
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 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.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
개요와 확장성
1-31Power supply class는 battery, UPS, AC 또는 DC power supply의 property를 사용자 공간에 표현합니다.
거의 모든 power supply에 적용할 수 있는 core attribute 집합을 정의하며, 이 attribute는 sysfs와 uevent 인터페이스로 제공됩니다.
각 attribute는 측정 단위까지 명확한 의미를 가집니다. 다만 특정 monitoring hardware가 모든 값을 제공하지 못할 수 있으므로 지원할 수 없는 attribute는 생략할 수 있습니다.
Power supply class는 확장 가능하며 driver 자체 attribute도 정의할 수 있습니다. 여러 power supply type이나 driver에 널리 적용할 수 있는 attribute가 발견되면 표준 Linux 발전 과정에 따라 core 집합에 추가할 수 있습니다.
LED framework와도 통합되어 battery charging/fully charged 상태와 AC/USB power supply online 상태에 일반적으로 기대되는 표시를 제공합니다. 표시 사용 여부를 포함한 세부 동작은 LED framework의 설계 원칙에 따라 사용자와 장비별 기본값이 완전히 제어합니다.
Driver가 제공한 표준 property는 일관된 사용자 공간 인터페이스와 선택적 LED 표시로 이어집니다.
========================
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).
표준 attribute와 단위
32-56Power supply class는 미리 정의한 attribute 집합으로 driver 간 코드 중복을 없앱니다. Driver는 미리 정의된 attribute와 그 단위를 함께 재사용해야 합니다.
그 결과 사용자 공간은 어떤 power supply에서도 예측 가능한 attribute와 단위를 얻어 일관되게 처리하고 표시할 수 있으며, 서로 다른 power supply와 장비의 결과도 직접 비교할 수 있습니다.
Attribute 선언과 처리 예제는 `drivers/power/supply/ds2760_battery.c`를 참고합니다.
`include/linux/power_supply.h`의 규칙에 따라 별도 설명이 없으면 voltage, current, charge, energy, time, temperature의 단위는 각각 `µV`, `µA`, `µAh`, `µWh`, second, 섭씨 0.1도입니다. Raw value를 class의 단위로 변환하는 일은 driver의 책임입니다.
Driver는 raw hardware 값을 이 단위로 변환해 내보냅니다.
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 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.
Charge, energy, capacity 구분
57-81Charge와 energy는 모두 battery의 capacity를 표현하지만 이 class에서는 엄격히 구분합니다. `CHARGE_*`는 `µAh` 단위의 capacity만, `ENERGY_*`는 `µWh` 단위의 capacity만 나타냅니다. `CAPACITY`는 0부터 100까지의 percent로 나타냅니다. 세 용어를 섞어 쓰면 안 됩니다.
`_AVG` postfix는 hardware가 실제 평균값을 보고할 수 있을 때만 사용하는 hardware-averaged value입니다. `_NOW`는 순간값 또는 즉시 측정값입니다.
원문의 ASCII 표를 단위와 의미가 분명한 표로 다시 구성했습니다.
평균값은 hardware가 직접 지원할 때만 사용합니다.
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.
상태, 인증, health와 voltage
82-117`STATUS`는 charging, full, discharging 즉 load에 전력을 공급하는 상태 등의 동작 상태를 나타내며 `battery.h`에 정의된 `BATTERY_STATUS_*` 값과 대응합니다.
`CHARGE_TYPE`은 battery의 charging rate를 나타내며 trickle charge와 fast charge를 구분합니다. 이미 충전됐거나 방전 중이면 `n/a`를, 상태를 모르면 `unknown`을 표시할 수 있습니다.
`AUTHENTIC`은 platform에 연결된 battery 또는 charger가 정품이면 1, 정품이 아니면 0입니다. `HEALTH`는 battery health를 나타내며 `battery.h`의 `POWER_SUPPLY_HEALTH_*` 값에 대응합니다.
`VOLTAGE_OCV`는 battery의 open-circuit voltage입니다.
`VOLTAGE_MAX_DESIGN`과 `VOLTAGE_MIN_DESIGN`은 정상 조건에서 power supply가 full 또는 empty로 간주될 때의 최대·최소 설계 voltage입니다. Voltage와 battery capacity 사이에 직접 관계는 없지만 단순한 battery는 voltage로 capacity를 매우 거칠게 추정합니다. Battery driver는 이 attribute로 해당 battery의 최대·최소 voltage threshold를 사용자 공간에 알릴 수도 있습니다.
`VOLTAGE_MAX`와 `VOLTAGE_MIN`은 `_DESIGN` 값과 같은 종류이지만 hardware가 특정 power supply의 threshold를 측정해 보관하는 방식으로 추정할 수만 있을 때 사용합니다.
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.
Boot 측정값, 설계값과 실제 threshold
118-143`VOLTAGE_BOOT`와 `CURRENT_BOOT`는 각각 boot 중에 측정한 voltage와 current를 보고합니다.
`CHARGE_FULL_DESIGN`과 `CHARGE_EMPTY_DESIGN`은 battery가 full 또는 empty로 간주되는 설계 charge 값입니다. `ENERGY_FULL_DESIGN`과 `ENERGY_EMPTY_DESIGN`은 같은 의미를 energy로 표현합니다.
`CHARGE_FULL`과 `CHARGE_EMPTY`는 battery가 full 또는 empty가 되었을 때 마지막으로 기억한 charge 값입니다. Temperature와 age 같은 현재 조건에서 full/empty로 간주하는 charge를 뜻할 수도 있습니다. 즉 설계값이 아니라 실제 threshold입니다. `ENERGY_FULL`과 `ENERGY_EMPTY`는 같은 의미를 energy로 표현합니다.
`CHARGE_COUNTER`는 현재 charge counter이며 단위는 `µAh`입니다. 쉽게 음수가 될 수 있고 별도의 empty/full 값은 없으며, 시간에 따른 상대 측정에만 유용합니다.
DESIGN 속성과 기억된 실제 threshold를 구분합니다.
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.
충전과 입력 limit
144-182`PRECHARGE_CURRENT`는 charge cycle의 precharge 단계에서 사용하는 최대 charge current이며 보통 battery capacity의 20%입니다. `CHARGE_TERM_CURRENT`는 charge termination current입니다. Battery voltage가 recharge threshold보다 높고 charge current가 이 설정값보다 낮으면 charge cycle을 종료하며, 보통 battery capacity의 10%입니다.
`CONSTANT_CHARGE_CURRENT`는 charger에 설정한 constant charge current이고 `CONSTANT_CHARGE_CURRENT_MAX`는 power supply object가 지원하는 최대 charge current입니다. `CONSTANT_CHARGE_VOLTAGE`는 charger에 설정한 constant charge voltage이며 `CONSTANT_CHARGE_VOLTAGE_MAX`는 지원하는 최대 charge voltage입니다.
`INPUT_CURRENT_LIMIT`, `INPUT_VOLTAGE_LIMIT`, `INPUT_POWER_LIMIT`은 각각 charger에 설정한 입력 current, voltage, power limit입니다. Charging source에서 끌어오는 current와 적용할 voltage·power 제한을 나타냅니다.
`CHARGE_CONTROL_LIMIT`은 현재 charge control limit 설정이고 `CHARGE_CONTROL_LIMIT_MAX`는 그 최댓값입니다. `CALIBRATE`는 battery 또는 coulomb counter의 calibration 상태입니다.
현재 설정과 hardware가 지원하는 최대치를 구분합니다.
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, temperature와 남은 시간
183-216`CAPACITY`는 percent 단위 capacity입니다. `CAPACITY_ALERT_MIN`과 `CAPACITY_ALERT_MAX`는 각각 percent 단위의 최소·최대 capacity alert 값입니다. `CAPACITY_LEVEL`은 `POWER_SUPPLY_CAPACITY_LEVEL_*`에 대응하는 capacity level입니다.
`TEMP`는 power supply temperature, `TEMP_ALERT_MIN`과 `TEMP_ALERT_MAX`는 battery temperature alert의 최소·최대값입니다. `TEMP_AMBIENT`는 ambient temperature이고 `TEMP_AMBIENT_ALERT_MIN`과 `TEMP_AMBIENT_ALERT_MAX`는 ambient temperature alert의 최소·최대값입니다. `TEMP_MIN`과 `TEMP_MAX`는 동작 가능한 최소·최대 temperature입니다.
`TIME_TO_EMPTY`는 battery가 load에 전력을 공급하는 동안 empty로 간주될 때까지 남은 second입니다. `TIME_TO_FULL`은 charging 중 full로 간주될 때까지 남은 second입니다.
Alert threshold, 상태 수준, 예상 시간을 서로 다른 속성으로 제공합니다.
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와 외부 power supply의 상호작용
217-231Power supply는 공급자와 수전 장치 역할을 동시에 하는 경우가 많으며 battery가 대표적입니다. 따라서 battery는 외부 전원을 공급받는지 알아야 하는 경우가 많습니다.
이를 위해 power supply class는 battery notification mechanism을 구현합니다.
외부 power supply인 AC는 `supplied_to` struct member에 전력을 받는 battery 이름을 나열합니다. 외부 power supply가 `power_supply_changed()`를 호출할 때마다 `external_power_changed` callback을 통해 이 수전 장치에 알립니다.
External supply가 변경을 알리면 등록된 battery callback으로 전달됩니다.
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 특성
232-243Driver는 `power_supply_get_battery_info()`를 호출해 devicetree battery node에서 battery 특성을 얻어야 합니다. Node 정의는 `Documentation/devicetree/bindings/power/supply/battery.yaml`에 있고 구현 예제는 `drivers/power/supply/bq27xxx_battery.c`에 있습니다.
`struct power_supply_battery_info`의 property와 battery node의 대응 property는 `enum power_supply_property` 원소와 맞는 이름을 사용합니다. 이렇게 해 sysfs attribute와 battery node property의 이름을 일관되게 유지합니다.
Devicetree, kernel struct, sysfs가 같은 property vocabulary를 공유합니다.
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.
Q&A: 필요한 표준 attribute가 없을 때
244-259질문: `POWER_SUPPLY_PROP_XYZ` attribute는 어디에 있습니까?
답변: Driver 요구에 맞는 attribute를 찾을 수 없다면 새 attribute를 추가하고 driver와 함께 patch를 보내도 됩니다. 현재 제공되는 attribute는 지금까지 작성된 driver가 제공하는 값들입니다. 앞으로 추가할 만한 후보로 model/part number, cycle time, manufacturer 등이 있습니다.
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&A: 매우 특수한 attribute
260-270질문: Battery color처럼 매우 특수한 attribute를 표준 attribute에 추가해야 합니까?
답변: 대체로 아닙니다. 유용하다면 해당 driver 자체에 둘 수 있습니다. 다만 많은 battery와 driver에 적용되거나 일반 battery specification/standard에서 유래한 attribute라면 core attribute 집합에 추가할 후보가 될 수 있습니다.
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&A: 측정하지 못하는 property의 추론
271-288질문: Monitoring chip이나 firmware가 percent capacity는 제공하지 않고 `charge_{now,full,empty}`만 제공한다면 driver 안에서 percent capacity를 계산해 `CAPACITY`를 등록해야 합니까? `time_to_empty`와 `time_to_full`도 마찬가지입니까?
답변: 대체로 아닙니다. 이 class는 사용할 수 있는 특정 hardware가 직접 측정하는 property를 export하도록 설계됐습니다.
제공되지 않는 property를 heuristic이나 mathematical model로 추론하는 것은 battery driver의 역할이 아니므로 별도 기능으로 분리해야 합니다. Power supply class 위에서 legacy APM API를 제공하는 `apm_power` driver는 charge, current, voltage 등으로 남은 battery capacity를 단순 추정하지만, differential equation이나 Kalman filter를 다루는 완전한 battery model은 floating-point calculation이 필요하므로 kernel 역할이 아닐 가능성이 큽니다. 아직 작성되지 않은 `batteryd` 또는 `libbattery` 같은 사용자 공간 구성 요소가 처리하는 편이 낫습니다.
직접 측정값과 모델 기반 추정값의 책임을 분리합니다.
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.
요약·해설
power_supply_class.rst:1-288Power supply class는 driver가 측정한 값을 공통 이름과 단위로 노출합니다. `CHARGE_*`, `ENERGY_*`, `CAPACITY`를 엄격히 구분하고, hardware가 제공하지 않는 값을 battery driver 안에서 임의로 추론하지 않는 것이 핵심 원칙입니다.