docs: Document low-battery compatibility config.

HOWTO set up an EC board such that plugging it in and turning it on Just
Works.

BUG=none
BRANCH=none
TEST=load docs in a markdown viewer for formatting.

Change-Id: Ib1b31fe0a3c26ac7aad95d362f89afc25f57bf99
Signed-off-by: Jonathan Brandmeyer <jbrandmeyer@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/1180403

3 files changed, 462 insertions, 9 deletions

diff --git a/common/charge_state_v2.c b/common/charge_state_v2.c
index 879585b26f..aed3e02ad0 100644
--- a/common/charge_state_v2.c
+++ b/common/charge_state_v2.c
@@ -2308,7 +2308,7 @@ static int charge_command_charge_state(struct host_cmd_handler_args *args)
 				val = curr.chg.option;
 				break;
 			case CS_PARAM_LIMIT_POWER:
-#ifdef CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT
+#ifdef CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW
 				/*
 				 * LIMIT_POWER status is based on battery level
 				 * and external charger power.
diff --git a/docs/low_battery_startup.md b/docs/low_battery_startup.md
new file mode 100644
index 0000000000..451136f80e
--- /dev/null
+++ b/docs/low_battery_startup.md
@@ -0,0 +1,428 @@
+# Configuring the EC for Low-Battery Startup
+
+Near the bottom of charge, starting up a ChromeOS device can be a tricky
+proposition.  Several features interact to make it difficult to reliably turn on
+the machine without browning out.  Over the years, a variety of configuration
+options have been written to maximize ChromeOS's compatibility with the basic
+user expectation,
+
+"I plugged it in, therefore it should turn on."
+
+When creating a new board configuration, this document should aid the engineer
+in navigating and choosing correct values for these options.
+
+The first section describes the various features which interact with each other
+to create a complex environment for the EC during boot, especially at a low
+state of charge.
+
+Second, we'll provide some reference configurations which cover many
+Chromebooks' use cases.
+
+Finally, we'll close out with a detailed review of the configuration parameters
+which are available.
+
+## Interacting Features
+
+### Battery and Charging Circuit
+
+For the most part, ChromeOS device power systems are much like other laptop
+battery power systems.  A variable-voltage rail is connected to the battery via
+a series of cutoff MOSFETs.  Several system power rails derive their power from
+the system's variable-voltage rail.  Mains power is delivered to the
+variable-voltage system rail by a buck/boost charging circuit.  Mains power is
+itself rectified, isolated, and stepped down by an external power supply.
+
+During most of the battery charge, the charger operates in current mode, acting
+as a constant current source that delivers current to the variable-voltage rail.
+Load transients are served by the capacitance on the rail and the battery.  By
+superposition, load transients during the charge don't necessarily draw current
+from the battery, they may just reduce the current flow into the battery.
+
+References to AC power in the EC codebase are actually references to an external
+power supply's DC source.  External supplies that are actually USB-PD-speaking
+battery packs are indistinguishable from AC/DC adapters as far as the EC is
+concerned.  Variables and functions which refer to external supplies all refer
+to them as 'AC', though.
+
+### Source Current Negotiation
+
+A device may draw power from an AC adapter via a few methods.
+
+#### USB BC1.2 Current Sources
+
+BC1.2 negotiation is usually managed entirely by an external IC.  Once it is
+complete, the EC limits itself to 2.4A max.  Additionally, the charger may be
+configured to switch to an input voltage regulation mode if the input voltage
+begins to sag too low.
+
+Ideally, the input source provides a voltage droop, such that it is not quite
+overloaded at the input voltage regulation setpoint of about 4.5V.  Thus, 4.5V
+serves as a reasonable reference voltage for the charger to use when it is in an
+input voltage-regulation mode.
+
+In effect, the EC limits to both a maximum current of 2.4A and minimum voltage
+of 4.5V, for about 12W of power draw from a BC1.2 source.
+
+See also `driver/bc12/bq24392.c:bc12_detect()`.
+
+#### USB-PD Sources
+
+High-current power supplies are negotiated via the USB Type C Current Source and
+USB Power Delivery specifications (PD).  PD sources must support Type-C Current
+Source, but the reverse is not true.  Both types of current sources are managed
+via the PD protocol module in the EC codebase.
+
+Type-C Current Source capabilities of up to 15W (3A, 5V) are advertised via
+analog signaling alone.  Via digital communication in the PD protocol, much
+higher power states may be negotiated.  However, higher power states also
+usually run at a higher voltage state as well.  Any time the voltage level is
+changing, the power sink (the ChromeOS device) must lower its power consumption
+during the transient.  The standby current level is governed by
+`CONFIG_CHARGER_INPUT_CURRENT`.
+
+PD port partners are capable of both soft and hard resets.  Hard resets will
+cause a dead-bus state for a brief interval before PD can renegotiate, from
+scratch, because it is intended to emulate a cable disconnect.  Therefore, a
+hard reset without a connected battery will brownout the Chromebook.
+
+### Locked and Unlocked Firmware
+
+The Verified Boot implementation normally limits the complexity of the code
+which executes in the locked Read-Only firmware package.  The consequences for
+the EC are:
+
+- Locked RO EC firmware does not process any digital PD messages at all, it only
+  recognizes the analog advertisement of USB Current Source (15W max).
+- Installation of user-provided firmware is supported, but the write-protect pin
+  must be cleared to enable it.
+- On recent systems, write-protect is cleared by removing the system battery.
+
+### ChromeOS `powerd`
+
+The power management daemon provided by ChromeOS displays a "low-power charger"
+warning message via the system tray whenever the charger is limited to less than
+20W.  Therefore, if a USB-PD source is restricted to analog signaling, or a
+BC1.2 source is connected, the user gets alerted to the situation.
+
+Systems that can run on very little power may be rapidly charged with a 15W
+charger, while a high power system may require a 40W state or more for a decent
+battery charging user experience.  Therefore, a board's overlay may override the
+warning threshold by replacing `/usr/share/power_manager/usb_min_ac_watts` in
+the board's filesystem.
+
+See also `platform2/power_manager/` source code.
+
+### Cell Imbalance
+
+Under normal conditions, the battery pack is equipped with a management IC which
+is solely responsible for the safety of the battery, measurement of the state of
+charge, and the balance of its cells.  Examples include (but are not limited to)
+the TI BQ40Z50 and Renesas RAJ240.
+
+However, after very long periods of rest without a battery charging cycle, the
+natural self-discharge rate of each cell will cause them to diverge somewhat
+from each other.
+
+Some IC's can be configured to report a pack total state of charge of zero if
+any one cell's voltage is below a certain threshold.  However, many do not.
+Therefore, after an extended rest period, one cell can be very close to the cell
+undervoltage cutoff threshold, even though the pack as a whole is considered to
+be at 3% charge or more.
+
+### Power Profile During Boot
+
+The power profile during the boot sequence is substantially different than that
+seen during typical use.  Dynamic voltage and frequency scaling of the AP is
+partially governed by the temperature of the processor core.  As the processor
+gets hotter, it will reduce its maximum core voltage and frequency to settle out
+at some maximum design junction temperature for the core.  For passively cooled
+devices, the profile may also be chosen to limit the external case temperature.
+
+At startup, the case and core are cold.  The bootloaders and kernel are also
+optimized to boot as fast as possible for a responsive user experience.  So, the
+power drawn during the boot is much higher than that seen during typical
+productivity and entertainment tasks.
+
+### Depthcharge Power Verification
+
+After verification and optional update of the EC's RW firwmare, Depthcharge will
+poll the EC to verify that it is allowed to proceed to boot to the kernel.
+
+It does this by polling via the:
+- `EC_CMD_CHARGE_STATE` host command.
+- `CHARGE_STATE_CMD_GET_PARAM` subcommand.
+- `CS_PARAM_LIMIT_POWER` parameter.
+
+When the EC returns 0, power draw by the AP is unlimited and depthcharge resumes
+the boot.  If the EC fails to return 0 in three seconds, depthcharge shuts down.
+
+See also VbExEcVbootDone() in Depthcharge, and option
+`CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW` in the EC.  By default, this option
+is not set, and the EC immediately allows the boot to proceed.
+
+## Example Low-Battery Boot Sequences and Configurations
+
+Most ChromeOS devices power needs will be met by one of the following templates.
+
+### Low-Power Device
+
+Low-power devices require 15W or less of power to boot the AP.  The battery pack
+is robust enough to support the device during brief intervals of PD negotiation
+without browning out.
+
+```
+#define CONFIG_CHARGER_INPUT_CURRENT 512
+#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 1
+```
+
+A detailed boot sequence under this configuration, with a low battery and
+available AC power via a USB-PD charger:
+
+1. EC ROM bootloader loads and jumps to the EC's read-only firmware image.
+1. RO firmware negotiates a 15W state via Current Source analog signaling and
+   begins charging the battery with it.
+1. RO firmware verifies conditions to begin booting the AP:
+     - Battery state of charge > 1%
+     - OR charger power greater or equal to 15W (met by Current Source analog
+       signaling).
+1. AP firmware performs verification of the EC's RW image, upgrades it if
+   necessary, and sysjumps the EC to it.
+1. AP firmware queries the charge state limit power flag via EC-host command,
+   and the EC immediately responds that it is clear.
+1. Depthcharge continues the boot.
+     1. In parallel with kernel loading and Linux's boot, the EC performs PD
+        negotiation.  Charger power lowers to 2.5W for up to 500ms as the source
+        transitions from vSafe5V to its highest supported voltage (15V or 20V
+        are typical).  During this transition time some power is drawn from the
+        battery.
+     1. After PD negotiation is complete, the EC raises the charger current
+        limit to the negotiated limit (45W is typical).
+
+### Low-Power Device Startup With Marginal Battery Compatibility
+
+Similar in configuration to the low-power device startup, this system enables
+additional options to maximize its compatibility with marginal batteries near
+the bottom of charge.  The Grunt family is an exemplar.  This system will
+complete software sync with less than 15W of power, but may require more power
+to boot the kernel and get to the login screen.
+
+```
+/* Limit battery impact during PD voltage changes. */
+#define CONFIG_CHARGER_INPUT_CURRENT 512
+
+/* Distrust the battery SOC measurement a bit. */
+#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 3
+
+/*
+ * Require PD negotiation to be complete prior to booting Linux, but don't
+ * care about how much power we negotiate.
+ */
+#define CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW 15001
+
+/* Extra paranoia about imbalanced cells. */
+#define CONFIG_BATTERY_MEASURE_IMBALANCE
+```
+
+Additionally, in order to take advantage of cell imbalance detection, the system
+battery must support per-cell voltage measurement.
+
+A detailed boot sequence under this configuration, with a low battery and
+available AC power:
+
+1. EC ROM bootloader loads and jumps to the EC's read-only firmware image.
+1. RO firmware negotiates a 15W state via Current Source analog signaling and
+   begins charging the battery with it.
+1. RO firmware verifies conditions to begin booting the AP:
+     - battery state of charge >= 3% AND cell imbalance < 200 mV
+     - OR battery state of charge >= 5%
+     - OR charger power greater or equal to 15W (met by Current Source analog
+       signaling).
+1. AP firmware performs verification of the EC's RW image, upgrades it if
+   necessary, and sysjumps the EC to it.
+1. AP firmware polls the charge state limit power flag via EC-host command for
+   up to 3 seconds, in 50ms intervals.  The EC will return `1` (power limited)
+   so long as the charger power is < 15.001W and the battery is less than 3%.
+     1. Meanwhile, the EC performs PD negotiation.  Charger power lowers to 2.5W
+        for up to 500ms as the source transitions from vSafe5V to its highest
+        supported voltage (15V or 20V are typical).
+     1. After negotiation is complete, the EC raises the charger current limit
+        to the negotiated limit (45W is typical).
+     1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request.
+1. Depthcharge continues to boot Linux.
+
+
+### High-Power Boot Device Startup
+
+A "high-power device" in this case is one that requires significantly more than
+15W of power to boot the AP.  These devices may complete software sync at 15W or
+less.  Very briefly drawing current out of the battery does not cause a
+brownout.
+
+Example configuration:
+
+```
+#define CONFIG_CHARGER_INPUT_CURRENT 512
+#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 3
+#define CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON 15000
+#define CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW 27000
+```
+
+Where the low-power device specified a threshold that just barely
+requires PD negotiation to happen before booting, this device has a definite
+minimum power to boot Linux (27W).  A detailed boot sequence under this
+configuration, with a low battery and available AC power:
+
+1. EC ROM bootloader loads and jumps to the EC's read-only firmware image.
+1. RO firmware negotiates a 15W state via Current Source analog signaling and
+   begins charging the battery with it.
+1. RO firmware verifies conditions to begin booting the AP:
+    - battery state of charge >= 3%
+    - OR charger power greater or equal to 15W (met by Current Source analog
+      signaling).
+1. AP firmware performs verification of the EC's RW image, upgrades it if
+  necessary, and sysjumps the EC to it.
+1. AP firmware polls the charge state limit power flag via EC-host command for
+   up to 3 seconds, in 50ms intervals.  The EC will return `1` (power limited)
+   so long as the charger power is < 27W and the battery is less than 3%.
+     1. Meanwhile, the EC performs PD negotiation.  Charger power lowers to 2.5W
+        for up to 500ms as the source transitions from vSafe5V to its highest
+        supported voltage (15V or 20V are typical).
+     1. After negotiation is complete, the EC raises the charger current limit
+        to the negotiated limit (45W is typical).
+     1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request.
+1. Depthcharge continues to boot Linux.
+
+
+### High-Power SwSync Device Startup
+
+Like the high-power boot device startup, these devices draw less than 15W during
+most of the software sync process, but may briefly exceed 15W during short
+intervals of software sync.  However, there is substantial risk of brownout
+during those intervals unless the battery is charged up a bit first.  Therefore,
+they strictly require 1% battery capacity to perform software sync.
+Additionally, this configuration requires PD negotiation to be complete prior to
+performing a no-battery boot.  Nami is an exemplar.
+
+
+Example configuration:
+
+```
+#define CONFIG_CHARGER_INPUT_CURRENT 512
+
+#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON_WITH_AC 1
+#define CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON_WITH_BATT 15000
+
+#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 3
+#define CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON 27000
+
+#define CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT 3
+#define CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW 27000
+```
+
+1. EC ROM bootloader loads and jumps to the EC's read-only firmware image.
+1. RO firmware negotiates a 15W state via Current Source analog signaling and
+   begins charging the battery with it.
+1. RO firmware verifies conditions to begin booting the AP:
+     - Battery state of charge is greater than 1% AND charger power is greater
+       than 15W  (met after a minute or so of charging on analog signaling)
+     - OR Battery state of charge is greater than 3%
+     - OR Charger power is greater than 27W (met after PD negotiation in
+       unlocked RO firmware).
+1. AP firmware performs verification of the EC's RW image, upgrades it if
+   necessary, and sysjumps the EC to it.
+1. AP firmware polls the charge state limit power flag via EC-host command for
+   up to 3 seconds, in 50ms intervals.  The EC will return `1` (power limited)
+   so long as the charger power is < 27W and the battery is less than 3%.
+     1. Meanwhile, the EC performs PD negotiation.  Charger power lowers to 2.5W
+        for up to 500ms as the source transitions from vSafe5V to its highest
+        supported voltage (15V or 20V are typical).
+     1. After negotiation is complete, the EC raises the charger current limit
+        to the negotiated limit (45W is typical).
+     1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request.
+1. Depthcharge continues to boot Linux.
+
+
+## Configuration Option Details
+
+### `CONFIG_CHARGER_INPUT_CURRENT`
+
+Required.
+
+The lowest current limit programmed into the charger.  This determines both the
+default level used on startup, and the value used during the voltage transients
+in PD negotiation.
+
+It should not be higher than 512 mA unless the device ships with a discrete
+power supply.  Raising this term above 512 mA is contrary to USB-PD.  It may be
+lowered in order to improve compatibility with marginal BC1.2 chargers.
+
+### `CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON`
+
+Required.
+
+The minimum battery state of charge to start up the AP, in percent of full
+charge.
+
+#### `CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON`
+
+Default: 15000 (15W)
+
+The minimum charger power level to start the AP even when the battery is less
+than `CHARGER_MIN_BAT_PCT_FOR_POWER_ON`, in milliwatts.
+
+### `CONFIG_BATTERY_MEASURE_IMBALANCE`
+
+Optional.  Only set this option if one or more batteries shipped with this board
+support per-cell battery voltage measurement.
+
+When enabled, the EC will query the attached battery for its per-cell voltages.
+If the cell voltage is excessively imbalanced at a low state of charge, the boot
+is inhibited.
+
+#### `CONFIG_CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON`
+
+Default: 5%.  Above this battery state of charge, cell voltage balance is
+ignored.
+
+#### `CONFIG_BATTERY_MAX_IMBALANCE_MV`
+
+Default: 200 mV.  If the difference between the highest and lowest cell exceeds
+this value, then the pack is considered to be imbalanced.
+
+Note that lithium chemistry cells will almost always read similar voltages.  It
+is only near the top and bottom of charge that the slope of dV/dQ increases
+enough for small cell imbalances to be visible as a voltage difference.
+
+### `CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW`
+
+Optional.
+
+The minimum charger power level to allow Depthcharge to start up the kernel,
+even when the battery state of charge is less than
+`CHARGER_LIMIT_POWER_THRESH_BAT_PCT`, in milliwatts.
+
+When this term is `#undef`ined (the default), kernel startup is immediately
+allowed.
+
+#### `CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT`
+
+Optional.
+
+The minimum battery state of charge to allow Depthcharge to start up the kernel.
+When using this feature, start with `CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON`
+
+### `CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON_WITH_AC`
+
+Optional.
+
+Similar to `MIN_BAT_PCT_FOR_POWER_ON`, but used to define a secondary threshold
+for this feature.
+
+#### `CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON_WITH_BATT`
+
+Optional.
+
+Similar to `CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON`, this is the minimum
+charger power needed to boot even when the battery is less than
+`CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON_WITH_AC`
+
diff --git a/include/config.h b/include/config.h
index 2231491af5..79d9099b7a 100644
--- a/include/config.h
+++ b/include/config.h
@@ -712,10 +712,16 @@
  * Note that CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT/_CHG_MW are thresholds
  * for the OS boot used by Depthcharge. The OS has higher power requirement
  * but PD power is also available.
