PM / Runtime: Use device type and device class callbacks (a6ab7aa9) · Commits · e / devices / android_kernel_fairphone_FP4

Documentation/power/runtime_pm.txt

+87 −86

Original line number	Original line	Diff line number	Diff line
	@@ -42,80 +42,81 @@ struct dev_pm_ops {
	...		...
	};		};

	The ->runtime_suspend() callback is executed by the PM core for the bus type of		The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks are
	the device being suspended. The bus type's callback is then _entirely_		executed by the PM core for either the bus type, or device type (if the bus
	_responsible_ for handling the device as appropriate, which may, but need not		type's callback is not defined), or device class (if the bus type's and device
	include executing the device driver's own ->runtime_suspend() callback (from the		type's callbacks are not defined) of given device. The bus type, device type
			and device class callbacks are referred to as subsystem-level callbacks in what
			follows.

			The subsystem-level suspend callback is _entirely_ _responsible_ for handling
			the suspend of the device as appropriate, which may, but need not include
			executing the device driver's own ->runtime_suspend() callback (from the
	PM core's point of view it is not necessary to implement a ->runtime_suspend()		PM core's point of view it is not necessary to implement a ->runtime_suspend()
	callback in a device driver as long as the bus type's ->runtime_suspend() knows		callback in a device driver as long as the subsystem-level suspend callback
	what to do to handle the device).		knows what to do to handle the device).

	* Once the bus type's ->runtime_suspend() callback has completed successfully		* Once the subsystem-level suspend callback has completed successfully
	for given device, the PM core regards the device as suspended, which need		for given device, the PM core regards the device as suspended, which need
	not mean that the device has been put into a low power state. It is		not mean that the device has been put into a low power state. It is
	supposed to mean, however, that the device will not process data and will		supposed to mean, however, that the device will not process data and will
	not communicate with the CPU(s) and RAM until its bus type's		not communicate with the CPU(s) and RAM until the subsystem-level resume
	->runtime_resume() callback is executed for it. The run-time PM status of		callback is executed for it. The run-time PM status of a device after
	a device after successful execution of its bus type's ->runtime_suspend()		successful execution of the subsystem-level suspend callback is 'suspended'.
	callback is 'suspended'.
			* If the subsystem-level suspend callback returns -EBUSY or -EAGAIN,
	* If the bus type's ->runtime_suspend() callback returns -EBUSY or -EAGAIN,		the device's run-time PM status is 'active', which means that the device
	the device's run-time PM status is supposed to be 'active', which means that		_must_ be fully operational afterwards.
	the device _must_ be fully operational afterwards.
			* If the subsystem-level suspend callback returns an error code different
	* If the bus type's ->runtime_suspend() callback returns an error code		from -EBUSY or -EAGAIN, the PM core regards this as a fatal error and will
	different from -EBUSY or -EAGAIN, the PM core regards this as a fatal		refuse to run the helper functions described in Section 4 for the device,
	error and will refuse to run the helper functions described in Section 4		until the status of it is directly set either to 'active', or to 'suspended'
	for the device, until the status of it is directly set either to 'active'		(the PM core provides special helper functions for this purpose).
	or to 'suspended' (the PM core provides special helper functions for this
	purpose).		In particular, if the driver requires remote wake-up capability (i.e. hardware
			mechanism allowing the device to request a change of its power state, such as
	In particular, if the driver requires remote wakeup capability for proper		PCI PME) for proper functioning and device_run_wake() returns 'false' for the
	functioning and device_run_wake() returns 'false' for the device, then		device, then ->runtime_suspend() should return -EBUSY. On the other hand, if
	->runtime_suspend() should return -EBUSY. On the other hand, if		device_run_wake() returns 'true' for the device and the device is put into a low
	device_run_wake() returns 'true' for the device and the device is put		power state during the execution of the subsystem-level suspend callback, it is
	into a low power state during the execution of its bus type's		expected that remote wake-up will be enabled for the device. Generally, remote
	->runtime_suspend(), it is expected that remote wake-up (i.e. hardware mechanism		wake-up should be enabled for all input devices put into a low power state at
	allowing the device to request a change of its power state, such as PCI PME)		run time.
	will be enabled for the device. Generally, remote wake-up should be enabled
	for all input devices put into a low power state at run time.		The subsystem-level resume callback is _entirely_ _responsible_ for handling the
			resume of the device as appropriate, which may, but need not include executing
	The ->runtime_resume() callback is executed by the PM core for the bus type of		the device driver's own ->runtime_resume() callback (from the PM core's point of
	the device being woken up. The bus type's callback is then _entirely_		view it is not necessary to implement a ->runtime_resume() callback in a device
	_responsible_ for handling the device as appropriate, which may, but need not		driver as long as the subsystem-level resume callback knows what to do to handle
	include executing the device driver's own ->runtime_resume() callback (from the		the device).
	PM core's point of view it is not necessary to implement a ->runtime_resume()
	callback in a device driver as long as the bus type's ->runtime_resume() knows		* Once the subsystem-level resume callback has completed successfully, the PM
	what to do to handle the device).		core regards the device as fully operational, which means that the device
			_must_ be able to complete I/O operations as needed. The run-time PM status
	* Once the bus type's ->runtime_resume() callback has completed successfully,		of the device is then 'active'.
	the PM core regards the device as fully operational, which means that the
	device _must_ be able to complete I/O operations as needed. The run-time		* If the subsystem-level resume callback returns an error code, the PM core
	PM status of the device is then 'active'.		regards this as a fatal error and will refuse to run the helper functions
			described in Section 4 for the device, until its status is directly set
	* If the bus type's ->runtime_resume() callback returns an error code, the PM		either to 'active' or to 'suspended' (the PM core provides special helper
	core regards this as a fatal error and will refuse to run the helper		functions for this purpose).
	functions described in Section 4 for the device, until its status is
	directly set either to 'active' or to 'suspended' (the PM core provides		The subsystem-level idle callback is executed by the PM core whenever the device
	special helper functions for this purpose).		appears to be idle, which is indicated to the PM core by two counters, the
			device's usage counter and the counter of 'active' children of the device.
	The ->runtime_idle() callback is executed by the PM core for the bus type of
	given device whenever the device appears to be idle, which is indicated to the
	PM core by two counters, the device's usage counter and the counter of 'active'
	children of the device.

	* If any of these counters is decreased using a helper function provided by		* If any of these counters is decreased using a helper function provided by
	the PM core and it turns out to be equal to zero, the other counter is		the PM core and it turns out to be equal to zero, the other counter is
	checked. If that counter also is equal to zero, the PM core executes the		checked. If that counter also is equal to zero, the PM core executes the
	device bus type's ->runtime_idle() callback (with the device as an		subsystem-level idle callback with the device as an argument.
	argument).

	The action performed by a bus type's ->runtime_idle() callback is totally		The action performed by a subsystem-level idle callback is totally dependent on
	dependent on the bus type in question, but the expected and recommended action		the subsystem in question, but the expected and recommended action is to check
	is to check if the device can be suspended (i.e. if all of the conditions		if the device can be suspended (i.e. if all of the conditions necessary for
	necessary for suspending the device are satisfied) and to queue up a suspend		suspending the device are satisfied) and to queue up a suspend request for the
	request for the device in that case. The value returned by this callback is		device in that case. The value returned by this callback is ignored by the PM
	ignored by the PM core.		core.

	The helper functions provided by the PM core, described in Section 4, guarantee		The helper functions provided by the PM core, described in Section 4, guarantee
	that the following constraints are met with respect to the bus type's run-time		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:
	removing the device from device hierarchy		removing the device from device hierarchy

	int pm_runtime_idle(struct device *dev);		int pm_runtime_idle(struct device *dev);
	- execute ->runtime_idle() for the device's bus type; returns 0 on success		- execute the subsystem-level idle callback for the device; returns 0 on
	or error code on failure, where -EINPROGRESS means that ->runtime_idle()		success or error code on failure, where -EINPROGRESS means that
	is already being executed		->runtime_idle() is already being executed

	int pm_runtime_suspend(struct device *dev);		int pm_runtime_suspend(struct device *dev);
	- execute ->runtime_suspend() for the device's bus type; returns 0 on		- execute the subsystem-level suspend callback for the device; returns 0 on
	success, 1 if the device's run-time PM status was already 'suspended', or		success, 1 if the device's run-time PM status was already 'suspended', or
	error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt		error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt
	to suspend the device again in future		to suspend the device again in future

	int pm_runtime_resume(struct device *dev);		int pm_runtime_resume(struct device *dev);
	- execute ->runtime_resume() for the device's bus type; returns 0 on		- execute the subsystem-leve resume callback for the device; returns 0 on
	success, 1 if the device's run-time PM status was already 'active' or		success, 1 if the device's run-time PM status was already 'active' or
	error code on failure, where -EAGAIN means it may be safe to attempt to		error code on failure, where -EAGAIN means it may be safe to attempt to
	resume the device again in future, but 'power.runtime_error' should be		resume the device again in future, but 'power.runtime_error' should be
	checked additionally		checked additionally

	int pm_request_idle(struct device *dev);		int pm_request_idle(struct device *dev);
	- submit a request to execute ->runtime_idle() for the device's bus type		- submit a request to execute the subsystem-level idle callback for the
	(the request is represented by a work item in pm_wq); returns 0 on success		device (the request is represented by a work item in pm_wq); returns 0 on
	or error code if the request has not been queued up		success or error code if the request has not been queued up

	int pm_schedule_suspend(struct device *dev, unsigned int delay);		int pm_schedule_suspend(struct device *dev, unsigned int delay);
	- schedule the execution of ->runtime_suspend() for the device's bus type		- schedule the execution of the subsystem-level suspend callback for the
	in future, where 'delay' is the time to wait before queuing up a suspend		device in future, where 'delay' is the time to wait before queuing up a
	work item in pm_wq, in milliseconds (if 'delay' is zero, the work item is		suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work
	queued up immediately); returns 0 on success, 1 if the device's PM		item is queued up immediately); returns 0 on success, 1 if the device's PM
	run-time status was already 'suspended', or error code if the request		run-time status was already 'suspended', or error code if the request
	hasn't been scheduled (or queued up if 'delay' is 0); if the execution of		hasn't been scheduled (or queued up if 'delay' is 0); if the execution of
	->runtime_suspend() is already scheduled and not yet expired, the new		->runtime_suspend() is already scheduled and not yet expired, the new
	value of 'delay' will be used as the time to wait		value of 'delay' will be used as the time to wait

	int pm_request_resume(struct device *dev);		int pm_request_resume(struct device *dev);
	- submit a request to execute ->runtime_resume() for the device's bus type		- submit a request to execute the subsystem-level resume callback for the
	(the request is represented by a work item in pm_wq); returns 0 on		device (the request is represented by a work item in pm_wq); returns 0 on
	success, 1 if the device's run-time PM status was already 'active', or		success, 1 if the device's run-time PM status was already 'active', or
	error code if the request hasn't been queued up		error code if the request hasn't been queued up

	@@ -303,12 +304,12 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
	run-time PM callbacks described in Section 2		run-time PM callbacks described in Section 2

	int pm_runtime_disable(struct device *dev);		int pm_runtime_disable(struct device *dev);
	- prevent the run-time PM helper functions from running the device bus		- prevent the run-time PM helper functions from running subsystem-level
	type's run-time PM callbacks, make sure that all of the pending run-time		run-time PM callbacks for the device, make sure that all of the pending
	PM operations on the device are either completed or canceled; returns		run-time PM operations on the device are either completed or canceled;
	1 if there was a resume request pending and it was necessary to execute		returns 1 if there was a resume request pending and it was necessary to
	->runtime_resume() for the device's bus type to satisfy that request,		execute the subsystem-level resume callback for the device to satisfy that
	otherwise 0 is returned		request, otherwise 0 is returned

	void pm_suspend_ignore_children(struct device *dev, bool enable);		void pm_suspend_ignore_children(struct device *dev, bool enable);
	- set/unset the power.ignore_children flag of the device		- 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,
	they will fail returning -EAGAIN, because the device's usage counter is		they will fail returning -EAGAIN, because the device's usage counter is
	incremented by the core before executing ->probe() and ->remove(). Still, it		incremented by the core before executing ->probe() and ->remove(). Still, it
	may be desirable to suspend the device as soon as ->probe() or ->remove() has		may be desirable to suspend the device as soon as ->probe() or ->remove() has
	finished, so the PM core uses pm_runtime_idle_sync() to invoke the device bus		finished, so the PM core uses pm_runtime_idle_sync() to invoke the
	type's ->runtime_idle() callback at that time.		subsystem-level idle callback for the device at that time.

