@@ -979,20 +979,45 @@ every time right after the runtime_resume() callback has returned
979979(alternatively, the runtime_suspend() callback will have to check if the
980980device should really be suspended and return -EAGAIN if that is not the case).
981981
982- The runtime PM of PCI devices is disabled by default. It is also blocked by
983- pci_pm_init() that runs the pm_runtime_forbid() helper function. If a PCI
984- driver implements the runtime PM callbacks and intends to use the runtime PM
985- framework provided by the PM core and the PCI subsystem, it should enable this
986- feature by executing the pm_runtime_enable() helper function. However, the
987- driver should not call the pm_runtime_allow() helper function unblocking
988- the runtime PM of the device. Instead, it should allow user space or some
989- platform-specific code to do that (user space can do it via sysfs), although
990- once it has called pm_runtime_enable(), it must be prepared to handle the
982+ The runtime PM of PCI devices is enabled by default by the PCI core. PCI
983+ device drivers do not need to enable it and should not attempt to do so.
984+ However, it is blocked by pci_pm_init() that runs the pm_runtime_forbid()
985+ helper function. In addition to that, the runtime PM usage counter of
986+ each PCI device is incremented by local_pci_probe() before executing the
987+ probe callback provided by the device's driver.
988+
989+ If a PCI driver implements the runtime PM callbacks and intends to use the
990+ runtime PM framework provided by the PM core and the PCI subsystem, it needs
991+ to decrement the device's runtime PM usage counter in its probe callback
992+ function. If it doesn't do that, the counter will always be different from
993+ zero for the device and it will never be runtime-suspended. The simplest
994+ way to do that is by calling pm_runtime_put_noidle(), but if the driver
995+ wants to schedule an autosuspend right away, for example, it may call
996+ pm_runtime_put_autosuspend() instead for this purpose. Generally, it
997+ just needs to call a function that decrements the devices usage counter
998+ from its probe routine to make runtime PM work for the device.
999+
1000+ It is important to remember that the driver's runtime_suspend() callback
1001+ may be executed right after the usage counter has been decremented, because
1002+ user space may already have cuased the pm_runtime_allow() helper function
1003+ unblocking the runtime PM of the device to run via sysfs, so the driver must
1004+ be prepared to cope with that.
1005+
1006+ The driver itself should not call pm_runtime_allow(), though. Instead, it
1007+ should let user space or some platform-specific code do that (user space can
1008+ do it via sysfs as stated above), but it must be prepared to handle the
9911009runtime PM of the device correctly as soon as pm_runtime_allow() is called
992- (which may happen at any time). [It also is possible that user space causes
993- pm_runtime_allow() to be called via sysfs before the driver is loaded, so in
994- fact the driver has to be prepared to handle the runtime PM of the device as
995- soon as it calls pm_runtime_enable().]
1010+ (which may happen at any time, even before the driver is loaded).
1011+
1012+ When the driver's remove callback runs, it has to balance the decrementation
1013+ of the device's runtime PM usage counter at the probe time. For this reason,
1014+ if it has decremented the counter in its probe callback, it must run
1015+ pm_runtime_get_noresume() in its remove callback. [Since the core carries
1016+ out a runtime resume of the device and bumps up the device's usage counter
1017+ before running the driver's remove callback, the runtime PM of the device
1018+ is effectively disabled for the duration of the remove execution and all
1019+ runtime PM helper functions incrementing the device's usage counter are
1020+ then effectively equivalent to pm_runtime_get_noresume().]
9961021
9971022The runtime PM framework works by processing requests to suspend or resume
9981023devices, or to check if they are idle (in which cases it is reasonable to
0 commit comments