+ *
+ * WARNING: Locked RO firmware does not negotiate power greater than 15W via
+ * analog signaling.  If the AP requires greater than 15W to boot, then see
+ * CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW.
  */
 #undef CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON
 #undef CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON_WITH_AC
+/* Default: 15000 */
 #undef CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON
+/* Default: Disabled */
 #undef CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON_WITH_BATT
 
 /* Minimum battery percentage for power on with an imbalanced pack */
@@ -733,10 +739,21 @@
 /*
  * Low energy thresholds - when battery level is below BAT_PCT and an external
  * charger provides less than CHG_MW of power, inform the AP of the situation
- * through the LIMIT_POWER host event.
+ * through the LIMIT_POWER charge state parameter.  Depthcharge will hold off on
+ * the boot for up to 3 seconds while waiting for either condition to clear
+ * before starting the kernel.  This wait happens after sw sync in RW mode, so
+ * the firmware may set it high enough that PD negotiation is required to clear
+ * it.
+ *
+ * Default: Disabled.  Depthcharge is immediately released to boot the kernel.
+ *
+ * Setting this value to 15001 will require PD negotiation to be complete prior
+ * to releasing depthcharge.  During PD negotiation, the charger will be briefly
+ * reduced to about 2.5W for a few hundred ms.
  */
