Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) Linux power supply class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) ~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) Power supply class used to represent battery, UPS, AC or DC power supply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) properties to user-space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) It defines core set of attributes, which should be applicable to (almost)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) every power supply out there. Attributes are available via sysfs and uevent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) Each attribute has well defined meaning, up to unit of measure used. While
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) the attributes provided are believed to be universally applicable to any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) power supply, specific monitoring hardware may not be able to provide them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) all, so any of them may be skipped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) Power supply class is extensible, and allows to define drivers own attributes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) The core attribute set is subject to the standard Linux evolution (i.e.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) if it will be found that some attribute is applicable to many power supply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) types or their drivers, it can be added to the core set).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) It also integrates with LED framework, for the purpose of providing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) typically expected feedback of battery charging/fully charged status and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) AC/USB power supply online status. (Note that specific details of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) indication (including whether to use it at all) are fully controllable by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) user and/or specific machine defaults, per design principles of LED
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) framework).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) Attributes/properties
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) ~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) Power supply class has predefined set of attributes, this eliminates code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) duplication across drivers. Power supply class insist on reusing its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) predefined attributes *and* their units.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) So, userspace gets predictable set of attributes and their units for any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) kind of power supply, and can process/present them to a user in consistent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) manner. Results for different power supplies and machines are also directly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) comparable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) for the example how to declare and handle attributes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) Units
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) ~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) Quoting include/linux/power_supply.h:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51)   All voltages, currents, charges, energies, time and temperatures in µV,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52)   µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53)   stated. It's driver's job to convert its raw values to units in which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54)   this class operates.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) Attributes/properties detailed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) +--------------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) |               **Charge/Energy/Capacity - how to not confuse**            |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) +--------------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) | **Because both "charge" (µAh) and "energy" (µWh) represents "capacity"   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) | of battery, this class distinguish these terms. Don't mix them!**        |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) |                                                                          |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) | - `CHARGE_*`                                                             |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) |	attributes represents capacity in µAh only.                        |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) | - `ENERGY_*`                                                             |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) |	attributes represents capacity in µWh only.                        |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) | - `CAPACITY`                                                             |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) |	attribute represents capacity in *percents*, from 0 to 100.        |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) +--------------------------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) Postfixes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) _AVG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77)   *hardware* averaged value, use it if your hardware is really able to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78)   report averaged values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) _NOW
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80)   momentary/instantaneous values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) STATUS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83)   this attribute represents operating status (charging, full,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84)   discharging (i.e. powering a load), etc.). This corresponds to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85)   `BATTERY_STATUS_*` values, as defined in battery.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) CHARGE_TYPE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88)   batteries can typically charge at different rates.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89)   This defines trickle and fast charges.  For batteries that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90)   are already charged or discharging, 'n/a' can be displayed (or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91)   'unknown', if the status is not known).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) AUTHENTIC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94)   indicates the power supply (battery or charger) connected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95)   to the platform is authentic(1) or non authentic(0).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) HEALTH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98)   represents health of the battery, values corresponds to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99)   POWER_SUPPLY_HEALTH_*, defined in battery.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) VOLTAGE_OCV
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)   open circuit voltage of the battery.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)   design values for maximal and minimal power supply voltages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)   Maximal/minimal means values of voltages when battery considered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)   "full"/"empty" at normal conditions. Yes, there is no direct relation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)   between voltage and battery capacity, but some dumb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)   batteries use voltage for very approximated calculation of capacity.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)   Battery driver also can use this attribute just to inform userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)   about maximal and minimal voltage thresholds of a given battery.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) VOLTAGE_MAX, VOLTAGE_MIN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)   same as _DESIGN voltage values except that these ones should be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)   if hardware could only guess (measure and retain) the thresholds of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)   given power supply.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) VOLTAGE_BOOT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)   Reports the voltage measured during boot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) CURRENT_BOOT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)   Reports the current measured during boot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)   design charge values, when battery considered full/empty.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)   same as above but for energy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) CHARGE_FULL, CHARGE_EMPTY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)   These attributes means "last remembered value of charge when battery
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)   became full/empty". It also could mean "value of charge when battery
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)   considered full/empty at given conditions (temperature, age)".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)   I.e. these attributes represents real thresholds, not design values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) ENERGY_FULL, ENERGY_EMPTY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)   same as above but for energy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) CHARGE_COUNTER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)   the current charge counter (in µAh).  This could easily
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)   be negative; there is no empty or full value.  It is only useful for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)   relative, time-based measurements.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) PRECHARGE_CURRENT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)   the maximum charge current during precharge phase of charge cycle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)   (typically 20% of battery capacity).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) CHARGE_TERM_CURRENT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)   Charge termination current. The charge cycle terminates when battery
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)   voltage is above recharge threshold, and charge current is below
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)   this setting (typically 10% of battery capacity).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) CONSTANT_CHARGE_CURRENT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)   constant charge current programmed by charger.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) CONSTANT_CHARGE_CURRENT_MAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)   maximum charge current supported by the power supply object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) CONSTANT_CHARGE_VOLTAGE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)   constant charge voltage programmed by charger.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) CONSTANT_CHARGE_VOLTAGE_MAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)   maximum charge voltage supported by the power supply object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) INPUT_CURRENT_LIMIT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)   input current limit programmed by charger. Indicates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)   the current drawn from a charging source.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) INPUT_VOLTAGE_LIMIT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)   input voltage limit programmed by charger. Indicates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)   the voltage limit from a charging source.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) INPUT_POWER_LIMIT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)   input power limit programmed by charger. Indicates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)   the power limit from a charging source.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) CHARGE_CONTROL_LIMIT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)   current charge control limit setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) CHARGE_CONTROL_LIMIT_MAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)   maximum charge control limit setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) CALIBRATE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)   battery or coulomb counter calibration status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) CAPACITY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)   capacity in percents.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) CAPACITY_ALERT_MIN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)   minimum capacity alert value in percents.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) CAPACITY_ALERT_MAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)   maximum capacity alert value in percents.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) CAPACITY_LEVEL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)   capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) TEMP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)   temperature of the power supply.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) TEMP_ALERT_MIN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)   minimum battery temperature alert.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) TEMP_ALERT_MAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)   maximum battery temperature alert.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) TEMP_AMBIENT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)   ambient temperature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) TEMP_AMBIENT_ALERT_MIN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)   minimum ambient temperature alert.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) TEMP_AMBIENT_ALERT_MAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)   maximum ambient temperature alert.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) TEMP_MIN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)   minimum operatable temperature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) TEMP_MAX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)   maximum operatable temperature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) TIME_TO_EMPTY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)   seconds left for battery to be considered empty
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)   (i.e. while battery powers a load)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) TIME_TO_FULL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)   seconds left for battery to be considered full
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)   (i.e. while battery is charging)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) Battery <-> external power supply interaction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) Often power supplies are acting as supplies and supplicants at the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) time. Batteries are good example. So, batteries usually care if they're
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) externally powered or not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) For that case, power supply class implements notification mechanism for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) batteries.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) External power supply (AC) lists supplicants (batteries) names in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) "supplied_to" struct member, and each power_supply_changed() call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) issued by external power supply will notify supplicants via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) external_power_changed callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Devicetree battery characteristics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) Drivers should call power_supply_get_battery_info() to obtain battery
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) characteristics from a devicetree battery node, defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) Documentation/devicetree/bindings/power/supply/battery.txt. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) implemented in drivers/power/supply/bq27xxx_battery.c.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) Properties in struct power_supply_battery_info and their counterparts in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) battery node have names corresponding to elements in enum power_supply_property,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) for naming consistency between sysfs attributes and battery node properties.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) QA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) ~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) Q:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)    Where is POWER_SUPPLY_PROP_XYZ attribute?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) A:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)    If you cannot find attribute suitable for your driver needs, feel free
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)    to add it and send patch along with your driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)    The attributes available currently are the ones currently provided by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)    drivers written.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)    Good candidates to add in future: model/part#, cycle_time, manufacturer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)    etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) Q:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)    I have some very specific attribute (e.g. battery color), should I add
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)    this attribute to standard ones?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) A:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)    Most likely, no. Such attribute can be placed in the driver itself, if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)    it is useful. Of course, if the attribute in question applicable to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)    large set of batteries, provided by many drivers, and/or comes from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)    some general battery specification/standard, it may be a candidate to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)    be added to the core attribute set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) Q:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)    Suppose, my battery monitoring chip/firmware does not provides capacity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)    in percents, but provides charge_{now,full,empty}. Should I calculate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)    percentage capacity manually, inside the driver, and register CAPACITY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)    attribute? The same question about time_to_empty/time_to_full.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) A:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)    Most likely, no. This class is designed to export properties which are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)    directly measurable by the specific hardware available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)    Inferring not available properties using some heuristics or mathematical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)    model is not subject of work for a battery driver. Such functionality
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)    should be factored out, and in fact, apm_power, the driver to serve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)    legacy APM API on top of power supply class, uses a simple heuristic of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)    approximating remaining battery capacity based on its charge, current,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)    voltage and so on. But full-fledged battery model is likely not subject
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)    for kernel at all, as it would require floating point calculation to deal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)    with things like differential equations and Kalman filters. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)    better be handled by batteryd/libbattery, yet to be written.