diff options
-rw-r--r-- | Documentation/power/runtime_pm.txt | 173 | ||||
-rw-r--r-- | drivers/base/power/runtime.c | 45 |
2 files changed, 132 insertions, 86 deletions
diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index 4a3109b28847..7b5ab2701247 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt | |||
@@ -42,80 +42,81 @@ struct dev_pm_ops { | |||
42 | ... | 42 | ... |
43 | }; | 43 | }; |
44 | 44 | ||
45 | The ->runtime_suspend() callback is executed by the PM core for the bus type of | 45 | The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks are |
46 | the device being suspended. The bus type's callback is then _entirely_ | 46 | executed by the PM core for either the bus type, or device type (if the bus |
47 | _responsible_ for handling the device as appropriate, which may, but need not | 47 | type's callback is not defined), or device class (if the bus type's and device |
48 | include executing the device driver's own ->runtime_suspend() callback (from the | 48 | type's callbacks are not defined) of given device. The bus type, device type |
49 | and device class callbacks are referred to as subsystem-level callbacks in what | ||
50 | follows. | ||
51 | |||
52 | The subsystem-level suspend callback is _entirely_ _responsible_ for handling | ||
53 | the suspend of the device as appropriate, which may, but need not include | ||
54 | executing the device driver's own ->runtime_suspend() callback (from the | ||
49 | PM core's point of view it is not necessary to implement a ->runtime_suspend() | 55 | PM core's point of view it is not necessary to implement a ->runtime_suspend() |
50 | callback in a device driver as long as the bus type's ->runtime_suspend() knows | 56 | callback in a device driver as long as the subsystem-level suspend callback |
51 | what to do to handle the device). | 57 | knows what to do to handle the device). |
52 | 58 | ||
53 | * Once the bus type's ->runtime_suspend() callback has completed successfully | 59 | * Once the subsystem-level suspend callback has completed successfully |
54 | for given device, the PM core regards the device as suspended, which need | 60 | for given device, the PM core regards the device as suspended, which need |
55 | not mean that the device has been put into a low power state. It is | 61 | not mean that the device has been put into a low power state. It is |
56 | supposed to mean, however, that the device will not process data and will | 62 | supposed to mean, however, that the device will not process data and will |
57 | not communicate with the CPU(s) and RAM until its bus type's | 63 | not communicate with the CPU(s) and RAM until the subsystem-level resume |
58 | ->runtime_resume() callback is executed for it. The run-time PM status of | 64 | callback is executed for it. The run-time PM status of a device after |
59 | a device after successful execution of its bus type's ->runtime_suspend() | 65 | successful execution of the subsystem-level suspend callback is 'suspended'. |
60 | callback is 'suspended'. | 66 | |
61 | 67 | * If the subsystem-level suspend callback returns -EBUSY or -EAGAIN, | |
62 | * If the bus type's ->runtime_suspend() callback returns -EBUSY or -EAGAIN, | 68 | the device's run-time PM status is 'active', which means that the device |
63 | the device's run-time PM status is supposed to be 'active', which means that | 69 | _must_ be fully operational afterwards. |
64 | the device _must_ be fully operational afterwards. | 70 | |
65 | 71 | * If the subsystem-level suspend callback returns an error code different | |
66 | * If the bus type's ->runtime_suspend() callback returns an error code | 72 | from -EBUSY or -EAGAIN, the PM core regards this as a fatal error and will |
67 | different from -EBUSY or -EAGAIN, the PM core regards this as a fatal | 73 | refuse to run the helper functions described in Section 4 for the device, |
68 | error and will refuse to run the helper functions described in Section 4 | 74 | until the status of it is directly set either to 'active', or to 'suspended' |
69 | for the device, until the status of it is directly set either to 'active' | 75 | (the PM core provides special helper functions for this purpose). |
70 | or to 'suspended' (the PM core provides special helper functions for this | 76 | |
71 | purpose). | 77 | In particular, if the driver requires remote wake-up capability (i.e. hardware |
72 | 78 | mechanism allowing the device to request a change of its power state, such as | |
73 | In particular, if the driver requires remote wakeup capability for proper | 79 | PCI PME) for proper functioning and device_run_wake() returns 'false' for the |
74 | functioning and device_run_wake() returns 'false' for the device, then | 80 | device, then ->runtime_suspend() should return -EBUSY. On the other hand, if |
75 | ->runtime_suspend() should return -EBUSY. On the other hand, if | 81 | device_run_wake() returns 'true' for the device and the device is put into a low |
76 | device_run_wake() returns 'true' for the device and the device is put | 82 | power state during the execution of the subsystem-level suspend callback, it is |
77 | into a low power state during the execution of its bus type's | 83 | expected that remote wake-up will be enabled for the device. Generally, remote |
78 | ->runtime_suspend(), it is expected that remote wake-up (i.e. hardware mechanism | 84 | wake-up should be enabled for all input devices put into a low power state at |
79 | allowing the device to request a change of its power state, such as PCI PME) | 85 | run time. |
80 | will be enabled for the device. Generally, remote wake-up should be enabled | 86 | |
81 | for all input devices put into a low power state at run time. | 87 | The subsystem-level resume callback is _entirely_ _responsible_ for handling the |
82 | 88 | resume of the device as appropriate, which may, but need not include executing | |
83 | The ->runtime_resume() callback is executed by the PM core for the bus type of | 89 | the device driver's own ->runtime_resume() callback (from the PM core's point of |
84 | the device being woken up. The bus type's callback is then _entirely_ | 90 | view it is not necessary to implement a ->runtime_resume() callback in a device |
85 | _responsible_ for handling the device as appropriate, which may, but need not | 91 | driver as long as the subsystem-level resume callback knows what to do to handle |
86 | include executing the device driver's own ->runtime_resume() callback (from the | 92 | the device). |
87 | PM core's point of view it is not necessary to implement a ->runtime_resume() | 93 | |
88 | callback in a device driver as long as the bus type's ->runtime_resume() knows | 94 | * Once the subsystem-level resume callback has completed successfully, the PM |
89 | what to do to handle the device). | 95 | core regards the device as fully operational, which means that the device |
90 | 96 | _must_ be able to complete I/O operations as needed. The run-time PM status | |
91 | * Once the bus type's ->runtime_resume() callback has completed successfully, | 97 | of the device is then 'active'. |
92 | the PM core regards the device as fully operational, which means that the | 98 | |
93 | device _must_ be able to complete I/O operations as needed. The run-time | 99 | * If the subsystem-level resume callback returns an error code, the PM core |
94 | PM status of the device is then 'active'. | 100 | regards this as a fatal error and will refuse to run the helper functions |
95 | 101 | described in Section 4 for the device, until its status is directly set | |
96 | * If the bus type's ->runtime_resume() callback returns an error code, the PM | 102 | either to 'active' or to 'suspended' (the PM core provides special helper |
97 | core regards this as a fatal error and will refuse to run the helper | 103 | functions for this purpose). |
98 | functions described in Section 4 for the device, until its status is | 104 | |
99 | directly set either to 'active' or to 'suspended' (the PM core provides | 105 | The subsystem-level idle callback is executed by the PM core whenever the device |
100 | special helper functions for this purpose). | 106 | appears to be idle, which is indicated to the PM core by two counters, the |
101 | 107 | device's usage counter and the counter of 'active' children of the device. | |
102 | The ->runtime_idle() callback is executed by the PM core for the bus type of | ||
103 | given device whenever the device appears to be idle, which is indicated to the | ||
104 | PM core by two counters, the device's usage counter and the counter of 'active' | ||
105 | children of the device. | ||
106 | 108 | ||
107 | * If any of these counters is decreased using a helper function provided by | 109 | * If any of these counters is decreased using a helper function provided by |
108 | the PM core and it turns out to be equal to zero, the other counter is | 110 | the PM core and it turns out to be equal to zero, the other counter is |
109 | checked. If that counter also is equal to zero, the PM core executes the | 111 | checked. If that counter also is equal to zero, the PM core executes the |
110 | device bus type's ->runtime_idle() callback (with the device as an | 112 | subsystem-level idle callback with the device as an argument. |
111 | argument). | ||
112 | 113 | ||
113 | The action performed by a bus type's ->runtime_idle() callback is totally | 114 | The action performed by a subsystem-level idle callback is totally dependent on |
114 | dependent on the bus type in question, but the expected and recommended action | 115 | the subsystem in question, but the expected and recommended action is to check |
115 | is to check if the device can be suspended (i.e. if all of the conditions | 116 | if the device can be suspended (i.e. if all of the conditions necessary for |
116 | necessary for suspending the device are satisfied) and to queue up a suspend | 117 | suspending the device are satisfied) and to queue up a suspend request for the |
117 | request for the device in that case. The value returned by this callback is | 118 | device in that case. The value returned by this callback is ignored by the PM |
118 | ignored by the PM core. | 119 | core. |
119 | 120 | ||
120 | The helper functions provided by the PM core, described in Section 4, guarantee | 121 | The helper functions provided by the PM core, described in Section 4, guarantee |
121 | that the following constraints are met with respect to the bus type's run-time | 122 | that the following constraints are met with respect to the bus type's run-time |
@@ -238,41 +239,41 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: | |||
238 | removing the device from device hierarchy | 239 | removing the device from device hierarchy |
239 | 240 | ||
240 | int pm_runtime_idle(struct device *dev); | 241 | int pm_runtime_idle(struct device *dev); |
241 | - execute ->runtime_idle() for the device's bus type; returns 0 on success | 242 | - execute the subsystem-level idle callback for the device; returns 0 on |
242 | or error code on failure, where -EINPROGRESS means that ->runtime_idle() | 243 | success or error code on failure, where -EINPROGRESS means that |
243 | is already being executed | 244 | ->runtime_idle() is already being executed |
244 | 245 | ||
245 | int pm_runtime_suspend(struct device *dev); | 246 | int pm_runtime_suspend(struct device *dev); |
246 | - execute ->runtime_suspend() for the device's bus type; returns 0 on | 247 | - execute the subsystem-level suspend callback for the device; returns 0 on |
247 | success, 1 if the device's run-time PM status was already 'suspended', or | 248 | success, 1 if the device's run-time PM status was already 'suspended', or |
248 | error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt | 249 | error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt |
249 | to suspend the device again in future | 250 | to suspend the device again in future |
250 | 251 | ||
251 | int pm_runtime_resume(struct device *dev); | 252 | int pm_runtime_resume(struct device *dev); |
252 | - execute ->runtime_resume() for the device's bus type; returns 0 on | 253 | - execute the subsystem-leve resume callback for the device; returns 0 on |
253 | success, 1 if the device's run-time PM status was already 'active' or | 254 | success, 1 if the device's run-time PM status was already 'active' or |
254 | error code on failure, where -EAGAIN means it may be safe to attempt to | 255 | error code on failure, where -EAGAIN means it may be safe to attempt to |
255 | resume the device again in future, but 'power.runtime_error' should be | 256 | resume the device again in future, but 'power.runtime_error' should be |
256 | checked additionally | 257 | checked additionally |
257 | 258 | ||
258 | int pm_request_idle(struct device *dev); | 259 | int pm_request_idle(struct device *dev); |
259 | - submit a request to execute ->runtime_idle() for the device's bus type | 260 | - submit a request to execute the subsystem-level idle callback for the |
260 | (the request is represented by a work item in pm_wq); returns 0 on success | 261 | device (the request is represented by a work item in pm_wq); returns 0 on |
261 | or error code if the request has not been queued up | 262 | success or error code if the request has not been queued up |
262 | 263 | ||
263 | int pm_schedule_suspend(struct device *dev, unsigned int delay); | 264 | int pm_schedule_suspend(struct device *dev, unsigned int delay); |
264 | - schedule the execution of ->runtime_suspend() for the device's bus type | 265 | - schedule the execution of the subsystem-level suspend callback for the |
265 | in future, where 'delay' is the time to wait before queuing up a suspend | 266 | device in future, where 'delay' is the time to wait before queuing up a |
266 | work item in pm_wq, in milliseconds (if 'delay' is zero, the work item is | 267 | suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work |
267 | queued up immediately); returns 0 on success, 1 if the device's PM | 268 | item is queued up immediately); returns 0 on success, 1 if the device's PM |
268 | run-time status was already 'suspended', or error code if the request | 269 | run-time status was already 'suspended', or error code if the request |
269 | hasn't been scheduled (or queued up if 'delay' is 0); if the execution of | 270 | hasn't been scheduled (or queued up if 'delay' is 0); if the execution of |
270 | ->runtime_suspend() is already scheduled and not yet expired, the new | 271 | ->runtime_suspend() is already scheduled and not yet expired, the new |
271 | value of 'delay' will be used as the time to wait | 272 | value of 'delay' will be used as the time to wait |
272 | 273 | ||
273 | int pm_request_resume(struct device *dev); | 274 | int pm_request_resume(struct device *dev); |
274 | - submit a request to execute ->runtime_resume() for the device's bus type | 275 | - submit a request to execute the subsystem-level resume callback for the |
275 | (the request is represented by a work item in pm_wq); returns 0 on | 276 | device (the request is represented by a work item in pm_wq); returns 0 on |
276 | success, 1 if the device's run-time PM status was already 'active', or | 277 | success, 1 if the device's run-time PM status was already 'active', or |
277 | error code if the request hasn't been queued up | 278 | error code if the request hasn't been queued up |
278 | 279 | ||
@@ -303,12 +304,12 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: | |||
303 | run-time PM callbacks described in Section 2 | 304 | run-time PM callbacks described in Section 2 |
304 | 305 | ||
305 | int pm_runtime_disable(struct device *dev); | 306 | int pm_runtime_disable(struct device *dev); |
306 | - prevent the run-time PM helper functions from running the device bus | 307 | - prevent the run-time PM helper functions from running subsystem-level |
307 | type's run-time PM callbacks, make sure that all of the pending run-time | 308 | run-time PM callbacks for the device, make sure that all of the pending |
308 | PM operations on the device are either completed or canceled; returns | 309 | run-time PM operations on the device are either completed or canceled; |
309 | 1 if there was a resume request pending and it was necessary to execute | 310 | returns 1 if there was a resume request pending and it was necessary to |
310 | ->runtime_resume() for the device's bus type to satisfy that request, | 311 | execute the subsystem-level resume callback for the device to satisfy that |
311 | otherwise 0 is returned | 312 | request, otherwise 0 is returned |
312 | 313 | ||
313 | void pm_suspend_ignore_children(struct device *dev, bool enable); | 314 | void pm_suspend_ignore_children(struct device *dev, bool enable); |
314 | - set/unset the power.ignore_children flag of the device | 315 | - set/unset the power.ignore_children flag of the device |
@@ -378,5 +379,5 @@ pm_runtime_suspend() or pm_runtime_idle() or their asynchronous counterparts, | |||
378 | they will fail returning -EAGAIN, because the device's usage counter is | 379 | they will fail returning -EAGAIN, because the device's usage counter is |
379 | incremented by the core before executing ->probe() and ->remove(). Still, it | 380 | incremented by the core before executing ->probe() and ->remove(). Still, it |
380 | may be desirable to suspend the device as soon as ->probe() or ->remove() has | 381 | may be desirable to suspend the device as soon as ->probe() or ->remove() has |
381 | finished, so the PM core uses pm_runtime_idle_sync() to invoke the device bus | 382 | finished, so the PM core uses pm_runtime_idle_sync() to invoke the |
382 | type's ->runtime_idle() callback at that time. | 383 | subsystem-level idle callback for the device at that time. |
diff --git a/drivers/base/power/runtime.c b/drivers/base/power/runtime.c index 40d7720a4b21..f8b044e8aef7 100644 --- a/drivers/base/power/runtime.c +++ b/drivers/base/power/runtime.c | |||
@@ -85,6 +85,19 @@ static int __pm_runtime_idle(struct device *dev) | |||
85 | dev->bus->pm->runtime_idle(dev); | 85 | dev->bus->pm->runtime_idle(dev); |
86 | 86 | ||
87 | spin_lock_irq(&dev->power.lock); | 87 | spin_lock_irq(&dev->power.lock); |
88 | } else if (dev->type && dev->type->pm && dev->type->pm->runtime_idle) { | ||
89 | spin_unlock_irq(&dev->power.lock); | ||
90 | |||
91 | dev->type->pm->runtime_idle(dev); | ||
92 | |||
93 | spin_lock_irq(&dev->power.lock); | ||
94 | } else if (dev->class && dev->class->pm | ||
95 | && dev->class->pm->runtime_idle) { | ||
96 | spin_unlock_irq(&dev->power.lock); | ||
97 | |||
98 | dev->class->pm->runtime_idle(dev); | ||
99 | |||
100 | spin_lock_irq(&dev->power.lock); | ||
88 | } | 101 | } |
89 | 102 | ||
90 | dev->power.idle_notification = false; | 103 | dev->power.idle_notification = false; |
@@ -194,6 +207,22 @@ int __pm_runtime_suspend(struct device *dev, bool from_wq) | |||
194 | 207 | ||
195 | spin_lock_irq(&dev->power.lock); | 208 | spin_lock_irq(&dev->power.lock); |
196 | dev->power.runtime_error = retval; | 209 | dev->power.runtime_error = retval; |
210 | } else if (dev->type && dev->type->pm | ||
211 | && dev->type->pm->runtime_suspend) { | ||
212 | spin_unlock_irq(&dev->power.lock); | ||
213 | |||
214 | retval = dev->type->pm->runtime_suspend(dev); | ||
215 | |||
216 | spin_lock_irq(&dev->power.lock); | ||
217 | dev->power.runtime_error = retval; | ||
218 | } else if (dev->class && dev->class->pm | ||
219 | && dev->class->pm->runtime_suspend) { | ||
220 | spin_unlock_irq(&dev->power.lock); | ||
221 | |||
222 | retval = dev->class->pm->runtime_suspend(dev); | ||
223 | |||
224 | spin_lock_irq(&dev->power.lock); | ||
225 | dev->power.runtime_error = retval; | ||
197 | } else { | 226 | } else { |
198 | retval = -ENOSYS; | 227 | retval = -ENOSYS; |
199 | } | 228 | } |
@@ -359,6 +388,22 @@ int __pm_runtime_resume(struct device *dev, bool from_wq) | |||
359 | 388 | ||
360 | spin_lock_irq(&dev->power.lock); | 389 | spin_lock_irq(&dev->power.lock); |
361 | dev->power.runtime_error = retval; | 390 | dev->power.runtime_error = retval; |
391 | } else if (dev->type && dev->type->pm | ||
392 | && dev->type->pm->runtime_resume) { | ||
393 | spin_unlock_irq(&dev->power.lock); | ||
394 | |||
395 | retval = dev->type->pm->runtime_resume(dev); | ||
396 | |||
397 | spin_lock_irq(&dev->power.lock); | ||
398 | dev->power.runtime_error = retval; | ||
399 | } else if (dev->class && dev->class->pm | ||
400 | && dev->class->pm->runtime_resume) { | ||
401 | spin_unlock_irq(&dev->power.lock); | ||
402 | |||
403 | retval = dev->class->pm->runtime_resume(dev); | ||
404 | |||
405 | spin_lock_irq(&dev->power.lock); | ||
406 | dev->power.runtime_error = retval; | ||
362 | } else { | 407 | } else { |
363 | retval = -ENOSYS; | 408 | retval = -ENOSYS; |
364 | } | 409 | } |