battery: Optionally prevent boot at low SOC with cell imbalance.

Measure the cell imbalance with method dispatch to a per-battery
method, such that families with a plurality of configurable batteries
can support them all.  By default, cell imbalance is taken to be 'zero'
in case we don't support that battery's management IC.  Provide a driver
for reading cell voltages for the TI BQ4050 family.  This IC is quite
popular, but by no means universal.

BUG=b:111214767
BRANCH=none
TEST=Boot on Careena with a custom debug print statement, showing that
we can measure the typical battery voltages during and after the boot at
the battery status polling interval.

Change-Id: I235389b252ac9c373aa9706dbd1066f7c0bbce71
Signed-off-by: Jonathan Brandmeyer <jbrandmeyer@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/1162663
Reviewed-by: Daisuke Nojiri <dnojiri@chromium.org>

3 files changed, 77 insertions, 0 deletions

diff --git a/include/battery.h b/include/battery.h
index a97745b794..2ba56e1c9d 100644
--- a/include/battery.h
+++ b/include/battery.h
@@ -117,6 +117,7 @@ int battery_get_avg_voltage(void); /* in mV */
 #define BATT_FLAG_BAD_REMAINING_CAPACITY	0x00000100
 #define BATT_FLAG_BAD_FULL_CAPACITY		0x00000200
 #define BATT_FLAG_BAD_STATUS			0x00000400
+#define BATT_FLAG_IMBALANCED_CELL		0x00000800
 /* All of the above BATT_FLAG_BAD_* bits */
 #define BATT_FLAG_BAD_ANY			0x000007fc
 
@@ -328,6 +329,12 @@ int battery_device_chemistry(char *dest, int size);
 int battery_manufacturer_date(int *year, int *month, int *day);
 
 /**
+ * Report the absolute difference between the highest and lowest cell voltage in
+ * the battery pack, in millivolts.  On error or unimplemented, returns '0'.
+ */
+int battery_imbalance_mv(void);
+
+/**
  * Call board-specific cut-off function.
  *
  * @return EC_RES_INVALID_COMMAND if the battery doesn't support.
diff --git a/include/battery_fuel_gauge.h b/include/battery_fuel_gauge.h
index 8de72d7d4e..9c3b0b12da 100644
--- a/include/battery_fuel_gauge.h
+++ b/include/battery_fuel_gauge.h
@@ -31,6 +31,11 @@ struct fuel_gauge_info {
 	const uint8_t override_nil;
 	const struct ship_mode_info ship_mode;
 	const struct fet_info fet;
+
+#ifdef CONFIG_BATTERY_MEASURE_IMBALANCE
+	/* See battery_*_imbalance_mv() for functions which are suitable. */
+	int (*imbalance_mv)(void);
+#endif
 };
 
 struct board_batt_params {
@@ -42,4 +47,18 @@ struct board_batt_params {
 extern const struct board_batt_params board_battery_info[];
 extern const enum battery_type DEFAULT_BATTERY_TYPE;
 
+
+#ifdef CONFIG_BATTERY_MEASURE_IMBALANCE
+/**
+ * Report the absolute difference between the highest and lowest cell voltage in
+ * the battery pack, in millivolts.  On error or unimplemented, returns '0'.
+ */
+int battery_default_imbalance_mv(void);
+
+#ifdef CONFIG_BATTERY_BQ4050
+int battery_bq4050_imbalance_mv(void);
+#endif
+
+#endif
+
 #endif /* __CROS_EC_BATTERY_FUEL_GAUGE_H */
diff --git a/include/config.h b/include/config.h
index 619ee9f55c..4f5688010f 100644
--- a/include/config.h
+++ b/include/config.h
@@ -266,6 +266,7 @@
 #undef CONFIG_BATTERY_BQ20Z453
 #undef CONFIG_BATTERY_BQ27541
 #undef CONFIG_BATTERY_BQ27621
+#undef CONFIG_BATTERY_BQ4050
 #undef CONFIG_BATTERY_MAX17055
 
 /* Compile mock battery support; used by tests. */
@@ -398,6 +399,12 @@
 #undef CONFIG_BATTERY_COUNT
 
 /*
+ * Smart battery driver should measure the voltage cell imbalance in the battery
+ * pack.  This requires a battery driver capable of the measurement.
+ */
+#undef CONFIG_BATTERY_MEASURE_IMBALANCE
+
+/*
  * Expose some data when it is needed.
  * For example, battery disconnect state
  */
@@ -695,6 +702,15 @@
 /* Minimum charger power (in mW) required for powering on. */
 #undef CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON
 
+/* Minimum battery percentage for power on with an imbalanced pack */
+#undef CONFIG_CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON
+
+/*
+ * Maximum battery cell imbalance to accept before considering the pack to be
+ * imbalanced, in millivolts.
+ */
+#undef CONFIG_BATTERY_MAX_IMBALANCE_MV
+
 /* Set this option when using a Narrow VDC (NVDC) charger, such as ISL9237/8. */
 #undef CONFIG_CHARGER_NARROW_VDC
 
@@ -3667,6 +3683,7 @@
 #if defined(CONFIG_BATTERY_BQ20Z453) || \
 	defined(CONFIG_BATTERY_BQ27541) || \
 	defined(CONFIG_BATTERY_BQ27621) || \
+	defined(CONFIG_BATTERY_BQ4050) || \
 	defined(CONFIG_BATTERY_MAX17055) || \
 	defined(CONFIG_BATTERY_SMART)
 #define CONFIG_BATTERY
@@ -3794,6 +3811,40 @@
 #endif /* !defined(CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON) */
 #endif /* defined(HAS_TASK_CHIPSET) */
 
+#ifndef CONFIG_CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON
+/*
+ * The function of MEASURE_BATTERY_IMBALANCE and these variables is to prevent a
+ * battery brownout when the management IC reports a state of charge that is
+ * higher than CHARGER_MIN_BAT_PCT_FOR_POWER_ON, but an individual cell is lower
+ * than the rest of the pack.  The critical term is MAX_IMBALANCE_MV, which must
+ * be small enough to ensure that the system can reliably boot even when the
+ * battery total state of charge barely passes the
+ * CHARGER_MIN_BAT_PCT_FOR_POWER_ON threshold.
+ *
+ * Lowering CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON below
+ * CHARGER_MIN_BAT_PCT_FOR_POWER_ON disables this check.  Raising it too high
+ * may needlessly prevent boot when the lowest cell can still support the
+ * system.
+ *
+ * As this term is lowered and BATTERY_MAX_IMBALANCE_MV is raised, the risk of
+ * cell-undervoltage brownout during startup increases.  Raising this term and
+ * lowering MAX_IMBALANCE_MV increases the risk of poor UX when the user must
+ * wait longer to turn on their device.
+ */
+#define CONFIG_CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON 5
+#endif
+
+#ifndef CONFIG_BATTERY_MAX_IMBALANCE_MV
+/*
+ * WAG.  Imbalanced battery packs in this situation appear to have balanced
+ * charge very quickly after beginning the charging cycle, since dV/dQ rapidly
+ * decreases as the cell is charged out of deep discharge.  Increasing the value
+ * of CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON will make a system tolerant of
+ * larger values of BATTERY_MAX_IMBALANCE_MV.
+ */
+#define CONFIG_BATTERY_MAX_IMBALANCE_MV 200
+#endif
+
 #ifndef HAS_TASK_KEYPROTO
 #undef CONFIG_KEYBOARD_PROTOCOL_8042
 /*