driver core: Document limitation related to DL_FLAG_RPM_ACTIVE

If device_link_add() is called twice in a row to create a stateless
device link for the same consumer-supplier pair without an attempt
to delete the link between these calls, and the second caller passes
DL_FLAG_RPM_ACTIVE to it in flags, calling either device_link_del()
or device_link_remove() immediately after that will leave the link's
supplier device with nonzero PM-runtime usage counter, which may
prevent the supplier from being runtime-suspended going forward
until the link is deleted by another invocation of device_link_del()
or device_link_remove() for it.

Even though this is confusing and may lead to subtle issues, trying
to avoid it in the framework also may cause problems to appear, so
document it as a known limitation.

Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Rafael J. Wysocki 2019-02-07 19:41:56 +01:00 committed by Greg Kroah-Hartman
parent 4080ab0830
commit 70fb9a2523
1 changed files with 18 additions and 3 deletions

View File

@ -86,9 +86,10 @@ integration is desired.
Two other flags are specifically targeted at use cases where the device
link is added from the consumer's ``->probe`` callback: ``DL_FLAG_RPM_ACTIVE``
can be specified to runtime resume the supplier upon addition of the
device link. ``DL_FLAG_AUTOREMOVE_CONSUMER`` causes the device link to be
automatically purged when the consumer fails to probe or later unbinds.
can be specified to runtime resume the supplier and prevent it from suspending
before the consumer is runtime suspended. ``DL_FLAG_AUTOREMOVE_CONSUMER``
causes the device link to be automatically purged when the consumer fails to
probe or later unbinds.
Similarly, when the device link is added from supplier's ``->probe`` callback,
``DL_FLAG_AUTOREMOVE_SUPPLIER`` causes the device link to be automatically
@ -121,6 +122,20 @@ set) are expected to be removed by whoever called :c:func:`device_link_add()`
to add them with the help of either :c:func:`device_link_del()` or
:c:func:`device_link_remove()`.
Passing ``DL_FLAG_RPM_ACTIVE`` along with ``DL_FLAG_STATELESS`` to
:c:func:`device_link_add()` may cause the PM-runtime usage counter of the
supplier device to remain nonzero after a subsequent invocation of either
:c:func:`device_link_del()` or :c:func:`device_link_remove()` to remove the
device link returned by it. This happens if :c:func:`device_link_add()` is
called twice in a row for the same consumer-supplier pair without removing the
link between these calls, in which case allowing the PM-runtime usage counter
of the supplier to drop on an attempt to remove the link may cause it to be
suspended while the consumer is still PM-runtime-active and that has to be
avoided. [To work around this limitation it is sufficient to let the consumer
runtime suspend at least once, or call :c:func:`pm_runtime_set_suspended()` for
it with PM-runtime disabled, between the :c:func:`device_link_add()` and
:c:func:`device_link_del()` or :c:func:`device_link_remove()` calls.]
Sometimes drivers depend on optional resources. They are able to operate
in a degraded mode (reduced feature set or performance) when those resources
are not present. An example is an SPI controller that can use a DMA engine