Documentation/driver-api/device_link.rst

4 Device links
8 that are borne out of a parent/child relationship within the device
10 are ordered based on this relationship, i.e. children are always suspended
13 Sometimes there is a need to represent device dependencies beyond the
18 dependencies, i.e. that one device must be bound to a driver before
21 Often these two dependency types come together, so a device depends on
25 Device links allow representation of such dependencies in the driver core.
27 In its standard or *managed* form, a device link combines *both* dependency
29 "supplier" device and its "consumer" devices, and it guarantees driver
30 presence on the supplier.  The consumer devices are not probed before the
34 When driver presence on the supplier is irrelevant and only correct
35 suspend/resume and shutdown ordering is needed, the device link may
37 enforcing driver presence on the supplier is optional.
40 ``DL_FLAG_PM_RUNTIME`` flag on addition of the device link, the PM core
47 The earliest point in time when device links can be added is after
52 remains in a consistent state:  E.g. a device link cannot be added in
55 or the device link needs to be added from a function which is guaranteed
57 device ``->probe`` callback or a boot-time PCI quirk.
59 Another example for an inconsistent state would be a device link that
61 ``->probe`` callback while the supplier hasn't started to probe yet:  Had the
62 driver core known about the device link earlier, it wouldn't have probed the
63 consumer in the first place.  The onus is thus on the consumer to check
64 presence of the supplier after adding the link, and defer probing on
65 non-presence.  [Note that it is valid to create a link from the consumer's
66 ``->probe`` callback while the supplier is still probing, but the consumer must
71 If a device link with ``DL_FLAG_STATELESS`` set (i.e. a stateless device link)
72 is added in the ``->probe`` callback of the supplier or consumer driver, it is
73 typically deleted in its ``->remove`` callback for symmetry.  That way, if the
74 driver is compiled as a module, the device link is added on module load and
75 orderly deleted on unload.  The same restrictions that apply to device link
77 to deletion.  Device links managed by the driver core are deleted automatically
80 Several flags may be specified on device link addition, two of which
86 Two other flags are specifically targeted at use cases where the device
87 link is added from the consumer's ``->probe`` callback:  ``DL_FLAG_RPM_ACTIVE``
90 causes the device link to be automatically purged when the consumer fails to
93 Similarly, when the device link is added from supplier's ``->probe`` callback,
94 ``DL_FLAG_AUTOREMOVE_SUPPLIER`` causes the device link to be automatically
99 to probe for a driver for the consumer driver on the link automatically after
100 a driver has been bound to the supplier device.
110 device links (i.e. when ``DL_FLAG_STATELESS`` is not specified on link addition)
116 Moreover, managed device links cannot be deleted directly.  They are deleted
119 However, stateless device links (i.e. device links with ``DL_FLAG_STATELESS``
125 :c:func:`device_link_add()` may cause the PM-runtime usage counter of the
126 supplier device to remain nonzero after a subsequent invocation of either
128 device link returned by it.  This happens if :c:func:`device_link_add()` is
129 called twice in a row for the same consumer-supplier pair without removing the
130 link between these calls, in which case allowing the PM-runtime usage counter
131 of the supplier to drop on an attempt to remove the link may cause it to be
132 suspended while the consumer is still PM-runtime-active and that has to be
135 it with PM-runtime disabled, between the :c:func:`device_link_add()` and
138 Sometimes drivers depend on optional resources.  They are able to operate
142 resources at probe time but on non-presence there is no way to know whether
147 for drivers as switching between modes of operation at runtime based on the
149 based on probe deferral.  In any case optional resources are beyond the
150 scope of device links.
155 * An MMU device exists alongside a busmaster device, both are in the same
157   device and shall be runtime resumed and kept active whenever and as long
158   as the busmaster device is active.  The busmaster device's driver shall
159   not bind before the MMU is bound.  To achieve this, a device link with
160   runtime PM integration is added from the busmaster device (consumer)
161   to the MMU device (supplier).  The effect with regards to runtime PM
162   is the same as if the MMU was the parent of the master device.
167   switch, but rather the MMU device serves the busmaster device and is
168   useless without it.  A device link creates a synthetic hierarchical
172   and an NHI device to manage the PCIe switch.  On resume from system sleep,
173   the NHI device needs to re-establish PCI tunnels to attached devices
177   device links from the hotplug ports (consumers) to the NHI device
182   for HDMI/DP audio.  In the device hierarchy the HDA controller is a sibling
183   of the VGA device, yet both share the same power domain and the HDA
185   VGA device.  A device link from the HDA controller (consumer) to the
186   VGA device (supplier) aptly represents this relationship.
188 * ACPI allows definition of a device start order by way of _DEP objects.
189   A classical example is when ACPI power management methods on one device
192   management of the device in question to work.
195   video processing IP cores on transparent memory access IP cores that handle
202   class or device type callbacks.  It is intended for devices sharing
203   a single on/off switch, however it does not guarantee a specific
211   device link and does not allow for shutdown ordering or driver presence
212   dependencies.  It also cannot be used on ACPI systems.
217 The device hierarchy, which -- as the name implies -- is a tree,
218 becomes a directed acyclic graph once device links are added.
222 no device links present, the two lists are a flattened, one-dimensional
223 representations of the device tree such that a device is placed behind
225 or OpenFirmware device tree top-down and appending devices to the lists
228 Once device links are added, the lists need to satisfy the additional
229 constraint that a device is placed behind all its suppliers, recursively.
230 To ensure this, upon addition of the device link the consumer and the
231 entire sub-graph below it (all children and consumers of the consumer)
236 verified upon device link addition that the supplier is not dependent
237 on the consumer or any children or consumers of the consumer.
242 Notably this also prevents the addition of a device link from a parent
243 device to a child.  However the converse is allowed, i.e. a device link
246 such a device link only makes sense if a driver presence dependency is
247 needed on top of that.  In this case driver authors should weigh
248 carefully if a device link is at all the right tool for the purpose.
250 add a device flag causing the parent driver to be probed before the
256 .. kernel-doc:: include/linux/device.h
269 * The initial state of a device link is automatically determined by
270   :c:func:`device_link_add()` based on the driver presence on the supplier
274 * When a supplier device is bound to a driver, links to its consumers
279 * Before a consumer device is probed, presence of supplier drivers is
280   verified by checking the consumer device is not in the wait_for_suppliers
295 * When the consumer's driver is later on removed, links to suppliers revert