coreboot-mirror
/
chrome-ec
mirror of https://review.coreboot.org/chrome-ec.git
1
0
Fork 0
Code Issues Releases Wiki Activity

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
This commit is contained in:
Jonathan Brandmeyer 2018-08-17 15:11:08 -06:00 committed by chrome-bot
parent 54ad833b41
commit 7a377aff01
3 changed files with 462 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
common/charge_state_v2.c
View File

@ -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.

428
docs/low_battery_startup.md Normal file
View File

@ -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`

41
include/config.h
View File

@ -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