Re: [PATCH] power: supply: core: Add kerneldoc to battery struct

[Randy Dunlap <rdunlap@infradead.org>]

Hi,

On 11/4/21 5:30 PM, 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.
> 
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> ---
>   include/linux/power_supply.h | 209 +++++++++++++++++++++++++++++++----
>   1 file changed, 186 insertions(+), 23 deletions(-)
> 
> diff --git a/include/linux/power_supply.h b/include/linux/power_supply.h
> index 9ca1f120a211..671730c5279f 100644
> --- a/include/linux/power_supply.h
> +++ b/include/linux/power_supply.h
> @@ -342,37 +342,200 @@ 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 fully charged and we just trickle in some current to keep the
> + *   voltage up between constant_charge_voltage_max_uv and overvoltage_limit_uv.
> + * @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.
> + * @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 trickle 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: when tricklecharging the battery can temporarily
> + *   exceed the nominal voltage voltage_max_design_uv. The tricklecharginging
> + *   must stop when we reach this value, not to restart unless we get back
> + *   down to constant_charge_voltage_max_uv.
> + * @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.
> + * @factory_internal_resistance_uohm: the internal resistance of the battery
> + *   at fabrication time, expressed in microohms. This resistance will vary
> + *   depending on the lifetime and charge of the battery, so this is just a
> + *   nominal ballpark figure.
> + * @ocv_temp: array indicating the open circuit voltage (OCV) capacity
> + *   temperature indices. This is an array of temperatures in degrees celsius

                                                            preferably    Celsius

> + *   indicating which capacity table to used for a certain temperature, since
> + *   the capacity for reasons of chemistry will be different at different
> + *   temperatures. Determining capacity is a multivariate problem and the
> + *   temperature is the first variable we determine.
> + * @temp_ambient_alert_min: the battery will go outside of operating conditions
> + *   when the ambient temperature goes below this temperature in degrees
> + *   celsius.
> + * @temp_ambient_alert_max: the battery will go outside of operating conditions
> + *   when the ambient temperature goes above this temperature in degrees
> + *   celsius.

Ditto. et al.

> + * @temp_alert_min: the battery should issue an alert if the internal
> + *   temperature goes below this temperature in degrees celsius.
> + * @temp_alert_max: the battery should issue an alert if the internal
> + *   temperature goes above this temperature in degrees celsius.
> + * @temp_min: the battery will go outside of operating conditions when
> + *   the internal temperature goes below this temperature in degrees celsius.
> + *   Normally this means the system should shut down.
> + * @temp_max: the battery will go outside of operating conditions when
> + *   the internal temperature goes above this temperature in degrees celsius.
> + *   Normally this means the system should shut down.
> + * @ocv_table: for each entry in ocv_temp there is a corresponding entry in
> + *   ocv_table and a size for each entry in ocv_table_size. These arrays
> + *   determine the capacity in percent in relation to the voltage in microvolts
> + *   at the indexed temperature.
> + * @ocv_table_size: for each entry in ocv_temp this array is giving the size of
> + *   each entry in the array of capacity arrays in ocv_table.
> + * @resist_table: this is a table that correlates a resistance to an internal
> + *   temperature of a battery. This can be achieved by a separate thermistor to
> + *   supply voltage on a third terminal on a battery which is the most
> + *   reliable. An external thermistor can also be used sometimes.
> + * @resist_table_size: the number of items in the resist table.
> + *
>    * This is the recommended struct to manage static battery parameters,
>    * populated by power_supply_get_battery_info(). Most platform drivers should
>    * use these for consistency.
> + *
>    * Its field names must correspond to elements in enum power_supply_property.
>    * The default field value is -EINVAL.
> - * Power supply class itself doesn't use this.
> + *
> + * The charging parameters here assumes a CC/CV charging scheme. This method

                                    assume

> + * is most common with Lithium Ion batteries (other methods are possible) and
> + * looks as follows:
> + *
> + * ^ Battery voltage
...
> + * +------------------------------------------------------------------> time
> + *
> + * ^ Current into the battery
...
> + * +-----------------------------------------------------------------> time
> + *
> + * These diagrams are synchronized on time and the voltage and current
> + * follow each other.
> + *
> + * With CC/CV charging commence over time like this for an empty battery:
> + *
> + * 1. First a small initial pre-charge current (precharge_current_ua)
> + *    is applied if the voltage is below precharge_voltage_max_uv until we
> + *    reach precharge_voltage_max_uv. CATION: in some text this is referred

                                          CAUTION:        texts
(although CATION is a word!)

> + *    to as "trickle charging" but the use in the Linux kernel is differen

                                                                      different

> + *    see below!
> + *
> + * 2. Then the main charging current is applied, which is called the constant
> + *    current (CC) phase. A current regulator is set up to allow
> + *    constant_charge_current_max_ua of current to flow into the battery.
> + *    The chemical reaction in the battery will make the voltage go up as
> + *    charge goes into the battery. This current is applied until we reach
> + *    the constant_charge_voltage_max_uv voltage.
> + *
> + * 3. At this voltage we switch over to the constant voltage (CV) phase. This
> + *    means we allow current to go into the battery, but we keep the voltage
> + *    fixed. This current will continue to charge the battery while keeping
> + *    the voltage the same. A chemical reaction in the battery goes on
> + *    storing energy without affecting the voltage. Over time the current
> + *    will slowly drop and when we reach charge_term_current_ua we will
> + *    end the constant voltage phase.
> + *
> + * After this the battery is fully charged, and if we do not support trickle
> + * charging, the charging will not restart until power dissapation make the

                                                           dissipation makes

> + * voltage fall so that we reach charge_restart_voltage_uv and at this point
> + * we restart charging at the appropriate phase, usually this will be inside
> + * the CV phase.


Tested-by: Randy Dunlap <rdunlap@infradead.org>

and if (when :) you fix these, you can add

Acked-by: Randy Dunlap <rdunlap@infradead.org>


Thanks for doing this.

-- 
~Randy