Orange Pi5 kernel

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