Documentation/driver-api/device_link.rst

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