diff options
Diffstat (limited to 'docs/low_battery_startup.md')
| -rw-r--r-- | docs/low_battery_startup.md | 420 |
1 files changed, 0 insertions, 420 deletions
diff --git a/docs/low_battery_startup.md b/docs/low_battery_startup.md deleted file mode 100644 index 48f9c28f49..0000000000 --- a/docs/low_battery_startup.md +++ /dev/null @@ -1,420 +0,0 @@ -# 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/max14637.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 vb2ex_ec_vboot_done() 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` |