USB: use the runtime-PM autosuspend implementation

		 Alan Stern <stern@rowland.harvard.edu>

			    December 11, 2009

			    October 28, 2010

The user interface for controlling dynamic PM is located in the power/

subdirectory of each USB device's sysfs directory, that is, in

/sys/bus/usb/devices/.../power/ where "..." is the device's ID.  The

relevant attribute files are: wakeup, control, and autosuspend.

(There may also be a file named "level"; this file was deprecated

as of the 2.6.35 kernel and replaced by the "control" file.)

relevant attribute files are: wakeup, control, and

autosuspend_delay_ms.  (There may also be a file named "level"; this

file was deprecated as of the 2.6.35 kernel and replaced by the

"control" file.  In 2.6.38 the "autosuspend" file will be deprecated

and replaced by the "autosuspend_delay_ms" file.  The only difference

is that the newer file expresses the delay in milliseconds whereas the

older file uses seconds.  Confusingly, both files are present in 2.6.37

but only "autosuspend" works.)

	power/wakeup

		suspended and autoresume was not allowed.  This

		setting is no longer supported.)

	power/autosuspend

	power/autosuspend_delay_ms

		This file contains an integer value, which is the

		number of seconds the device should remain idle before

		the kernel will autosuspend it (the idle-delay time).

		The default is 2.  0 means to autosuspend as soon as

		the device becomes idle, and negative values mean

		never to autosuspend.  You can write a number to the

		file to change the autosuspend idle-delay time.

Writing "-1" to power/autosuspend and writing "on" to power/control do

essentially the same thing -- they both prevent the device from being

autosuspended.  Yes, this is a redundancy in the API.

		number of milliseconds the device should remain idle

		before the kernel will autosuspend it (the idle-delay

		time).  The default is 2000.  0 means to autosuspend

		as soon as the device becomes idle, and negative

		values mean never to autosuspend.  You can write a

		number to the file to change the autosuspend

		idle-delay time.

Writing "-1" to power/autosuspend_delay_ms and writing "on" to

power/control do essentially the same thing -- they both prevent the

device from being autosuspended.  Yes, this is a redundancy in the

API.

(In 2.6.21 writing "0" to power/autosuspend would prevent the device

from being autosuspended; the behavior was changed in 2.6.22.  The

power/autosuspend attribute did not exist prior to 2.6.21, and the

power/level attribute did not exist prior to 2.6.22.  power/control

was added in 2.6.34.)

was added in 2.6.34, and power/autosuspend_delay_ms was added in

2.6.37 but did not become functional until 2.6.38.)

	Changing the default idle-delay time

	------------------------------------

The default autosuspend idle-delay time is controlled by a module

parameter in usbcore.  You can specify the value when usbcore is

loaded.  For example, to set it to 5 seconds instead of 2 you would

The default autosuspend idle-delay time (in seconds) is controlled by

a module parameter in usbcore.  You can specify the value when usbcore

is loaded.  For example, to set it to 5 seconds instead of 2 you would

do:

	modprobe usbcore autosuspend=5

If a driver knows that its device has proper suspend/resume support,

it can enable autosuspend all by itself.  For example, the video

driver for a laptop's webcam might do this, since these devices are

rarely used and so should normally be autosuspended.

driver for a laptop's webcam might do this (in recent kernels they

do), since these devices are rarely used and so should normally be

autosuspended.

Sometimes it turns out that even when a device does work okay with

autosuspend there are still problems.  For example, there are

experimental patches adding autosuspend support to the usbhid driver,

which manages keyboards and mice, among other things.  Tests with a

number of keyboards showed that typing on a suspended keyboard, while

causing the keyboard to do a remote wakeup all right, would

nonetheless frequently result in lost keystrokes.  Tests with mice

showed that some of them would issue a remote-wakeup request in

response to button presses but not to motion, and some in response to

neither.

autosuspend there are still problems.  For example, the usbhid driver,

which manages keyboards and mice, has autosuspend support.  Tests with

a number of keyboards show that typing on a suspended keyboard, while

causing the keyboard to do a remote wakeup all right, will nonetheless

frequently result in lost keystrokes.  Tests with mice show that some

of them will issue a remote-wakeup request in response to button

presses but not to motion, and some in response to neither.

The kernel will not prevent you from enabling autosuspend on devices

that can't handle it.  It is even possible in theory to damage a

device by suspending it at the wrong time -- for example, suspending a

USB hard disk might cause it to spin down without parking the heads.

(Highly unlikely, but possible.)  Take care.

device by suspending it at the wrong time.  (Highly unlikely, but

possible.)  Take care.

	The driver interface for Power Management

