device_link.rst 16 KB

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