Commit fafba48d authored by Rafael J. Wysocki's avatar Rafael J. Wysocki

PM / Sleep: Update documentation related to system wakeup

The system wakeup section of Documentation/power/devices.txt is
outdated, so make it agree with the current code.
Signed-off-by: default avatarRafael J. Wysocki <rjw@sisk.pl>
parent 90756592
...@@ -140,41 +140,57 @@ sequencing in the driver model tree. ...@@ -140,41 +140,57 @@ sequencing in the driver model tree.
/sys/devices/.../power/wakeup files /sys/devices/.../power/wakeup files
----------------------------------- -----------------------------------
All devices in the driver model have two flags to control handling of wakeup All device objects in the driver model contain fields that control the handling
events (hardware signals that can force the device and/or system out of a low of system wakeup events (hardware signals that can force the system out of a
power state). These flags are initialized by bus or device driver code using sleep state). These fields are initialized by bus or device driver code using
device_set_wakeup_capable() and device_set_wakeup_enable(), defined in device_set_wakeup_capable() and device_set_wakeup_enable(), defined in
include/linux/pm_wakeup.h. include/linux/pm_wakeup.h.
The "can_wakeup" flag just records whether the device (and its driver) can The "power.can_wakeup" flag just records whether the device (and its driver) can
physically support wakeup events. The device_set_wakeup_capable() routine physically support wakeup events. The device_set_wakeup_capable() routine
affects this flag. The "should_wakeup" flag controls whether the device should affects this flag. The "power.wakeup" field is a pointer to an object of type
try to use its wakeup mechanism. device_set_wakeup_enable() affects this flag; struct wakeup_source used for controlling whether or not the device should use
for the most part drivers should not change its value. The initial value of its system wakeup mechanism and for notifying the PM core of system wakeup
should_wakeup is supposed to be false for the majority of devices; the major events signaled by the device. This object is only present for wakeup-capable
exceptions are power buttons, keyboards, and Ethernet adapters whose WoL devices (i.e. devices whose "can_wakeup" flags are set) and is created (or
(wake-on-LAN) feature has been set up with ethtool. It should also default removed) by device_set_wakeup_capable().
to true for devices that don't generate wakeup requests on their own but merely
forward wakeup requests from one bus to another (like PCI bridges).
Whether or not a device is capable of issuing wakeup events is a hardware Whether or not a device is capable of issuing wakeup events is a hardware
matter, and the kernel is responsible for keeping track of it. By contrast, matter, and the kernel is responsible for keeping track of it. By contrast,
whether or not a wakeup-capable device should issue wakeup events is a policy whether or not a wakeup-capable device should issue wakeup events is a policy
decision, and it is managed by user space through a sysfs attribute: the decision, and it is managed by user space through a sysfs attribute: the
power/wakeup file. User space can write the strings "enabled" or "disabled" to "power/wakeup" file. User space can write the strings "enabled" or "disabled"
set or clear the "should_wakeup" flag, respectively. This file is only present to it to indicate whether or not, respectively, the device is supposed to signal
for wakeup-capable devices (i.e. devices whose "can_wakeup" flags are set) system wakeup. This file is only present if the "power.wakeup" object exists
and is created (or removed) by device_set_wakeup_capable(). Reads from the for the given device and is created (or removed) along with that object, by
file will return the corresponding string. device_set_wakeup_capable(). Reads from the file will return the corresponding
string.
The device_may_wakeup() routine returns true only if both flags are set.
The "power/wakeup" file is supposed to contain the "disabled" string initially
for the majority of devices; the major exceptions are power buttons, keyboards,
and Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with
ethtool. It should also default to "enabled" for devices that don't generate
wakeup requests on their own but merely forward wakeup requests from one bus to
another (like PCI Express ports).
The device_may_wakeup() routine returns true only if the "power.wakeup" object
exists and the corresponding "power/wakeup" file contains the string "enabled".
This information is used by subsystems, like the PCI bus type code, to see This information is used by subsystems, like the PCI bus type code, to see
whether or not to enable the devices' wakeup mechanisms. If device wakeup whether or not to enable the devices' wakeup mechanisms. If device wakeup
mechanisms are enabled or disabled directly by drivers, they also should use mechanisms are enabled or disabled directly by drivers, they also should use
device_may_wakeup() to decide what to do during a system sleep transition. device_may_wakeup() to decide what to do during a system sleep transition.
However for runtime power management, wakeup events should be enabled whenever Device drivers, however, are not supposed to call device_set_wakeup_enable()
the device and driver both support them, regardless of the should_wakeup flag. directly in any case.
It ought to be noted that system wakeup is conceptually different from "remote
wakeup" used by runtime power management, although it may be supported by the
same physical mechanism. Remote wakeup is a feature allowing devices in
low-power states to trigger specific interrupts to signal conditions in which
they should be put into the full-power state. Those interrupts may or may not
be used to signal system wakeup events, depending on the hardware design. On
some systems it is impossible to trigger them from system sleep states. In any
case, remote wakeup should always be enabled for runtime power management for
all devices and drivers that support it.
/sys/devices/.../power/control files /sys/devices/.../power/control files
------------------------------------ ------------------------------------
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment