Re: [PATCH v3] power: supply: core: Add kerneldoc to battery struct
From: Vaittinen, Matti <hidden>
Date: 2021-11-16 06:24:45
On 11/16/21 02:17, Linus Walleij wrote:
This complements the struct power_supply_battery_info with extensive kerneldoc explaining the different semantics of the fields, including an overview of the CC/CV charging concepts implicit in some of the struct members. This is done to first establish semantics before I can add more charging methods by breaking out the CC/CV parameters to its own struct.
Cc: Matti Vaittinen <redacted> Tested-by: Randy Dunlap <redacted> Acked-by: Randy Dunlap <redacted> Signed-off-by: Linus Walleij <redacted> --- ChangeLog v2->v3: - After reading the Rohm bd99954 I realized I put the trickle charging at the end of the phase (as I like it to be) but > the one driver using it is putting it before pre-charge, so we adapt to this fact. I will add new properties for "maintenance charging" that happen after CV instead. - Matti, please check this so I don't make any more mistakes.
Well spotted Linus! I had not realized the trickle-charging is also used to maintain the full battery state. After this heads-up I did some googling and it indeed seems to me that there is two potential charging phases that are called trickle-charging. (And if I interpreted google search results correctly, it is not only the ROHM BD99954 which uses trickle-charging as the first charging phase for LI-Ion batteries ;) ). But yes. I think this is now how BD99954 handles it. The driver is interpreting tricle-charging as shown in figure at page 15 in data-sheet: https://fscdn.rohm.com/en/products/databook/datasheet/ic/power/battery_management/bd99954xxx-e.pdf
quoted hunk ↗ jump to hunk
ChangeLog v1->v2: - Fix some spelling error etc. --- include/linux/power_supply.h | 211 +++++++++++++++++++++++++++++++---- 1 file changed, 188 insertions(+), 23 deletions(-)diff --git a/include/linux/power_supply.h b/include/linux/power_supply.h index 9ca1f120a211..52ac70caa401 100644 --- a/include/linux/power_supply.h +++ b/include/linux/power_supply.h@@ -342,37 +342,202 @@ struct power_supply_resistance_temp_table { #define POWER_SUPPLY_OCV_TEMP_MAX 20 -/* +/** + * struct power_supply_battery_info - information about batteries + * @technology: from the POWER_SUPPLY_TECHNOLOGY_* enum + * @energy_full_design_uwh: energy content when fully charged in microwatt + * hours + * @charge_full_design_uah: charge content when fully charged in microampere + * hours + * @voltage_min_design_uv: minimum voltage across the poles when the battery + * is at minimum voltage level in microvolts. If the voltage drops below this + * level the battery will need precharging when using CC/CV charging. + * @voltage_max_design_uv: voltage across the poles when the battery is fully + * charged in microvolts. This is the "nominal voltage" i.e. the voltage + * printed on the label of the battery. + * @tricklecharge_current_ua: the tricklecharge current used when trickle + * charging the battery in microamperes. This is the charging phase when the + * battery is completely empty and we need to carefully trickle in some + * charge until we reach the precharging voltage. + * @precharge_current_ua: current to use in the precharge phase in microamperes, + * the precharge rate is limited by limiting the current to this value. + * @precharge_voltage_max_uv: the maximum voltage allowed when precharging in + * microvolts. When we pass this voltage we will nominally switch over to the + * next charging phase defined by constant_charge_current_ua and + * constant_charge_voltage_max_uv.
nit. Is there a reason to use 'next charging phase' instead of Constant Current phase? If I read this correctly, mentioning that the constant_charge_current_ua and constant_charge_voltage_max_uv define this 'next phase' locks the meaning to constant current charging - unless explanation of constant_charge_current_ua and constant_charge_voltage_max_uv is going to be modified. I think naming the 'next phase' as CC-phase could make this clearer?
+ * @charge_term_current_ua: when the current in the CV (constant voltage) + * charging phase drops below this value in microamperes the charging will + * terminate completely and not restart until the voltage over the battery + * poles reach charge_restart_voltage_uv unless we use maintenance charging. + * @charge_restart_voltage_uv: when the battery has been fully charged by + * CC/CV charging and charging has been disabled, and the voltage subsequently + * drops below this value in microvolts, the charging will be restarted + * (typically using CV charging). + * @overvoltage_limit_uv: If the voltage exceeds the nominal voltage + * voltage_max_design_uv and we reach this voltage level, all charging must + * stop and emergency procedures take place, such as shutting down the system + * in some cases. + * @constant_charge_current_max_ua: current in microamperes to use in the CC + * (constant current) charging phase. The charging rate is limited + * by this current. This is the main charging phase and as the current is + * constant into the battery the voltage slowly ascends to + * constant_charge_voltage_max_uv. + * @constant_charge_voltage_max_uv: voltage in microvolts signifying the end of + * the CC (constant current) charging phase and the beginning of the CV + * (constant voltage) charging phase.
...
+ * + * The charging parameters here assume a CC/CV charging scheme. This method + * is most common with Lithium Ion batteries (other methods are possible) and + * looks as follows: + * + * ^ Battery voltage + * | --- overvoltage_limit_uv + * | + * | ................................................... + * | .. constant_charge_voltage_max_uv + * | .. + * | . + * | . + * | . + * | . + * | . + * | .. precharge_voltage_max_uv + * | .. + * |. (trickle charging) + * +------------------------------------------------------------------> time + * + * ^ Current into the battery + * | + * | ............. constant_charge_current_max_ua + * | . . + * | . . + * | . . + * | . . + * | . .. + * | . .... + * | . ..... + * | ... precharge_current_ua ....... charge_term_current_ua + * | . . + * | . . + * |.... tricklecharge_current_ua . + * | . + * +-----------------------------------------------------------------> time + *
These diagrams are absolutely golden. I wish people took more time to produce things like this. It clarifies things far better, faster and more accurately than <insert large amount here> written words. Great job - thanks! Reviewed-by: Matti Vaittinen <redacted> Best Regards Matti Vaittinen