R-Car/Tests:System-Suspend-and-Wake-Up

This document describes test procedures for System Suspend and Wake-Up on Renesas ARM boards.

= System Suspend =

System Suspend allows to suspend the system to save power, and wake up the system to continue running later.

Linux supports up to four system suspend states:
 * Suspend-to-Idle aka s2idle (freeze): The system is frozen,
 * Standby / Power-On Suspend aka shallow (standby): Similar to Suspend-to-Idle (not covered here),
 * Suspend-to-RAM aka deep (mem): System state is retained in RAM, some system components may be powered down,
 * Suspend-to-Disk (disk): System state is stored to disk, and the system is powered down (not covered here).

Not all states are available on all systems.

= Wake-Up Sources =

When the system is suspended, it can be woken up using one or more wake-up sources, after which normal operation is resumed.

Which wake-up sources are available in which suspend state depends on the actual system. While Suspend-to-Idle supports all wake-up sources configured by Linux, this may not be the case for deeper suspend states.
 * On Renesas 32-bit ARM systems, Suspend-to-RAM doesn't power down the SoC, and all wake-up sources supported by Suspend-to-Idle are also supported by Suspend-to-RAM,
 * On Renesas 64-bit ARM systems, Suspend-to-RAM calls into PSCI, which asks the PMIC to power down the SoC. Hence only the PMIC can wake up the system.  Make sure to use Suspend-to-Idle if you want to use standard wake-up sources.

= Operation =

freeze mem
 * You can check which suspend states are available using:
 * 1) cat /sys/power/state

echo > /sys/power/state    # freeze, standby, mem, or disk
 * In general, the system is suspended to one of the suspend states using:


 * On some systems, additional setup steps may need to be performed before suspending the system. Please refer to the individual board pages for more information.

echo > /sys/power/mem_sleep # s2idle, shallow, or deep
 * As of v4.10, you can configure which state to use for Suspend-to-RAM (mem, default is deepest available):

name              active_count  event_count  wakeup_count  expire_count  active_since  total_time  max_time  last_change  prevent_suspend_time e6800000.ethernet 1             1            0             0             0             0           0         679148       0 keyboard          0             0            0             0             0             0           0         1197194      0 deleted           0             0            0             0             0             0           0         0            0
 * You can obtain a list of enabled wake-up sources and wake statistics using:
 * 1) cat /sys/kernel/debug/wakeup_sources

enabled disabled
 * You can control if a device is enabled for wake-up by manipulating sysfs, e.g.:
 * 1) cat /sys/devices/platform/keyboard/power/wakeup
 * 1) echo disabled > /sys/devices/platform/keyboard/power/wakeup
 * 2) cat /sys/devices/platform/keyboard/power/wakeup

= Board Specifics =

Supported suspend states and wake-up methods for each board can be found on the individual boards' pages:
 * Atmark Techno Armadillo-800 EVA
 * KMC KZM-A9-GT
 * Renesas APE6-EVM
 * Renesas Koelsch
 * Renesas Salvator-X
 * Renesas Salvator-XS

= Clock and Power Domain Considerations =

If a device in a Renesas ARM SoC is part of a Clock or Power Domain, and it is used as a wake-up source, or part of the wake-up path, it must be kept active during system suspend.

Currently this is handled in device-specific drivers by explicitly increasing the use count of the module clock when the device is configured as a wake-up source, or if it is part of the wake-up path. However, this is merely a workaround. And while this may work for devices part of a Clock Domain, it is not sufficient for devices part of a Power Domain (currently that works by chance because the affected Power Domain is kept powered for other reasons, e.g. because it is a parent of the CPU Power Domain).

The proper way to prevent the device from being stopped is to inform this requirement to the PM Domain core. This involves two parts:
 * 1) PM Domain drivers must declare that slave devices need to be kept active if involved in wake-up (this was already done for SH/R-Mobile SoCs, but not for R-Car, RZ/A1, and RZ/G1 SoCs),
 * 2) Interrupt controller drivers must indicate they are part of the wake-up path, when applicable.

With the above fixed, all clock workarounds can be removed.

= Topic Branches =


 * A topic branch with the above issues fixed, and all clock workarounds removed, can be found at renesas-drivers#topic/rcar-genpd-wakeup-v3,
 * A topic branch with all clock workarounds removed, but no core issues fixed (and thus broken wake-up behavior), can be found at renesas-drivers#topic/rcar-genpd-wakeup-broken.

= Debugging =

echo 0 > /sys/module/printk/parameters/console_suspend
 * The console can be kept enabled during system suspend using:

for i in freezer devices platform processors core none; do	echo Trying $i echo $i > /sys/power/pm_test echo mem > /sys/power/state done
 * You can test all suspend states and steps using:

= See Also =


 * SH EtherMAC Wake-on-Lan