Documentation/driver-api/device_link.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/device_link.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/device_link.rst
Extension
.rst
Size
16567 bytes
Lines
321
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

:c:func:`device_add()` has been called for the supplier and
:c:func:`device_initialize()` has been called for the consumer.

It is legal to add them later, but care must be taken that the system
remains in a consistent state:  E.g. a device link cannot be added in
the midst of a suspend/resume transition, so either commencement of
such a transition needs to be prevented with :c:func:`lock_system_sleep()`,
or the device link needs to be added from a function which is guaranteed
not to run in parallel to a suspend/resume transition, such as from a
device ``->probe`` callback or a boot-time PCI quirk.

Another example for an inconsistent state would be a device link that
represents a driver presence dependency, yet is added from the consumer's
``->probe`` callback while the supplier hasn't started to probe yet:  Had the
driver core known about the device link earlier, it wouldn't have probed the
consumer in the first place.  The onus is thus on the consumer to check
presence of the supplier after adding the link, and defer probing on
non-presence.  [Note that it is valid to create a link from the consumer's
``->probe`` callback while the supplier is still probing, but the consumer must
know that the supplier is functional already at the link creation time (that is
the case, for instance, if the consumer has just acquired some resources that
would not have been available had the supplier not been functional then).]

If a device link with ``DL_FLAG_STATELESS`` set (i.e. a stateless device link)
is added in the ``->probe`` callback of the supplier or consumer driver, it is
typically deleted in its ``->remove`` callback for symmetry.  That way, if the
driver is compiled as a module, the device link is added on module load and
orderly deleted on unload.  The same restrictions that apply to device link
addition (e.g. exclusion of a parallel suspend/resume transition) apply equally
to deletion.  Device links managed by the driver core are deleted automatically
by it.

Several flags may be specified on device link addition, two of which
have already been mentioned above:  ``DL_FLAG_STATELESS`` to express that no
driver presence dependency is needed (but only correct suspend/resume and
shutdown ordering) and ``DL_FLAG_PM_RUNTIME`` to express that runtime PM
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 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
purged when the supplier fails to probe or later unbinds.

If neither ``DL_FLAG_AUTOREMOVE_CONSUMER`` nor ``DL_FLAG_AUTOREMOVE_SUPPLIER``
is set, ``DL_FLAG_AUTOPROBE_CONSUMER`` can be used to request the driver core
to probe for a driver for the consumer driver on the link automatically after
a driver has been bound to the supplier device.

Note, however, that any combinations of ``DL_FLAG_AUTOREMOVE_CONSUMER``,
``DL_FLAG_AUTOREMOVE_SUPPLIER`` or ``DL_FLAG_AUTOPROBE_CONSUMER`` with
``DL_FLAG_STATELESS`` are invalid and cannot be used.

Limitations
===========

Driver authors should be aware that a driver presence dependency for managed
device links (i.e. when ``DL_FLAG_STATELESS`` is not specified on link addition)
may cause probing of the consumer to be deferred indefinitely.  This can become
a problem if the consumer is required to probe before a certain initcall level
is reached.  Worse, if the supplier driver is blacklisted or missing, the
consumer will never be probed.

Moreover, managed device links cannot be deleted directly.  They are deleted
by the driver core when they are not necessary any more in accordance with the

Annotation

Implementation Notes