aboutsummaryrefslogtreecommitdiffstats
path: root/drivers/base
diff options
context:
space:
mode:
authorRafael J. Wysocki <rjw@sisk.pl>2009-08-20 14:25:52 -0400
committerRafael J. Wysocki <rjw@sisk.pl>2009-09-14 14:27:00 -0400
commit20d652d7d1c2f202215ecf0306ccecc3569df9ba (patch)
treef08619cec4964478d764477ca45931f7d49401a3 /drivers/base
parent9d62ec6ca71d71c8a0d2cb1004f476d33f668955 (diff)
PM: Update kerneldoc comments in drivers/base/power/main.c
The kerneldoc comments in drivers/base/power/main.c are generally outdated and some of them don't describe the functions very accurately. Update them and standardize the format to use spaces instead of tabs. Signed-off-by: Rafael J. Wysocki <rjw@sisk.pl> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Acked-by: Greg Kroah-Hartman <gregkh@suse.de> Acked-by: Alan Stern <stern@rowland.harvard.edu>
Diffstat (limited to 'drivers/base')
-rw-r--r--drivers/base/power/main.c169
1 files changed, 84 insertions, 85 deletions
diff --git a/drivers/base/power/main.c b/drivers/base/power/main.c
index 86990011277b..b0899118569b 100644
--- a/drivers/base/power/main.c
+++ b/drivers/base/power/main.c
@@ -50,7 +50,7 @@ static DEFINE_MUTEX(dpm_list_mtx);
50static bool transition_started; 50static bool transition_started;
51 51
52/** 52/**
53 * device_pm_init - Initialize the PM-related part of a device object 53 * device_pm_init - Initialize the PM-related part of a device object.
54 * @dev: Device object being initialized. 54 * @dev: Device object being initialized.
55 */ 55 */
56void device_pm_init(struct device *dev) 56void device_pm_init(struct device *dev)
@@ -60,7 +60,7 @@ void device_pm_init(struct device *dev)
60} 60}
61 61
62/** 62/**
63 * device_pm_lock - lock the list of active devices used by the PM core 63 * device_pm_lock - Lock the list of active devices used by the PM core.
64 */ 64 */
65void device_pm_lock(void) 65void device_pm_lock(void)
66{ 66{
@@ -68,7 +68,7 @@ void device_pm_lock(void)
68} 68}
69 69
70/** 70/**
71 * device_pm_unlock - unlock the list of active devices used by the PM core 71 * device_pm_unlock - Unlock the list of active devices used by the PM core.
72 */ 72 */
73void device_pm_unlock(void) 73void device_pm_unlock(void)
74{ 74{
@@ -76,8 +76,8 @@ void device_pm_unlock(void)
76} 76}
77 77
78/** 78/**
79 * device_pm_add - add a device to the list of active devices 79 * device_pm_add - Add a device to the PM core's list of active devices.
80 * @dev: Device to be added to the list 80 * @dev: Device to add to the list.
81 */ 81 */
82void device_pm_add(struct device *dev) 82void device_pm_add(struct device *dev)
83{ 83{
@@ -103,10 +103,8 @@ void device_pm_add(struct device *dev)
103} 103}
104 104
105/** 105/**
106 * device_pm_remove - remove a device from the list of active devices 106 * device_pm_remove - Remove a device from the PM core's list of active devices.
107 * @dev: Device to be removed from the list 107 * @dev: Device to be removed from the list.
108 *
109 * This function also removes the device's PM-related sysfs attributes.
110 */ 108 */
111void device_pm_remove(struct device *dev) 109void device_pm_remove(struct device *dev)
112{ 110{
@@ -120,9 +118,9 @@ void device_pm_remove(struct device *dev)
120} 118}
121 119
122/** 120/**
123 * device_pm_move_before - move device in dpm_list 121 * device_pm_move_before - Move device in the PM core's list of active devices.
124 * @deva: Device to move in dpm_list 122 * @deva: Device to move in dpm_list.
125 * @devb: Device @deva should come before 123 * @devb: Device @deva should come before.
126 */ 124 */
127void device_pm_move_before(struct device *deva, struct device *devb) 125void device_pm_move_before(struct device *deva, struct device *devb)
128{ 126{
@@ -136,9 +134,9 @@ void device_pm_move_before(struct device *deva, struct device *devb)
136} 134}
137 135
138/** 136/**
139 * device_pm_move_after - move device in dpm_list 137 * device_pm_move_after - Move device in the PM core's list of active devices.
140 * @deva: Device to move in dpm_list 138 * @deva: Device to move in dpm_list.
141 * @devb: Device @deva should come after 139 * @devb: Device @deva should come after.
142 */ 140 */
143void device_pm_move_after(struct device *deva, struct device *devb) 141void device_pm_move_after(struct device *deva, struct device *devb)
144{ 142{
@@ -152,8 +150,8 @@ void device_pm_move_after(struct device *deva, struct device *devb)
152} 150}
153 151
154/** 152/**
155 * device_pm_move_last - move device to end of dpm_list 153 * device_pm_move_last - Move device to end of the PM core's list of devices.
156 * @dev: Device to move in dpm_list 154 * @dev: Device to move in dpm_list.
157 */ 155 */
158void device_pm_move_last(struct device *dev) 156void device_pm_move_last(struct device *dev)
159{ 157{
@@ -164,10 +162,10 @@ void device_pm_move_last(struct device *dev)
164} 162}
165 163
166/** 164/**
167 * pm_op - execute the PM operation appropiate for given PM event 165 * pm_op - Execute the PM operation appropriate for given PM event.
168 * @dev: Device. 166 * @dev: Device to handle.
169 * @ops: PM operations to choose from. 167 * @ops: PM operations to choose from.
170 * @state: PM transition of the system being carried out. 168 * @state: PM transition of the system being carried out.
171 */ 169 */
172static int pm_op(struct device *dev, 170static int pm_op(struct device *dev,
173 const struct dev_pm_ops *ops, 171 const struct dev_pm_ops *ops,
@@ -225,13 +223,13 @@ static int pm_op(struct device *dev,
225} 223}
226 224
227/** 225/**
228 * pm_noirq_op - execute the PM operation appropiate for given PM event 226 * pm_noirq_op - Execute the PM operation appropriate for given PM event.
229 * @dev: Device. 227 * @dev: Device to handle.
230 * @ops: PM operations to choose from. 228 * @ops: PM operations to choose from.
231 * @state: PM transition of the system being carried out. 229 * @state: PM transition of the system being carried out.
232 * 230 *
233 * The operation is executed with interrupts disabled by the only remaining 231 * The driver of @dev will not receive interrupts while this function is being
234 * functional CPU in the system. 232 * executed.
235 */ 233 */
236static int pm_noirq_op(struct device *dev, 234static int pm_noirq_op(struct device *dev,
237 const struct dev_pm_ops *ops, 235 const struct dev_pm_ops *ops,
@@ -329,11 +327,12 @@ static void pm_dev_err(struct device *dev, pm_message_t state, char *info,
329/*------------------------- Resume routines -------------------------*/ 327/*------------------------- Resume routines -------------------------*/
330 328
331/** 329/**
332 * device_resume_noirq - Power on one device (early resume). 330 * device_resume_noirq - Execute an "early resume" callback for given device.
333 * @dev: Device. 331 * @dev: Device to handle.
334 * @state: PM transition of the system being carried out. 332 * @state: PM transition of the system being carried out.
335 * 333 *
336 * Must be called with interrupts disabled. 334 * The driver of @dev will not receive interrupts while this function is being
335 * executed.
337 */ 336 */
338static int device_resume_noirq(struct device *dev, pm_message_t state) 337static int device_resume_noirq(struct device *dev, pm_message_t state)
339{ 338{
@@ -355,14 +354,11 @@ static int device_resume_noirq(struct device *dev, pm_message_t state)
355} 354}
356 355
357/** 356/**
358 * dpm_resume_noirq - Power on all regular (non-sysdev) devices. 357 * dpm_resume_noirq - Execute "early resume" callbacks for non-sysdev devices.
359 * @state: PM transition of the system being carried out. 358 * @state: PM transition of the system being carried out.
360 *
361 * Call the "noirq" resume handlers for all devices marked as
362 * DPM_OFF_IRQ and enable device drivers to receive interrupts.
363 * 359 *
364 * Must be called under dpm_list_mtx. Device drivers should not receive 360 * Call the "noirq" resume handlers for all devices marked as DPM_OFF_IRQ and
365 * interrupts while it's being executed. 361 * enable device drivers to receive interrupts.
366 */ 362 */
367void dpm_resume_noirq(pm_message_t state) 363void dpm_resume_noirq(pm_message_t state)
368{ 364{
@@ -384,9 +380,9 @@ void dpm_resume_noirq(pm_message_t state)
384EXPORT_SYMBOL_GPL(dpm_resume_noirq); 380EXPORT_SYMBOL_GPL(dpm_resume_noirq);
385 381
386/** 382/**
387 * device_resume - Restore state for one device. 383 * device_resume - Execute "resume" callbacks for given device.
388 * @dev: Device. 384 * @dev: Device to handle.
389 * @state: PM transition of the system being carried out. 385 * @state: PM transition of the system being carried out.
390 */ 386 */
391static int device_resume(struct device *dev, pm_message_t state) 387static int device_resume(struct device *dev, pm_message_t state)
392{ 388{
@@ -435,11 +431,11 @@ static int device_resume(struct device *dev, pm_message_t state)
435} 431}
436 432
437/** 433/**
438 * dpm_resume - Resume every device. 434 * dpm_resume - Execute "resume" callbacks for non-sysdev devices.
439 * @state: PM transition of the system being carried out. 435 * @state: PM transition of the system being carried out.
440 * 436 *
441 * Execute the appropriate "resume" callback for all devices the status of 437 * Execute the appropriate "resume" callback for all devices whose status
442 * which indicates that they are inactive. 438 * indicates that they are suspended.
443 */ 439 */
444static void dpm_resume(pm_message_t state) 440static void dpm_resume(pm_message_t state)
445{ 441{
@@ -476,9 +472,9 @@ static void dpm_resume(pm_message_t state)
476} 472}
477 473
478/** 474/**
479 * device_complete - Complete a PM transition for given device 475 * device_complete - Complete a PM transition for given device.
480 * @dev: Device. 476 * @dev: Device to handle.
481 * @state: PM transition of the system being carried out. 477 * @state: PM transition of the system being carried out.
482 */ 478 */
483static void device_complete(struct device *dev, pm_message_t state) 479static void device_complete(struct device *dev, pm_message_t state)
484{ 480{
@@ -503,11 +499,11 @@ static void device_complete(struct device *dev, pm_message_t state)
503} 499}
504 500
505/** 501/**
506 * dpm_complete - Complete a PM transition for all devices. 502 * dpm_complete - Complete a PM transition for all non-sysdev devices.
507 * @state: PM transition of the system being carried out. 503 * @state: PM transition of the system being carried out.
508 * 504 *
509 * Execute the ->complete() callbacks for all devices that are not marked 505 * Execute the ->complete() callbacks for all devices whose PM status is not
510 * as DPM_ON. 506 * DPM_ON (this allows new devices to be registered).
511 */ 507 */
512static void dpm_complete(pm_message_t state) 508static void dpm_complete(pm_message_t state)
513{ 509{
@@ -537,11 +533,11 @@ static void dpm_complete(pm_message_t state)
537} 533}
538 534
539/** 535/**
540 * dpm_resume_end - Restore state of each device in system. 536 * dpm_resume_end - Execute "resume" callbacks and complete system transition.
541 * @state: PM transition of the system being carried out. 537 * @state: PM transition of the system being carried out.
542 * 538 *
543 * Resume all the devices, unlock them all, and allow new 539 * Execute "resume" callbacks for all devices and complete the PM transition of
544 * devices to be registered once again. 540 * the system.
545 */ 541 */
546void dpm_resume_end(pm_message_t state) 542void dpm_resume_end(pm_message_t state)
547{ 543{
@@ -555,9 +551,11 @@ EXPORT_SYMBOL_GPL(dpm_resume_end);
555/*------------------------- Suspend routines -------------------------*/ 551/*------------------------- Suspend routines -------------------------*/
556 552
557/** 553/**
558 * resume_event - return a PM message representing the resume event 554 * resume_event - Return a "resume" message for given "suspend" sleep state.
559 * corresponding to given sleep state. 555 * @sleep_state: PM message representing a sleep state.
560 * @sleep_state: PM message representing a sleep state. 556 *
557 * Return a PM message representing the resume event corresponding to given
558 * sleep state.
561 */ 559 */
562static pm_message_t resume_event(pm_message_t sleep_state) 560static pm_message_t resume_event(pm_message_t sleep_state)
563{ 561{
@@ -574,11 +572,12 @@ static pm_message_t resume_event(pm_message_t sleep_state)
574} 572}
575 573
576/** 574/**
577 * device_suspend_noirq - Shut down one device (late suspend). 575 * device_suspend_noirq - Execute a "late suspend" callback for given device.
578 * @dev: Device. 576 * @dev: Device to handle.
579 * @state: PM transition of the system being carried out. 577 * @state: PM transition of the system being carried out.
580 * 578 *
581 * This is called with interrupts off and only a single CPU running. 579 * The driver of @dev will not receive interrupts while this function is being
580 * executed.
582 */ 581 */
583static int device_suspend_noirq(struct device *dev, pm_message_t state) 582static int device_suspend_noirq(struct device *dev, pm_message_t state)
584{ 583{
@@ -595,13 +594,11 @@ static int device_suspend_noirq(struct device *dev, pm_message_t state)
595} 594}
596 595
597/** 596/**
598 * dpm_suspend_noirq - Power down all regular (non-sysdev) devices. 597 * dpm_suspend_noirq - Execute "late suspend" callbacks for non-sysdev devices.
599 * @state: PM transition of the system being carried out. 598 * @state: PM transition of the system being carried out.
600 * 599 *
601 * Prevent device drivers from receiving interrupts and call the "noirq" 600 * Prevent device drivers from receiving interrupts and call the "noirq" suspend
602 * suspend handlers. 601 * handlers for all non-sysdev devices.
603 *
604 * Must be called under dpm_list_mtx.
605 */ 602 */
606int dpm_suspend_noirq(pm_message_t state) 603int dpm_suspend_noirq(pm_message_t state)
607{ 604{
@@ -626,9 +623,9 @@ int dpm_suspend_noirq(pm_message_t state)
626EXPORT_SYMBOL_GPL(dpm_suspend_noirq); 623EXPORT_SYMBOL_GPL(dpm_suspend_noirq);
627 624
628/** 625/**
629 * device_suspend - Save state of one device. 626 * device_suspend - Execute "suspend" callbacks for given device.
630 * @dev: Device. 627 * @dev: Device to handle.
631 * @state: PM transition of the system being carried out. 628 * @state: PM transition of the system being carried out.
632 */ 629 */
633static int device_suspend(struct device *dev, pm_message_t state) 630static int device_suspend(struct device *dev, pm_message_t state)
634{ 631{
@@ -675,10 +672,8 @@ static int device_suspend(struct device *dev, pm_message_t state)
675} 672}
676 673
677/** 674/**
678 * dpm_suspend - Suspend every device. 675 * dpm_suspend - Execute "suspend" callbacks for all non-sysdev devices.
679 * @state: PM transition of the system being carried out. 676 * @state: PM transition of the system being carried out.
680 *
681 * Execute the appropriate "suspend" callbacks for all devices.
682 */ 677 */
683static int dpm_suspend(pm_message_t state) 678static int dpm_suspend(pm_message_t state)
684{ 679{
@@ -712,9 +707,12 @@ static int dpm_suspend(pm_message_t state)
712} 707}
713 708
714/** 709/**
715 * device_prepare - Execute the ->prepare() callback(s) for given device. 710 * device_prepare - Prepare a device for system power transition.
716 * @dev: Device. 711 * @dev: Device to handle.
717 * @state: PM transition of the system being carried out. 712 * @state: PM transition of the system being carried out.
713 *
714 * Execute the ->prepare() callback(s) for given device. No new children of the
715 * device may be registered after this function has returned.
718 */ 716 */
719static int device_prepare(struct device *dev, pm_message_t state) 717static int device_prepare(struct device *dev, pm_message_t state)
720{ 718{
@@ -750,10 +748,10 @@ static int device_prepare(struct device *dev, pm_message_t state)
750} 748}
751 749
752/** 750/**
753 * dpm_prepare - Prepare all devices for a PM transition. 751 * dpm_prepare - Prepare all non-sysdev devices for a system PM transition.
754 * @state: PM transition of the system being carried out. 752 * @state: PM transition of the system being carried out.
755 * 753 *
756 * Execute the ->prepare() callback for all devices. 754 * Execute the ->prepare() callback(s) for all devices.
757 */ 755 */
758static int dpm_prepare(pm_message_t state) 756static int dpm_prepare(pm_message_t state)
759{ 757{
@@ -804,10 +802,11 @@ static int dpm_prepare(pm_message_t state)
804} 802}
805 803
806/** 804/**
807 * dpm_suspend_start - Save state and stop all devices in system. 805 * dpm_suspend_start - Prepare devices for PM transition and suspend them.
808 * @state: PM transition of the system being carried out. 806 * @state: PM transition of the system being carried out.
809 * 807 *
810 * Prepare and suspend all devices. 808 * Prepare all non-sysdev devices for system PM transition and execute "suspend"
809 * callbacks for them.
811 */ 810 */
812int dpm_suspend_start(pm_message_t state) 811int dpm_suspend_start(pm_message_t state)
813{ 812{