blob: d877297c857bdbc6daa99993f6fa014fbb016006 [file] [log] [blame] [view]
# Zephyr Hibernate Configuration
[TOC]
## Overview
Hibernate support puts the EC into the lowest operating power state. The EC
hibernate is distinct from the AP power states.
The EC is blocked from entering hibernation unless the following conditions are
true.
* AP power state is off (G3 or currently transitioning to G3 from S5).
* AC power is disconnected.
* Hibernate timer has expired.
EC chip types support different mechanisms for entering and exiting hibernate,
but there are some common characteristics:
* SRAM contents are not retained through hibernate
* Wake-up from hibernate is equivalent to a cold reset. The EC re-executes RO
code and jumps to RW code.
## Kconfig Options
The Kconfig option [`CONFIG_PLATFORM_EC_HIBERNATE`] enables hibernation support
in the EC application. The Kconfig option [`CONFIG_PLATFORM_EC_HIBERNATE_TYPE`]
selects the hibernate driver used by the platform.
There are 5 types of hibernate supported. Click through to the [Kconfig.system]
file for details on each type of hibernation.
1. [`CONFIG_PLATFORM_EC_HIBERNATE_PSL`]
1. [`CONFIG_PLATFORM_EC_HIBERNATE_VCI`]
1. [`CONFIG_PLATFORM_EC_HIBERNATE_ELPM`]
1. [`CONFIG_PLATFORM_EC_HIBERNATE_WAKE_PINS`]
1. [`CONFIG_PLATFORM_EC_HIBERNATE_Z5`]
The hibernate type is automatically configured based on the which devicetree
nodes are included in your project.
## Devicetree Nodes
### `CONFIG_PLATFORM_EC_HIBERNATE_PSL`
Supported by the Nuvoton NPCX families only. The `enabled-gpios` property in
the [`nuvoton,npcx-power-psl`] devictree node configures the GPIO corresponding
to the PSL_OUT signal.
The PSL_OUT signal is fixed based on the NPCX family. For reference, the
assignment of `enable-gpios` is noted below.
* [NPCX7 PSL_OUT]
* [NPCX9 PSL_OUT]
Use the `pinctrl-0` property to specify the list of PSL input (wake sources)
for the platform.
The PSL input wake sources varies based on the NPCX chip family.
* [NPCX7 PSL Inputs]
* [NPCX9 PSL Inputs]
For each PSL input, set the trigger mode and polarity of the signal. The set
the `pinctrl-0` property to the list of PSL inputs.
The final steps are to make sure the [`nuvoton,npcx-power-psl`] node is enabled
and the and the `pinctrl-names` property is set to `"sleep"`.
Example from the [Rex project]:
```
/* Power switch logic input pads */
&psl_in1_gpd2 {
/* LID_OPEN */
psl-in-mode = "edge";
psl-in-pol = "high-rising";
};
&psl_in2_gp00 {
/* ACOK_OD */
psl-in-mode = "edge";
psl-in-pol = "high-rising";
};
&psl_in4_gp02 {
/* MECH_PWR_BTN_ODL */
psl-in-mode = "edge";
psl-in-pol = "low-falling";
};
/* Power domain device controlled by PSL (Power Switch Logic) IO pads */
&power_ctrl_psl {
status = "okay";
pinctrl-names = "sleep";
pinctrl-0 = <&psl_in1_gpd2 &psl_in2_gp00 &psl_in4_gp02>;
};
```
### `CONFIG_PLATFORM_EC_HIBERNATE_VCI`
Supported by the Microchip EC family only. An example configuration of
the [`cros-ec,hibernate-vci-pin`] driver is shown below. This comes from the
[ptlrvp_mchp] project.
```
/ {
vci-pins{
#address-cells = <1>;
#size-cells = <0>;
/**
* Platform supports two wake-up sources:
* VCI_IN0: Power Button
* VCI_OVRD_IN: AC Present (using default register values)
*
* VCI_IN1: BATT_ID is enabled to allow system to reset when
* only battery is power source
*
* Note: Lid is not a wake-up source.
*/
vci_power_btn: vci_input_0@0 {
compatible = "cros-ec,hibernate-vci-pin";
reg = <0>;
vci-polarity = "Active_Low";
vci-latch-enable;
wakeup;
status = "okay";
};
vci_batt_id: vci_input_1@1 {
compatible = "cros-ec,hibernate-vci-pin";
reg = <1>;
vci-polarity = "Active_Low";
vci-latch-enable;
preserve;
status = "okay";
};
};
};
```
For details about configuring the VCI pin properties, refer to the
[`cros-ec,hibernate-vci-pin`] schema file.
### `CONFIG_PLATFORM_EC_HIBERNATE_ELPM`
Supported exclusively on ITE SoC families. Here is the example overlay
setting using the IT82000.BW SoC:
```
&power_ctrl_elpm {
status = "okay";
pinctrl-0 = <&xlpin0_gpq0_default>;
pinctrl-names = "default";
/* XLPIN[0](GPIO_G1): enabled, low-falling */
xlpin0: xlpin@0 { reg = <0>; polarity = "low-falling"; };
};
```
### `CONFIG_PLATFORM_EC_HIBERNATE_WAKE_PINS`
Supported by the ITE, Nuvoton, and Microchip ECs. The
[`cros-ec,hibernate-wake-pins`] node defines the interrupt signals that
will wake the EC from hibernate.
```
/ {
hibernate-wake-pins {
compatible = "cros-ec,hibernate-wake-pins";
wakeup-irqs = <&int_ac_present
&int_power_button
&int_lid_open>;
};
};
```
Each entry in the `wakeup-irqs` array references a platform interrupt signal
configured by the `"cros-ec,gpio-interrupts"` devictree node. Refer to the
[GPIO configuration](./zephyr_gpio.md) documentation for more information.
### `CONFIG_PLATFORM_EC_HIBERNATE_Z5`
The Hibernate Z5 implementation is supported by all EC chip types. The
[`cros-ec,hibernate-z5`] mode defines the GPIO connected to the EC used to
force the platform into the Z5 power state.
Discrete logic on the platform is responsible for transitioning the platform
back to Z1 and powering up the EC when a wake source is activated.
Example configuration from the [brox project]:
```
/{
hibernate_z5: hibernate-z5 {
compatible = "cros-ec,hibernate-z5";
en-slp-z-gpios = <&gpioa 0 GPIO_ACTIVE_HIGH>;
};
};
```
## Threads
EC hibernate support does not enable a dedicated thread. The hibernate support
monitors AP power state changes, and starts a timer when the AP power state
transitions to off.
## Testing and Debugging
### Shell Commands
Command | Description | Usage
:------ | :---------- | :----
`hibernate` | Hibernate the EC | `hibernate [seconds] [microseconds]`
`hibdelay` | Set the delay before going into hibernation | `hibdelay <seconds>`
Use the `hibernate` command to request the EC hibernate before the project
hibernation timeout expires. The AP power state must be off and AC must be
disconnected before the EC enters hibernate.
To verify the EC entered hibernate, shutdown the AP, disconnect AC, and run
the `hibernate` shell command. The EC should not respond to UART input, and
the EC should only wake up from hibernate for the configured wake sources. The
typical hibernate wake sources are:
* Power button press
* AC connection
* Lid open
Suspend wake sources, such as keyboard press and lid angle change, should not
wake the EC from hibernation.
Use the `hibdelay` command to override the project's hibernation timeout.
[`CONFIG_PLATFORM_EC_HIBERNATE`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.system?q=%22config%20PLATFORM_EC_HIBERNATE%22
[`CONFIG_PLATFORM_EC_HIBERNATE_TYPE`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.system?q=%22choice%20PLATFORM_EC_HIBERNATE_TYPE%22
[Kconfig.system]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.system
[`CONFIG_PLATFORM_EC_HIBERNATE_PSL`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.system?q=%22config%20PLATFORM_EC_HIBERNATE_PSL%22
[`CONFIG_PLATFORM_EC_HIBERNATE_VCI`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.system?q=%22config%20PLATFORM_EC_HIBERNATE_VCI%22
[`CONFIG_PLATFORM_EC_HIBERNATE_ELPM`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.system?q=%22config%20PLATFORM_EC_HIBERNATE_ELPM%22
[`CONFIG_PLATFORM_EC_HIBERNATE_WAKE_PINS`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.system?q=%22config%20PLATFORM_EC_HIBERNATE_WAKE_PINS%22
[`CONFIG_PLATFORM_EC_HIBERNATE_Z5`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.system?q=%22config%20PLATFORM_EC_HIBERNATE_Z5%22
[`nuvoton,npcx-power-psl`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/third_party/zephyr/main/dts/arm/nuvoton/npcx/npcx.dtsi?q=%22nuvoton,npcx-power-psl%22
[NPCX7 PSL_OUT]:https://source.corp.google.com/h/chrome-internal/chromeos/superproject/+/main:src/platform/ec/zephyr/boards/google/npcx7/npcx7.dts?q=enable-gpios
[NPCX9 PSL_OUT]:https://source.corp.google.com/h/chrome-internal/chromeos/superproject/+/main:src/platform/ec/zephyr/boards/google/npcx9/npcx9.dts?q=enable-gpios
[NPCX7 PSL inputs]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/third_party/zephyr/main/dts/arm/nuvoton/npcx/npcx7/npcx7-pinctrl.dtsi?q=%22PSL%20peripheral%20interfaces%22
[NPCX9 PSL inputs]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/third_party/zephyr/main/dts/arm/nuvoton/npcx/npcx9/npcx9-pinctrl.dtsi?q=%22PSL%20peripheral%20interfaces%22
[Rex project]:https://source.corp.google.com/h/chrome-internal/chromeos/superproject/+/main:src/platform/ec/zephyr/program/rex/rex.dtsi?q=%22Power%20switch%20logic%22
[`cros-ec,hibernate-vci-pin`]:https://source.corp.google.com/h/chrome-internal/chromeos/superproject/+/main:src/platform/ec/zephyr/dts/bindings/gpio/cros-ec,hibernate-vci-pin.yaml
[ptlrvp_mchp]:https://source.corp.google.com/h/chrome-internal/chromeos/superproject/+/main:src/platform/ec/zephyr/program/intelrvp/ptlrvp/ptlrvp_mchp/vci.dtsi;l=7?q=vci-pins
[`cros-ec,hibernate-wake-pins`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/gpio/cros-ec,hibernate-wake-pins.yaml
[`cros-ec,hibernate-z5`]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/hibernate/cros-ec,hibernate-z5.yaml
[brox project]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/program/brox/hibernate.dtsi