Documentation/driver-api/device_link.rst

   1 .. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>`
   2 .. |struct generic_pm_domain| replace:: :c:type:`struct generic_pm_domain <generic_pm_domain>`
   3
   4 ============
   5 Device links
   6 ============
   7
   8 By default, the driver core only enforces dependencies between devices
   9 that are borne out of a parent/child relationship within the device
  10 hierarchy: When suspending, resuming or shutting down the system, devices
  11 are ordered based on this relationship, i.e. children are always suspended
  12 before their parent, and the parent is always resumed before its children.
  13
  14 Sometimes there is a need to represent device dependencies beyond the
  15 mere parent/child relationship, e.g. between siblings, and have the
  16 driver core automatically take care of them.
  17
  18 Secondly, the driver core by default does not enforce any driver presence
  19 dependencies, i.e. that one device must be bound to a driver before
  20 another one can probe or function correctly.
  21
  22 Often these two dependency types come together, so a device depends on
  23 another one both with regards to driver presence *and* with regards to
  24 suspend/resume and shutdown ordering.
  25
  26 Device links allow representation of such dependencies in the driver core.
  27
  28 In its standard form, a device link combines *both* dependency types:
  29 It guarantees correct suspend/resume and shutdown ordering between a
  30 "supplier" device and its "consumer" devices, and it guarantees driver
  31 presence on the supplier.  The consumer devices are not probed before the
  32 supplier is bound to a driver, and they're unbound before the supplier
  33 is unbound.
  34
  35 When driver presence on the supplier is irrelevant and only correct
  36 suspend/resume and shutdown ordering is needed, the device link may
  37 simply be set up with the ``DL_FLAG_STATELESS`` flag.  In other words,
  38 enforcing driver presence on the supplier is optional.
  39
  40 Another optional feature is runtime PM integration:  By setting the
  41 ``DL_FLAG_PM_RUNTIME`` flag on addition of the device link, the PM core
  42 is instructed to runtime resume the supplier and keep it active
  43 whenever and for as long as the consumer is runtime resumed.
  44
  45 Usage
  46 =====
  47
  48 The earliest point in time when device links can be added is after
  49 :c:func:`device_add()` has been called for the supplier and
  50 :c:func:`device_initialize()` has been called for the consumer.
  51
  52 It is legal to add them later, but care must be taken that the system
  53 remains in a consistent state:  E.g. a device link cannot be added in
  54 the midst of a suspend/resume transition, so either commencement of
  55 such a transition needs to be prevented with :c:func:`lock_system_sleep()`,
  56 or the device link needs to be added from a function which is guaranteed
  57 not to run in parallel to a suspend/resume transition, such as from a
  58 device ``->probe`` callback or a boot-time PCI quirk.
  59
  60 Another example for an inconsistent state would be a device link that
  61 represents a driver presence dependency, yet is added from the consumer's
  62 ``->probe`` callback while the supplier hasn't probed yet:  Had the driver
  63 core known about the device link earlier, it wouldn't have probed the
  64 consumer in the first place.  The onus is thus on the consumer to check
  65 presence of the supplier after adding the link, and defer probing on
  66 non-presence.
  67
  68 If a device link is added in the ``->probe`` callback of the supplier or
  69 consumer driver, it is typically deleted in its ``->remove`` callback for
  70 symmetry.  That way, if the driver is compiled as a module, the device
  71 link is added on module load and orderly deleted on unload.  The same
  72 restrictions that apply to device link addition (e.g. exclusion of a
  73 parallel suspend/resume transition) apply equally to deletion.
  74
  75 Several flags may be specified on device link addition, two of which
  76 have already been mentioned above:  ``DL_FLAG_STATELESS`` to express that no
  77 driver presence dependency is needed (but only correct suspend/resume and
  78 shutdown ordering) and ``DL_FLAG_PM_RUNTIME`` to express that runtime PM
  79 integration is desired.
  80
  81 Two other flags are specifically targeted at use cases where the device
  82 link is added from the consumer's ``->probe`` callback:  ``DL_FLAG_RPM_ACTIVE``
  83 can be specified to runtime resume the supplier upon addition of the
  84 device link.  ``DL_FLAG_AUTOREMOVE_CONSUMER`` causes the device link to be
  85 automatically purged when the consumer fails to probe or later unbinds.
  86 This obviates the need to explicitly delete the link in the ``->remove``
  87 callback or in the error path of the ``->probe`` callback.
  88
  89 Similarly, when the device link is added from supplier's ``->probe`` callback,
  90 ``DL_FLAG_AUTOREMOVE_SUPPLIER`` causes the device link to be automatically
  91 purged when the supplier fails to probe or later unbinds.
  92
  93 Limitations
  94 ===========
  95
  96 Driver authors should be aware that a driver presence dependency (i.e. when
  97 ``DL_FLAG_STATELESS`` is not specified on link addition) may cause probing of
  98 the consumer to be deferred indefinitely.  This can become a problem if the
  99 consumer is required to probe before a certain initcall level is reached.
 100 Worse, if the supplier driver is blacklisted or missing, the consumer will
 101 never be probed.
 102
 103 Sometimes drivers depend on optional resources.  They are able to operate
 104 in a degraded mode (reduced feature set or performance) when those resources
 105 are not present.  An example is an SPI controller that can use a DMA engine
 106 or work in PIO mode.  The controller can determine presence of the optional
 107 resources at probe time but on non-presence there is no way to know whether
 108 they will become available in the near future (due to a supplier driver
 109 probing) or never.  Consequently it cannot be determined whether to defer
 110 probing or not.  It would be possible to notify drivers when optional
 111 resources become available after probing, but it would come at a high cost
 112 for drivers as switching between modes of operation at runtime based on the
 113 availability of such resources would be much more complex than a mechanism
 114 based on probe deferral.  In any case optional resources are beyond the
 115 scope of device links.
 116
 117 Examples
 118 ========
 119
 120 * An MMU device exists alongside a busmaster device, both are in the same
 121   power domain.  The MMU implements DMA address translation for the busmaster
 122   device and shall be runtime resumed and kept active whenever and as long
 123   as the busmaster device is active.  The busmaster device's driver shall
 124   not bind before the MMU is bound.  To achieve this, a device link with
 125   runtime PM integration is added from the busmaster device (consumer)
 126   to the MMU device (supplier).  The effect with regards to runtime PM
 127   is the same as if the MMU was the parent of the master device.
 128
 129   The fact that both devices share the same power domain would normally
 130   suggest usage of a |struct dev_pm_domain| or |struct generic_pm_domain|,
 131   however these are not independent devices that happen to share a power
 132   switch, but rather the MMU device serves the busmaster device and is
 133   useless without it.  A device link creates a synthetic hierarchical
 134   relationship between the devices and is thus more apt.
 135
 136 * A Thunderbolt host controller comprises a number of PCIe hotplug ports
 137   and an NHI device to manage the PCIe switch.  On resume from system sleep,
 138   the NHI device needs to re-establish PCI tunnels to attached devices
 139   before the hotplug ports can resume.  If the hotplug ports were children
 140   of the NHI, this resume order would automatically be enforced by the
 141   PM core, but unfortunately they're aunts.  The solution is to add
 142   device links from the hotplug ports (consumers) to the NHI device
 143   (supplier).  A driver presence dependency is not necessary for this
 144   use case.
 145
 146 * Discrete GPUs in hybrid graphics laptops often feature an HDA controller
 147   for HDMI/DP audio.  In the device hierarchy the HDA controller is a sibling
 148   of the VGA device, yet both share the same power domain and the HDA
 149   controller is only ever needed when an HDMI/DP display is attached to the
 150   VGA device.  A device link from the HDA controller (consumer) to the
 151   VGA device (supplier) aptly represents this relationship.
 152
 153 * ACPI allows definition of a device start order by way of _DEP objects.
 154   A classical example is when ACPI power management methods on one device
 155   are implemented in terms of I\ :sup:`2`\ C accesses and require a specific
 156   I\ :sup:`2`\ C controller to be present and functional for the power
 157   management of the device in question to work.
 158
 159 * In some SoCs a functional dependency exists from display, video codec and
 160   video processing IP cores on transparent memory access IP cores that handle
 161   burst access and compression/decompression.
 162
 163 Alternatives
 164 ============
 165
 166 * A |struct dev_pm_domain| can be used to override the bus,
 167   class or device type callbacks.  It is intended for devices sharing
 168   a single on/off switch, however it does not guarantee a specific
 169   suspend/resume ordering, this needs to be implemented separately.
 170   It also does not by itself track the runtime PM status of the involved
 171   devices and turn off the power switch only when all of them are runtime
 172   suspended.  Furthermore it cannot be used to enforce a specific shutdown
 173   ordering or a driver presence dependency.
 174
 175 * A |struct generic_pm_domain| is a lot more heavyweight than a
 176   device link and does not allow for shutdown ordering or driver presence
 177   dependencies.  It also cannot be used on ACPI systems.
 178
 179 Implementation
 180 ==============
 181
 182 The device hierarchy, which -- as the name implies -- is a tree,
 183 becomes a directed acyclic graph once device links are added.
 184
 185 Ordering of these devices during suspend/resume is determined by the
 186 dpm_list.  During shutdown it is determined by the devices_kset.  With
 187 no device links present, the two lists are a flattened, one-dimensional
 188 representations of the device tree such that a device is placed behind
 189 all its ancestors.  That is achieved by traversing the ACPI namespace
 190 or OpenFirmware device tree top-down and appending devices to the lists
 191 as they are discovered.
 192
 193 Once device links are added, the lists need to satisfy the additional
 194 constraint that a device is placed behind all its suppliers, recursively.
 195 To ensure this, upon addition of the device link the consumer and the
 196 entire sub-graph below it (all children and consumers of the consumer)
 197 are moved to the end of the list.  (Call to :c:func:`device_reorder_to_tail()`
 198 from :c:func:`device_link_add()`.)
 199
 200 To prevent introduction of dependency loops into the graph, it is
 201 verified upon device link addition that the supplier is not dependent
 202 on the consumer or any children or consumers of the consumer.
 203 (Call to :c:func:`device_is_dependent()` from :c:func:`device_link_add()`.)
 204 If that constraint is violated, :c:func:`device_link_add()` will return
 205 ``NULL`` and a ``WARNING`` will be logged.
 206
 207 Notably this also prevents the addition of a device link from a parent
 208 device to a child.  However the converse is allowed, i.e. a device link
 209 from a child to a parent.  Since the driver core already guarantees
 210 correct suspend/resume and shutdown ordering between parent and child,
 211 such a device link only makes sense if a driver presence dependency is
 212 needed on top of that.  In this case driver authors should weigh
 213 carefully if a device link is at all the right tool for the purpose.
 214 A more suitable approach might be to simply use deferred probing or
 215 add a device flag causing the parent driver to be probed before the
 216 child one.
 217
 218 State machine
 219 =============
 220
 221 .. kernel-doc:: include/linux/device.h
 222    :functions: device_link_state
 223
 224 ::
 225
 226                  .=============================.
 227                  |                             |
 228                  v                             |
 229  DORMANT <=> AVAILABLE <=> CONSUMER_PROBE => ACTIVE
 230     ^                                          |
 231     |                                          |
 232     '============ SUPPLIER_UNBIND <============'
 233
 234 * The initial state of a device link is automatically determined by
 235   :c:func:`device_link_add()` based on the driver presence on the supplier
 236   and consumer.  If the link is created before any devices are probed, it
 237   is set to ``DL_STATE_DORMANT``.
 238
 239 * When a supplier device is bound to a driver, links to its consumers
 240   progress to ``DL_STATE_AVAILABLE``.
 241   (Call to :c:func:`device_links_driver_bound()` from
 242   :c:func:`driver_bound()`.)
 243
 244 * Before a consumer device is probed, presence of supplier drivers is
 245   verified by checking that links to suppliers are in ``DL_STATE_AVAILABLE``
 246   state.  The state of the links is updated to ``DL_STATE_CONSUMER_PROBE``.
 247   (Call to :c:func:`device_links_check_suppliers()` from
 248   :c:func:`really_probe()`.)
 249   This prevents the supplier from unbinding.
 250   (Call to :c:func:`wait_for_device_probe()` from
 251   :c:func:`device_links_unbind_consumers()`.)
 252
 253 * If the probe fails, links to suppliers revert back to ``DL_STATE_AVAILABLE``.
 254   (Call to :c:func:`device_links_no_driver()` from :c:func:`really_probe()`.)
 255
 256 * If the probe succeeds, links to suppliers progress to ``DL_STATE_ACTIVE``.
 257   (Call to :c:func:`device_links_driver_bound()` from :c:func:`driver_bound()`.)
 258
 259 * When the consumer's driver is later on removed, links to suppliers revert
 260   back to ``DL_STATE_AVAILABLE``.
 261   (Call to :c:func:`__device_links_no_driver()` from
 262   :c:func:`device_links_driver_cleanup()`, which in turn is called from
 263   :c:func:`__device_release_driver()`.)
 264
 265 * Before a supplier's driver is removed, links to consumers that are not
 266   bound to a driver are updated to ``DL_STATE_SUPPLIER_UNBIND``.
 267   (Call to :c:func:`device_links_busy()` from
 268   :c:func:`__device_release_driver()`.)
 269   This prevents the consumers from binding.
 270   (Call to :c:func:`device_links_check_suppliers()` from
 271   :c:func:`really_probe()`.)
 272   Consumers that are bound are freed from their driver; consumers that are
 273   probing are waited for until they are done.
 274   (Call to :c:func:`device_links_unbind_consumers()` from
 275   :c:func:`__device_release_driver()`.)
 276   Once all links to consumers are in ``DL_STATE_SUPPLIER_UNBIND`` state,
 277   the supplier driver is released and the links revert to ``DL_STATE_DORMANT``.
 278   (Call to :c:func:`device_links_driver_cleanup()` from
 279   :c:func:`__device_release_driver()`.)
 280
 281 API
 282 ===
 283
 284 .. kernel-doc:: drivers/base/core.c
 285    :functions: device_link_add device_link_del