then the interface is considered to be idle, and the kernel may

autosuspend the device.

(There is a similar usage counter field in struct usb_device,

associated with the device itself rather than any of its interfaces.

This counter is used only by the USB core.)

Drivers need not be concerned about balancing changes to the usage

counter; the USB core will undo any remaining "get"s when a driver

is unbound from its interface.  As a corollary, drivers must not call

autosuspending a keyboard if the user can't cause the keyboard to do a

remote wakeup by typing on it.  If the driver sets

intf->needs_remote_wakeup to 1, the kernel won't autosuspend the

device if remote wakeup isn't available or has been disabled through

the power/wakeup attribute.  (If the device is already autosuspended,

though, setting this flag won't cause the kernel to autoresume it.

Normally a driver would set this flag in its probe method, at which

time the device is guaranteed not to be autosuspended.)

device if remote wakeup isn't available.  (If the device is already

autosuspended, though, setting this flag won't cause the kernel to

autoresume it.  Normally a driver would set this flag in its probe

method, at which time the device is guaranteed not to be

autosuspended.)

If a driver does its I/O asynchronously in interrupt context, it

should call usb_autopm_get_interface_async() before starting output and

	usb_mark_last_busy(struct usb_device *udev);

in the event handler.  This sets udev->last_busy to the current time.

udev->last_busy is the field used for idle-delay calculations;

updating it will cause any pending autosuspend to be moved back.  Most

of the usb_autopm_* routines will also set the last_busy field to the

current time.

in the event handler.  This tells the PM core that the device was just

busy and therefore the next autosuspend idle-delay expiration should

be pushed back.  Many of the usb_autopm_* routines also make this call,

so drivers need to worry only when interrupt-driven input arrives.

Asynchronous operation is always subject to races.  For example, a

driver may call one of the usb_autopm_*_interface_async() routines at

a time when the core has just finished deciding the device has been

idle for long enough but not yet gotten around to calling the driver's

suspend method.  The suspend method must be responsible for

synchronizing with the output request routine and the URB completion

handler; it should cause autosuspends to fail with -EBUSY if the

driver needs to use the device.

driver may call the usb_autopm_get_interface_async() routine at a time

when the core has just finished deciding the device has been idle for

long enough but not yet gotten around to calling the driver's suspend

method.  The suspend method must be responsible for synchronizing with

the I/O request routine and the URB completion handler; it should

cause autosuspends to fail with -EBUSY if the driver needs to use the

device.

External suspend calls should never be allowed to fail in this way,

only autosuspend calls.  The driver can tell them apart by checking

occurs.  Since system suspends are supposed to be as transparent as

possible, the device should remain suspended following the system

resume.  But this theory may not work out well in practice; over time

the kernel's behavior in this regard has changed.

the kernel's behavior in this regard has changed.  As of 2.6.37 the

policy is to resume all devices during a system resume and let them

handle their own runtime suspends afterward.

Secondly, a dynamic power-management event may occur as a system

suspend is underway.  The window for this is short, since system

	int	status;

	usb_mark_last_busy(udev);

	status = pm_runtime_put_sync(&udev->dev);

	dev_vdbg(&udev->dev, "%s: cnt %d -> %d\n",

			__func__, atomic_read(&udev->dev.power.usage_count),

			status);

}

/**

 * usb_try_autosuspend_device - attempt an autosuspend of a USB device and its interfaces

 * @udev: the usb_device to autosuspend

 *

 * This routine should be called when a core subsystem thinks @udev may

 * be ready to autosuspend.

 *

 * @udev's usage counter left unchanged.  If it is 0 and all the interfaces

 * are inactive then an autosuspend will be attempted.  The attempt may

 * fail or be delayed.

 *

 * The caller must hold @udev's device lock.

 *

 * This routine can run only in process context.

 */

void usb_try_autosuspend_device(struct usb_device *udev)