-#undef CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT
 #undef CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW
+/* Default: CHARGER_MIN_BAT_PCT_FOR_POWER_ON */
+#undef CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT
 
 /*
  * Enable charger's OTG functions, i.e. make it possible to supply output power
@@ -3839,12 +3856,12 @@
 
 /*
  * If a board has a chipset task, set the minimum charger power required for
- * powering on to 15W.  This is also the highest power discovered over Type-C.
- * The EC normally does not communicate using USB PD when the system is locked
- * and in RO, so it would not be able to tell if higher power is available.
- * However, if a 15W charger is discovered, it's likely that the charger does
- * speak USB PD and we would be able to negotiate more power after booting the
- * AP and jumping to EC RW.
+ * powering on to 15W.  This is also the highest power discovered over Type-C by
+ * analog signaling.  The EC normally does not communicate using USB PD when the
+ * system is locked and in RO, so it would not be able to tell if higher power
+ * is available.  However, if a 15W charger is discovered, it's likely that the
+ * charger does speak USB PD and we would be able to negotiate more power after
+ * booting the AP and jumping to EC RW.
  *
  * If a board needs more or less power to power on, they can re-define this
  * value in their board.h file.
@@ -3855,6 +3872,14 @@
 #endif /* !defined(CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON) */
 #endif /* defined(HAS_TASK_CHIPSET) */
 
+
+#ifdef CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW
+# ifndef CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT
+#  define CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT \
+	(CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON)
+# endif
+#endif
+
 #ifndef CONFIG_CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON
 /*
  * The function of MEASURE_BATTERY_IMBALANCE and these variables is to prevent a