Commit 20d652d7 authored by Rafael J. Wysocki's avatar Rafael J. Wysocki

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: default avatarRafael J. Wysocki <rjw@sisk.pl>
Acked-by: default avatarRandy Dunlap <randy.dunlap@oracle.com>
Acked-by: default avatarGreg Kroah-Hartman <gregkh@suse.de>
Acked-by: default avatarAlan Stern <stern@rowland.harvard.edu>
parent 9d62ec6c
...@@ -50,7 +50,7 @@ static DEFINE_MUTEX(dpm_list_mtx); ...@@ -50,7 +50,7 @@ static DEFINE_MUTEX(dpm_list_mtx);
static bool transition_started; static bool transition_started;
/** /**
* device_pm_init - Initialize the PM-related part of a device object * device_pm_init - Initialize the PM-related part of a device object.
* @dev: Device object being initialized. * @dev: Device object being initialized.
*/ */
void device_pm_init(struct device *dev) void device_pm_init(struct device *dev)
...@@ -60,7 +60,7 @@ void device_pm_init(struct device *dev) ...@@ -60,7 +60,7 @@ void device_pm_init(struct device *dev)
} }
/** /**
* device_pm_lock - lock the list of active devices used by the PM core * device_pm_lock - Lock the list of active devices used by the PM core.
*/ */
void device_pm_lock(void) void device_pm_lock(void)
{ {
...@@ -68,7 +68,7 @@ void device_pm_lock(void) ...@@ -68,7 +68,7 @@ void device_pm_lock(void)
} }
/** /**
* device_pm_unlock - unlock the list of active devices used by the PM core * device_pm_unlock - Unlock the list of active devices used by the PM core.
*/ */
void device_pm_unlock(void) void device_pm_unlock(void)
{ {
...@@ -76,8 +76,8 @@ void device_pm_unlock(void) ...@@ -76,8 +76,8 @@ void device_pm_unlock(void)
} }
/** /**
* device_pm_add - add a device to the list of active devices * device_pm_add - Add a device to the PM core's list of active devices.
* @dev: Device to be added to the list * @dev: Device to add to the list.
*/ */
void device_pm_add(struct device *dev) void device_pm_add(struct device *dev)
{ {
...@@ -103,10 +103,8 @@ void device_pm_add(struct device *dev) ...@@ -103,10 +103,8 @@ void device_pm_add(struct device *dev)
} }
/** /**
* device_pm_remove - remove a device from the list of active devices * device_pm_remove - Remove a device from the PM core's list of active devices.
* @dev: Device to be removed from the list * @dev: Device to be removed from the list.
*
* This function also removes the device's PM-related sysfs attributes.
*/ */
void device_pm_remove(struct device *dev) void device_pm_remove(struct device *dev)
{ {
...@@ -120,9 +118,9 @@ void device_pm_remove(struct device *dev) ...@@ -120,9 +118,9 @@ void device_pm_remove(struct device *dev)
} }
/** /**
* device_pm_move_before - move device in dpm_list * device_pm_move_before - Move device in the PM core's list of active devices.
* @deva: Device to move in dpm_list * @deva: Device to move in dpm_list.
* @devb: Device @deva should come before * @devb: Device @deva should come before.
*/ */
void device_pm_move_before(struct device *deva, struct device *devb) void device_pm_move_before(struct device *deva, struct device *devb)
{ {
...@@ -136,9 +134,9 @@ void device_pm_move_before(struct device *deva, struct device *devb) ...@@ -136,9 +134,9 @@ void device_pm_move_before(struct device *deva, struct device *devb)
} }
/** /**
* device_pm_move_after - move device in dpm_list * device_pm_move_after - Move device in the PM core's list of active devices.
* @deva: Device to move in dpm_list * @deva: Device to move in dpm_list.
* @devb: Device @deva should come after * @devb: Device @deva should come after.
*/ */
void device_pm_move_after(struct device *deva, struct device *devb) void device_pm_move_after(struct device *deva, struct device *devb)
{ {
...@@ -152,8 +150,8 @@ void device_pm_move_after(struct device *deva, struct device *devb) ...@@ -152,8 +150,8 @@ void device_pm_move_after(struct device *deva, struct device *devb)
} }
/** /**
* device_pm_move_last - move device to end of dpm_list * device_pm_move_last - Move device to end of the PM core's list of devices.
* @dev: Device to move in dpm_list * @dev: Device to move in dpm_list.
*/ */
void device_pm_move_last(struct device *dev) void device_pm_move_last(struct device *dev)
{ {
...@@ -164,10 +162,10 @@ void device_pm_move_last(struct device *dev) ...@@ -164,10 +162,10 @@ void device_pm_move_last(struct device *dev)
} }
/** /**
* pm_op - execute the PM operation appropiate for given PM event * pm_op - Execute the PM operation appropriate for given PM event.
* @dev: Device. * @dev: Device to handle.
* @ops: PM operations to choose from. * @ops: PM operations to choose from.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
*/ */
static int pm_op(struct device *dev, static int pm_op(struct device *dev,
const struct dev_pm_ops *ops, const struct dev_pm_ops *ops,
...@@ -225,13 +223,13 @@ static int pm_op(struct device *dev, ...@@ -225,13 +223,13 @@ static int pm_op(struct device *dev,
} }
/** /**
* pm_noirq_op - execute the PM operation appropiate for given PM event * pm_noirq_op - Execute the PM operation appropriate for given PM event.
* @dev: Device. * @dev: Device to handle.
* @ops: PM operations to choose from. * @ops: PM operations to choose from.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
* *
* The operation is executed with interrupts disabled by the only remaining * The driver of @dev will not receive interrupts while this function is being
* functional CPU in the system. * executed.
*/ */
static int pm_noirq_op(struct device *dev, static int pm_noirq_op(struct device *dev,
const struct dev_pm_ops *ops, 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,11 +327,12 @@ static void pm_dev_err(struct device *dev, pm_message_t state, char *info,
/*------------------------- Resume routines -------------------------*/ /*------------------------- Resume routines -------------------------*/
/** /**
* device_resume_noirq - Power on one device (early resume). * device_resume_noirq - Execute an "early resume" callback for given device.
* @dev: Device. * @dev: Device to handle.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
* *
* Must be called with interrupts disabled. * The driver of @dev will not receive interrupts while this function is being
* executed.
*/ */
static int device_resume_noirq(struct device *dev, pm_message_t state) static int device_resume_noirq(struct device *dev, pm_message_t state)
{ {
...@@ -355,14 +354,11 @@ static int device_resume_noirq(struct device *dev, pm_message_t state) ...@@ -355,14 +354,11 @@ static int device_resume_noirq(struct device *dev, pm_message_t state)
} }
/** /**
* dpm_resume_noirq - Power on all regular (non-sysdev) devices. * dpm_resume_noirq - Execute "early resume" callbacks for non-sysdev devices.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
*
* Call the "noirq" resume handlers for all devices marked as
* DPM_OFF_IRQ and enable device drivers to receive interrupts.
* *
* Must be called under dpm_list_mtx. Device drivers should not receive * Call the "noirq" resume handlers for all devices marked as DPM_OFF_IRQ and
* interrupts while it's being executed. * enable device drivers to receive interrupts.
*/ */
void dpm_resume_noirq(pm_message_t state) void dpm_resume_noirq(pm_message_t state)
{ {
...@@ -384,9 +380,9 @@ void dpm_resume_noirq(pm_message_t state) ...@@ -384,9 +380,9 @@ void dpm_resume_noirq(pm_message_t state)
EXPORT_SYMBOL_GPL(dpm_resume_noirq); EXPORT_SYMBOL_GPL(dpm_resume_noirq);
/** /**
* device_resume - Restore state for one device. * device_resume - Execute "resume" callbacks for given device.
* @dev: Device. * @dev: Device to handle.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
*/ */
static int device_resume(struct device *dev, pm_message_t state) static int device_resume(struct device *dev, pm_message_t state)
{ {
...@@ -435,11 +431,11 @@ static int device_resume(struct device *dev, pm_message_t state) ...@@ -435,11 +431,11 @@ static int device_resume(struct device *dev, pm_message_t state)
} }
/** /**
* dpm_resume - Resume every device. * dpm_resume - Execute "resume" callbacks for non-sysdev devices.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
* *
* Execute the appropriate "resume" callback for all devices the status of * Execute the appropriate "resume" callback for all devices whose status
* which indicates that they are inactive. * indicates that they are suspended.
*/ */
static void dpm_resume(pm_message_t state) static void dpm_resume(pm_message_t state)
{ {
...@@ -476,9 +472,9 @@ static void dpm_resume(pm_message_t state) ...@@ -476,9 +472,9 @@ static void dpm_resume(pm_message_t state)
} }
/** /**
* device_complete - Complete a PM transition for given device * device_complete - Complete a PM transition for given device.
* @dev: Device. * @dev: Device to handle.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
*/ */
static void device_complete(struct device *dev, pm_message_t state) static void device_complete(struct device *dev, pm_message_t state)
{ {
...@@ -503,11 +499,11 @@ static void device_complete(struct device *dev, pm_message_t state) ...@@ -503,11 +499,11 @@ static void device_complete(struct device *dev, pm_message_t state)
} }
/** /**
* dpm_complete - Complete a PM transition for all devices. * dpm_complete - Complete a PM transition for all non-sysdev devices.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
* *
* Execute the ->complete() callbacks for all devices that are not marked * Execute the ->complete() callbacks for all devices whose PM status is not
* as DPM_ON. * DPM_ON (this allows new devices to be registered).
*/ */
static void dpm_complete(pm_message_t state) static void dpm_complete(pm_message_t state)
{ {
...@@ -537,11 +533,11 @@ static void dpm_complete(pm_message_t state) ...@@ -537,11 +533,11 @@ static void dpm_complete(pm_message_t state)
} }
/** /**
* dpm_resume_end - Restore state of each device in system. * dpm_resume_end - Execute "resume" callbacks and complete system transition.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
* *
* Resume all the devices, unlock them all, and allow new * Execute "resume" callbacks for all devices and complete the PM transition of
* devices to be registered once again. * the system.
*/ */
void dpm_resume_end(pm_message_t state) void dpm_resume_end(pm_message_t state)
{ {
...@@ -555,9 +551,11 @@ EXPORT_SYMBOL_GPL(dpm_resume_end); ...@@ -555,9 +551,11 @@ EXPORT_SYMBOL_GPL(dpm_resume_end);
/*------------------------- Suspend routines -------------------------*/ /*------------------------- Suspend routines -------------------------*/
/** /**
* resume_event - return a PM message representing the resume event * resume_event - Return a "resume" message for given "suspend" sleep state.
* corresponding to given sleep state. * @sleep_state: PM message representing a sleep state.
* @sleep_state: PM message representing a sleep state. *
* Return a PM message representing the resume event corresponding to given
* sleep state.
*/ */
static pm_message_t resume_event(pm_message_t sleep_state) static pm_message_t resume_event(pm_message_t sleep_state)
{ {
...@@ -574,11 +572,12 @@ static pm_message_t resume_event(pm_message_t sleep_state) ...@@ -574,11 +572,12 @@ static pm_message_t resume_event(pm_message_t sleep_state)
} }
/** /**
* device_suspend_noirq - Shut down one device (late suspend). * device_suspend_noirq - Execute a "late suspend" callback for given device.
* @dev: Device. * @dev: Device to handle.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
* *
* This is called with interrupts off and only a single CPU running. * The driver of @dev will not receive interrupts while this function is being
* executed.
*/ */
static int device_suspend_noirq(struct device *dev, pm_message_t state) static int device_suspend_noirq(struct device *dev, pm_message_t state)
{ {
...@@ -595,13 +594,11 @@ static int device_suspend_noirq(struct device *dev, pm_message_t state) ...@@ -595,13 +594,11 @@ static int device_suspend_noirq(struct device *dev, pm_message_t state)
} }
/** /**
* dpm_suspend_noirq - Power down all regular (non-sysdev) devices. * dpm_suspend_noirq - Execute "late suspend" callbacks for non-sysdev devices.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
* *
* Prevent device drivers from receiving interrupts and call the "noirq" * Prevent device drivers from receiving interrupts and call the "noirq" suspend
* suspend handlers. * handlers for all non-sysdev devices.
*
* Must be called under dpm_list_mtx.
*/ */
int dpm_suspend_noirq(pm_message_t state) int dpm_suspend_noirq(pm_message_t state)
{ {
...@@ -626,9 +623,9 @@ int dpm_suspend_noirq(pm_message_t state) ...@@ -626,9 +623,9 @@ int dpm_suspend_noirq(pm_message_t state)
EXPORT_SYMBOL_GPL(dpm_suspend_noirq); EXPORT_SYMBOL_GPL(dpm_suspend_noirq);
/** /**
* device_suspend - Save state of one device. * device_suspend - Execute "suspend" callbacks for given device.
* @dev: Device. * @dev: Device to handle.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
*/ */
static int device_suspend(struct device *dev, pm_message_t state) static int device_suspend(struct device *dev, pm_message_t state)
{ {
...@@ -675,10 +672,8 @@ static int device_suspend(struct device *dev, pm_message_t state) ...@@ -675,10 +672,8 @@ static int device_suspend(struct device *dev, pm_message_t state)
} }
/** /**
* dpm_suspend - Suspend every device. * dpm_suspend - Execute "suspend" callbacks for all non-sysdev devices.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
*
* Execute the appropriate "suspend" callbacks for all devices.
*/ */
static int dpm_suspend(pm_message_t state) static int dpm_suspend(pm_message_t state)
{ {
...@@ -712,9 +707,12 @@ static int dpm_suspend(pm_message_t state) ...@@ -712,9 +707,12 @@ static int dpm_suspend(pm_message_t state)
} }
/** /**
* device_prepare - Execute the ->prepare() callback(s) for given device. * device_prepare - Prepare a device for system power transition.
* @dev: Device. * @dev: Device to handle.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
*
* Execute the ->prepare() callback(s) for given device. No new children of the
* device may be registered after this function has returned.
*/ */
static int device_prepare(struct device *dev, pm_message_t state) static int device_prepare(struct device *dev, pm_message_t state)
{ {
...@@ -750,10 +748,10 @@ static int device_prepare(struct device *dev, pm_message_t state) ...@@ -750,10 +748,10 @@ static int device_prepare(struct device *dev, pm_message_t state)
} }
/** /**
* dpm_prepare - Prepare all devices for a PM transition. * dpm_prepare - Prepare all non-sysdev devices for a system PM transition.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
* *
* Execute the ->prepare() callback for all devices. * Execute the ->prepare() callback(s) for all devices.
*/ */
static int dpm_prepare(pm_message_t state) static int dpm_prepare(pm_message_t state)
{ {
...@@ -804,10 +802,11 @@ static int dpm_prepare(pm_message_t state) ...@@ -804,10 +802,11 @@ static int dpm_prepare(pm_message_t state)
} }
/** /**
* dpm_suspend_start - Save state and stop all devices in system. * dpm_suspend_start - Prepare devices for PM transition and suspend them.
* @state: PM transition of the system being carried out. * @state: PM transition of the system being carried out.
* *
* Prepare and suspend all devices. * Prepare all non-sysdev devices for system PM transition and execute "suspend"
* callbacks for them.
*/ */
int dpm_suspend_start(pm_message_t state) int dpm_suspend_start(pm_message_t state)
{ {
......
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