Skip to content
This repository
Browse code

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: Rafael J. Wysocki <rjw@sisk.pl>
  • Loading branch information...
commit fafba48d4dd6fcbb1fd7ac4ab0ba22ef45b9796c 1 parent 9075659
Rafael J. Wysocki authored November 23, 2011

Showing 1 changed file with 38 additions and 22 deletions. Show diff stats Hide diff stats

  1. 60  Documentation/power/devices.txt
60  Documentation/power/devices.txt
@@ -140,41 +140,57 @@ sequencing in the driver model tree.
140 140
 
141 141
 /sys/devices/.../power/wakeup files
142 142
 -----------------------------------
143  
-All devices in the driver model have two flags to control handling of wakeup
144  
-events (hardware signals that can force the device and/or system out of a low
145  
-power state).  These flags are initialized by bus or device driver code using
  143
+All device objects in the driver model contain fields that control the handling
  144
+of system wakeup events (hardware signals that can force the system out of a
  145
+sleep state).  These fields are initialized by bus or device driver code using
146 146
 device_set_wakeup_capable() and device_set_wakeup_enable(), defined in
147 147
 include/linux/pm_wakeup.h.
148 148
 
149  
-The "can_wakeup" flag just records whether the device (and its driver) can
  149
+The "power.can_wakeup" flag just records whether the device (and its driver) can
150 150
 physically support wakeup events.  The device_set_wakeup_capable() routine
151  
-affects this flag.  The "should_wakeup" flag controls whether the device should
152  
-try to use its wakeup mechanism.  device_set_wakeup_enable() affects this flag;
153  
-for the most part drivers should not change its value.  The initial value of
154  
-should_wakeup is supposed to be false for the majority of devices; the major
155  
-exceptions are power buttons, keyboards, and Ethernet adapters whose WoL
156  
-(wake-on-LAN) feature has been set up with ethtool.  It should also default
157  
-to true for devices that don't generate wakeup requests on their own but merely
158  
-forward wakeup requests from one bus to another (like PCI bridges).
  151
+affects this flag.  The "power.wakeup" field is a pointer to an object of type
  152
+struct wakeup_source used for controlling whether or not the device should use
  153
+its system wakeup mechanism and for notifying the PM core of system wakeup
  154
+events signaled by the device.  This object is only present for wakeup-capable
  155
+devices (i.e. devices whose "can_wakeup" flags are set) and is created (or
  156
+removed) by device_set_wakeup_capable().
159 157
 
160 158
 Whether or not a device is capable of issuing wakeup events is a hardware
161 159
 matter, and the kernel is responsible for keeping track of it.  By contrast,
162 160
 whether or not a wakeup-capable device should issue wakeup events is a policy
163 161
 decision, and it is managed by user space through a sysfs attribute: the
164  
-power/wakeup file.  User space can write the strings "enabled" or "disabled" to
165  
-set or clear the "should_wakeup" flag, respectively.  This file is only present
166  
-for wakeup-capable devices (i.e. devices whose "can_wakeup" flags are set)
167  
-and is created (or removed) by device_set_wakeup_capable().  Reads from the
168  
-file will return the corresponding string.
169  
-
170  
-The device_may_wakeup() routine returns true only if both flags are set.
  162
+"power/wakeup" file.  User space can write the strings "enabled" or "disabled"
  163
+to it to indicate whether or not, respectively, the device is supposed to signal
  164
+system wakeup.  This file is only present if the "power.wakeup" object exists
  165
+for the given device and is created (or removed) along with that object, by
  166
+device_set_wakeup_capable().  Reads from the file will return the corresponding
  167
+string.
  168
+
  169
+The "power/wakeup" file is supposed to contain the "disabled" string initially
  170
+for the majority of devices; the major exceptions are power buttons, keyboards,
  171
+and Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with
  172
+ethtool.  It should also default to "enabled" for devices that don't generate
  173
+wakeup requests on their own but merely forward wakeup requests from one bus to
  174
+another (like PCI Express ports).
  175
+
  176
+The device_may_wakeup() routine returns true only if the "power.wakeup" object
  177
+exists and the corresponding "power/wakeup" file contains the string "enabled".
171 178
 This information is used by subsystems, like the PCI bus type code, to see
172 179
 whether or not to enable the devices' wakeup mechanisms.  If device wakeup
173 180
 mechanisms are enabled or disabled directly by drivers, they also should use
174 181
 device_may_wakeup() to decide what to do during a system sleep transition.
175  
-However for runtime power management, wakeup events should be enabled whenever
176  
-the device and driver both support them, regardless of the should_wakeup flag.
177  
-
  182
+Device drivers, however, are not supposed to call device_set_wakeup_enable()
  183
+directly in any case.
  184
+
  185
+It ought to be noted that system wakeup is conceptually different from "remote
  186
+wakeup" used by runtime power management, although it may be supported by the
  187
+same physical mechanism.  Remote wakeup is a feature allowing devices in
  188
+low-power states to trigger specific interrupts to signal conditions in which
  189
+they should be put into the full-power state.  Those interrupts may or may not
  190
+be used to signal system wakeup events, depending on the hardware design.  On
  191
+some systems it is impossible to trigger them from system sleep states.  In any
  192
+case, remote wakeup should always be enabled for runtime power management for
  193
+all devices and drivers that support it.
178 194
 
179 195
 /sys/devices/.../power/control files
180 196
 ------------------------------------

0 notes on commit fafba48

Please sign in to comment.
Something went wrong with that request. Please try again.