drivers/base/power/runtime.c

+45 −0

Original line number	Original line	Diff line number	Diff line
	@@ -84,6 +84,19 @@ static int __pm_runtime_idle(struct device *dev)

	dev->bus->pm->runtime_idle(dev);		dev->bus->pm->runtime_idle(dev);

			spin_lock_irq(&dev->power.lock);
			} else if (dev->type && dev->type->pm && dev->type->pm->runtime_idle) {
			spin_unlock_irq(&dev->power.lock);

			dev->type->pm->runtime_idle(dev);

			spin_lock_irq(&dev->power.lock);
			} else if (dev->class && dev->class->pm
			&& dev->class->pm->runtime_idle) {
			spin_unlock_irq(&dev->power.lock);

			dev->class->pm->runtime_idle(dev);

	spin_lock_irq(&dev->power.lock);		spin_lock_irq(&dev->power.lock);
	}		}

	@@ -192,6 +205,22 @@ int __pm_runtime_suspend(struct device *dev, bool from_wq)

	retval = dev->bus->pm->runtime_suspend(dev);		retval = dev->bus->pm->runtime_suspend(dev);

			spin_lock_irq(&dev->power.lock);
			dev->power.runtime_error = retval;
			} else if (dev->type && dev->type->pm
			&& dev->type->pm->runtime_suspend) {
			spin_unlock_irq(&dev->power.lock);

			retval = dev->type->pm->runtime_suspend(dev);

			spin_lock_irq(&dev->power.lock);
			dev->power.runtime_error = retval;
			} else if (dev->class && dev->class->pm
			&& dev->class->pm->runtime_suspend) {
			spin_unlock_irq(&dev->power.lock);

			retval = dev->class->pm->runtime_suspend(dev);

	spin_lock_irq(&dev->power.lock);		spin_lock_irq(&dev->power.lock);
	dev->power.runtime_error = retval;		dev->power.runtime_error = retval;
	} else {		} else {
	@@ -357,6 +386,22 @@ int __pm_runtime_resume(struct device *dev, bool from_wq)

	retval = dev->bus->pm->runtime_resume(dev);		retval = dev->bus->pm->runtime_resume(dev);

			spin_lock_irq(&dev->power.lock);
			dev->power.runtime_error = retval;
			} else if (dev->type && dev->type->pm
			&& dev->type->pm->runtime_resume) {
			spin_unlock_irq(&dev->power.lock);

			retval = dev->type->pm->runtime_resume(dev);

			spin_lock_irq(&dev->power.lock);
			dev->power.runtime_error = retval;
			} else if (dev->class && dev->class->pm
			&& dev->class->pm->runtime_resume) {
			spin_unlock_irq(&dev->power.lock);

			retval = dev->class->pm->runtime_resume(dev);

	spin_lock_irq(&dev->power.lock);		spin_lock_irq(&dev->power.lock);
	dev->power.runtime_error = retval;		dev->power.runtime_error = retval;
	} else {		} else {