{

	int	status;

	status = pm_runtime_idle(&udev->dev);

	status = pm_runtime_put_sync_autosuspend(&udev->dev);

	dev_vdbg(&udev->dev, "%s: cnt %d -> %d\n",

			__func__, atomic_read(&udev->dev.power.usage_count),

			status);

void usb_autopm_put_interface_async(struct usb_interface *intf)

{

	struct usb_device	*udev = interface_to_usbdev(intf);

	unsigned long		last_busy;

	int			status = 0;

	int			status;

	last_busy = udev->dev.power.last_busy;

	usb_mark_last_busy(udev);

	atomic_dec(&intf->pm_usage_cnt);

	pm_runtime_put_noidle(&intf->dev);

	if (udev->dev.power.runtime_auto) {

		/* Optimization: Don't schedule a delayed autosuspend if

		 * the timer is already running and the expiration time

		 * wouldn't change.

		 *

		 * We have to use the interface's timer.  Attempts to

		 * schedule a suspend for the device would fail because

		 * the interface is still active.

		 */

		if (intf->dev.power.timer_expires == 0 ||

				round_jiffies_up(last_busy) !=

				round_jiffies_up(jiffies)) {

			status = pm_schedule_suspend(&intf->dev,

					jiffies_to_msecs(

					round_jiffies_up_relative(

						udev->autosuspend_delay)));

		}

	}

	status = pm_runtime_put(&intf->dev);

	dev_vdbg(&intf->dev, "%s: cnt %d -> %d\n",

			__func__, atomic_read(&intf->dev.power.usage_count),

			status);

{

	int			w, i;

	struct usb_interface	*intf;

	unsigned long		suspend_time, j;

	/* Fail if autosuspend is disabled, or any interfaces are in use, or

	 * any interface drivers require remote wakeup but it isn't available.

		return -EOPNOTSUPP;

	}

	udev->do_remote_wakeup = w;

	/* If everything is okay but the device hasn't been idle for long

	 * enough, queue a delayed autosuspend request.

	 */

	j = ACCESS_ONCE(jiffies);

	suspend_time = udev->dev.power.last_busy + udev->autosuspend_delay;

	if (time_before(j, suspend_time)) {

		pm_schedule_suspend(&udev->dev, jiffies_to_msecs(

				round_jiffies_up_relative(suspend_time - j)));

		return -EAGAIN;

	}

	return 0;

}

	status = usb_suspend_both(udev, PMSG_AUTO_SUSPEND);

	/* If an interface fails the suspend, adjust the last_busy

	 * time so that we don't get another suspend attempt right

	 * away.

	 */

	if (status) {

		udev->dev.power.last_busy = jiffies +

				(udev->autosuspend_delay == 0 ? HZ/2 : 0);

	}

	/* Prevent the parent from suspending immediately after */

	else if (udev->parent)

	if (status == 0 && udev->parent)

		usb_mark_last_busy(udev->parent);

	return status;

	 * autosuspend checks.

	 */

	if (autosuspend_check(udev) == 0)

		pm_runtime_suspend(dev);

		pm_runtime_autosuspend(dev);

	return 0;

}

	/* Tell the runtime-PM framework the device is active */

	pm_runtime_set_active(&udev->dev);

	pm_runtime_use_autosuspend(&udev->dev);

	pm_runtime_enable(&udev->dev);

	err = usb_enumerate_device(udev);	/* Read descriptors */

	 */

	usb_disable_autosuspend(udev);

	/* Autosuspend can also be disabled if the initial autosuspend_delay

	 * is negative.

	 */

	if (udev->autosuspend_delay < 0)

		usb_autoresume_device(udev);

#endif

	/* For the present, all devices default to USB-PERSIST enabled */

static ssize_t

show_autosuspend(struct device *dev, struct device_attribute *attr, char *buf)

{

	struct usb_device *udev = to_usb_device(dev);

	return sprintf(buf, "%d\n", udev->autosuspend_delay / HZ);

	return sprintf(buf, "%d\n", dev->power.autosuspend_delay / 1000);

}

static ssize_t

set_autosuspend(struct device *dev, struct device_attribute *attr,

		const char *buf, size_t count)

{

	struct usb_device *udev = to_usb_device(dev);

	int value, old_delay;

	int rc;

	int value;

	if (sscanf(buf, "%d", &value) != 1 || value >= INT_MAX/HZ ||

			value <= - INT_MAX/HZ)

	if (sscanf(buf, "%d", &value) != 1 || value >= INT_MAX/1000 ||

			value <= -INT_MAX/1000)

		return -EINVAL;

	value *= HZ;

	usb_lock_device(udev);

	old_delay = udev->autosuspend_delay;

	udev->autosuspend_delay = value;

	if (old_delay < 0) {	/* Autosuspend wasn't allowed */

		if (value >= 0)

			usb_autosuspend_device(udev);

	} else {		/* Autosuspend was allowed */

		if (value < 0) {

			rc = usb_autoresume_device(udev);

			if (rc < 0) {

				count = rc;

				udev->autosuspend_delay = old_delay;

			}

		} else {

			usb_try_autosuspend_device(udev);

		}

	}

	usb_unlock_device(udev);

	pm_runtime_set_autosuspend_delay(dev, value * 1000);

	return count;

}