321 lines · plain
1.. _device_link:2 3============4Device links5============6 7By default, the driver core only enforces dependencies between devices8that are borne out of a parent/child relationship within the device9hierarchy: When suspending, resuming or shutting down the system, devices10are ordered based on this relationship, i.e. children are always suspended11before their parent, and the parent is always resumed before its children.12 13Sometimes there is a need to represent device dependencies beyond the14mere parent/child relationship, e.g. between siblings, and have the15driver core automatically take care of them.16 17Secondly, the driver core by default does not enforce any driver presence18dependencies, i.e. that one device must be bound to a driver before19another one can probe or function correctly.20 21Often these two dependency types come together, so a device depends on22another one both with regards to driver presence *and* with regards to23suspend/resume and shutdown ordering.24 25Device links allow representation of such dependencies in the driver core.26 27In its standard or *managed* form, a device link combines *both* dependency28types: It guarantees correct suspend/resume and shutdown ordering between a29"supplier" device and its "consumer" devices, and it guarantees driver30presence on the supplier. The consumer devices are not probed before the31supplier is bound to a driver, and they're unbound before the supplier32is unbound.33 34When driver presence on the supplier is irrelevant and only correct35suspend/resume and shutdown ordering is needed, the device link may36simply be set up with the ``DL_FLAG_STATELESS`` flag. In other words,37enforcing driver presence on the supplier is optional.38 39Another optional feature is runtime PM integration: By setting the40``DL_FLAG_PM_RUNTIME`` flag on addition of the device link, the PM core41is instructed to runtime resume the supplier and keep it active42whenever and for as long as the consumer is runtime resumed.43 44Usage45=====46 47The earliest point in time when device links can be added is after48:c:func:`device_add()` has been called for the supplier and49:c:func:`device_initialize()` has been called for the consumer.50 51It is legal to add them later, but care must be taken that the system52remains in a consistent state: E.g. a device link cannot be added in53the midst of a suspend/resume transition, so either commencement of54such a transition needs to be prevented with :c:func:`lock_system_sleep()`,55or the device link needs to be added from a function which is guaranteed56not to run in parallel to a suspend/resume transition, such as from a57device ``->probe`` callback or a boot-time PCI quirk.58 59Another example for an inconsistent state would be a device link that60represents a driver presence dependency, yet is added from the consumer's61``->probe`` callback while the supplier hasn't started to probe yet: Had the62driver core known about the device link earlier, it wouldn't have probed the63consumer in the first place. The onus is thus on the consumer to check64presence of the supplier after adding the link, and defer probing on65non-presence. [Note that it is valid to create a link from the consumer's66``->probe`` callback while the supplier is still probing, but the consumer must67know that the supplier is functional already at the link creation time (that is68the case, for instance, if the consumer has just acquired some resources that69would not have been available had the supplier not been functional then).]70 71If a device link with ``DL_FLAG_STATELESS`` set (i.e. a stateless device link)72is added in the ``->probe`` callback of the supplier or consumer driver, it is73typically deleted in its ``->remove`` callback for symmetry. That way, if the74driver is compiled as a module, the device link is added on module load and75orderly deleted on unload. The same restrictions that apply to device link76addition (e.g. exclusion of a parallel suspend/resume transition) apply equally77to deletion. Device links managed by the driver core are deleted automatically78by it.79 80Several flags may be specified on device link addition, two of which81have already been mentioned above: ``DL_FLAG_STATELESS`` to express that no82driver presence dependency is needed (but only correct suspend/resume and83shutdown ordering) and ``DL_FLAG_PM_RUNTIME`` to express that runtime PM84integration is desired.85 86Two other flags are specifically targeted at use cases where the device87link is added from the consumer's ``->probe`` callback: ``DL_FLAG_RPM_ACTIVE``88can be specified to runtime resume the supplier and prevent it from suspending89before the consumer is runtime suspended. ``DL_FLAG_AUTOREMOVE_CONSUMER``90causes the device link to be automatically purged when the consumer fails to91probe or later unbinds.92 93Similarly, when the device link is added from supplier's ``->probe`` callback,94``DL_FLAG_AUTOREMOVE_SUPPLIER`` causes the device link to be automatically95purged when the supplier fails to probe or later unbinds.96 97If neither ``DL_FLAG_AUTOREMOVE_CONSUMER`` nor ``DL_FLAG_AUTOREMOVE_SUPPLIER``98is set, ``DL_FLAG_AUTOPROBE_CONSUMER`` can be used to request the driver core99to probe for a driver for the consumer driver on the link automatically after100a driver has been bound to the supplier device.101 102Note, however, that any combinations of ``DL_FLAG_AUTOREMOVE_CONSUMER``,103``DL_FLAG_AUTOREMOVE_SUPPLIER`` or ``DL_FLAG_AUTOPROBE_CONSUMER`` with104``DL_FLAG_STATELESS`` are invalid and cannot be used.105 106Limitations107===========108 109Driver authors should be aware that a driver presence dependency for managed110device links (i.e. when ``DL_FLAG_STATELESS`` is not specified on link addition)111may cause probing of the consumer to be deferred indefinitely. This can become112a problem if the consumer is required to probe before a certain initcall level113is reached. Worse, if the supplier driver is blacklisted or missing, the114consumer will never be probed.115 116Moreover, managed device links cannot be deleted directly. They are deleted117by the driver core when they are not necessary any more in accordance with the118``DL_FLAG_AUTOREMOVE_CONSUMER`` and ``DL_FLAG_AUTOREMOVE_SUPPLIER`` flags.119However, stateless device links (i.e. device links with ``DL_FLAG_STATELESS``120set) are expected to be removed by whoever called :c:func:`device_link_add()`121to add them with the help of either :c:func:`device_link_del()` or122:c:func:`device_link_remove()`.123 124Passing ``DL_FLAG_RPM_ACTIVE`` along with ``DL_FLAG_STATELESS`` to125:c:func:`device_link_add()` may cause the PM-runtime usage counter of the126supplier device to remain nonzero after a subsequent invocation of either127:c:func:`device_link_del()` or :c:func:`device_link_remove()` to remove the128device link returned by it. This happens if :c:func:`device_link_add()` is129called twice in a row for the same consumer-supplier pair without removing the130link between these calls, in which case allowing the PM-runtime usage counter131of the supplier to drop on an attempt to remove the link may cause it to be132suspended while the consumer is still PM-runtime-active and that has to be133avoided. [To work around this limitation it is sufficient to let the consumer134runtime suspend at least once, or call :c:func:`pm_runtime_set_suspended()` for135it with PM-runtime disabled, between the :c:func:`device_link_add()` and136:c:func:`device_link_del()` or :c:func:`device_link_remove()` calls.]137 138Sometimes drivers depend on optional resources. They are able to operate139in a degraded mode (reduced feature set or performance) when those resources140are not present. An example is an SPI controller that can use a DMA engine141or work in PIO mode. The controller can determine presence of the optional142resources at probe time but on non-presence there is no way to know whether143they will become available in the near future (due to a supplier driver144probing) or never. Consequently it cannot be determined whether to defer145probing or not. It would be possible to notify drivers when optional146resources become available after probing, but it would come at a high cost147for drivers as switching between modes of operation at runtime based on the148availability of such resources would be much more complex than a mechanism149based on probe deferral. In any case optional resources are beyond the150scope of device links.151 152Examples153========154 155* An MMU device exists alongside a busmaster device, both are in the same156 power domain. The MMU implements DMA address translation for the busmaster157 device and shall be runtime resumed and kept active whenever and as long158 as the busmaster device is active. The busmaster device's driver shall159 not bind before the MMU is bound. To achieve this, a device link with160 runtime PM integration is added from the busmaster device (consumer)161 to the MMU device (supplier). The effect with regards to runtime PM162 is the same as if the MMU was the parent of the master device.163 164 The fact that both devices share the same power domain would normally165 suggest usage of a struct dev_pm_domain or struct generic_pm_domain,166 however these are not independent devices that happen to share a power167 switch, but rather the MMU device serves the busmaster device and is168 useless without it. A device link creates a synthetic hierarchical169 relationship between the devices and is thus more apt.170 171* A Thunderbolt host controller comprises a number of PCIe hotplug ports172 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 devices174 before the hotplug ports can resume. If the hotplug ports were children175 of the NHI, this resume order would automatically be enforced by the176 PM core, but unfortunately they're aunts. The solution is to add177 device links from the hotplug ports (consumers) to the NHI device178 (supplier). A driver presence dependency is not necessary for this179 use case.180 181* Discrete GPUs in hybrid graphics laptops often feature an HDA controller182 for HDMI/DP audio. In the device hierarchy the HDA controller is a sibling183 of the VGA device, yet both share the same power domain and the HDA184 controller is only ever needed when an HDMI/DP display is attached to the185 VGA device. A device link from the HDA controller (consumer) to the186 VGA device (supplier) aptly represents this relationship.187 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 device190 are implemented in terms of I\ :sup:`2`\ C accesses and require a specific191 I\ :sup:`2`\ C controller to be present and functional for the power192 management of the device in question to work.193 194* In some SoCs a functional dependency exists from display, video codec and195 video processing IP cores on transparent memory access IP cores that handle196 burst access and compression/decompression.197 198Alternatives199============200 201* A struct dev_pm_domain can be used to override the bus,202 class or device type callbacks. It is intended for devices sharing203 a single on/off switch, however it does not guarantee a specific204 suspend/resume ordering, this needs to be implemented separately.205 It also does not by itself track the runtime PM status of the involved206 devices and turn off the power switch only when all of them are runtime207 suspended. Furthermore it cannot be used to enforce a specific shutdown208 ordering or a driver presence dependency.209 210* A struct generic_pm_domain is a lot more heavyweight than a211 device link and does not allow for shutdown ordering or driver presence212 dependencies. It also cannot be used on ACPI systems.213 214Implementation215==============216 217The device hierarchy, which -- as the name implies -- is a tree,218becomes a directed acyclic graph once device links are added.219 220Ordering of these devices during suspend/resume is determined by the221dpm_list. During shutdown it is determined by the devices_kset. With222no device links present, the two lists are a flattened, one-dimensional223representations of the device tree such that a device is placed behind224all its ancestors. That is achieved by traversing the ACPI namespace225or OpenFirmware device tree top-down and appending devices to the lists226as they are discovered.227 228Once device links are added, the lists need to satisfy the additional229constraint that a device is placed behind all its suppliers, recursively.230To ensure this, upon addition of the device link the consumer and the231entire sub-graph below it (all children and consumers of the consumer)232are moved to the end of the list. (Call to :c:func:`device_reorder_to_tail()`233from :c:func:`device_link_add()`.)234 235To prevent introduction of dependency loops into the graph, it is236verified upon device link addition that the supplier is not dependent237on the consumer or any children or consumers of the consumer.238(Call to :c:func:`device_is_dependent()` from :c:func:`device_link_add()`.)239If that constraint is violated, :c:func:`device_link_add()` will return240``NULL`` and a ``WARNING`` will be logged.241 242Notably this also prevents the addition of a device link from a parent243device to a child. However the converse is allowed, i.e. a device link244from a child to a parent. Since the driver core already guarantees245correct suspend/resume and shutdown ordering between parent and child,246such a device link only makes sense if a driver presence dependency is247needed on top of that. In this case driver authors should weigh248carefully if a device link is at all the right tool for the purpose.249A more suitable approach might be to simply use deferred probing or250add a device flag causing the parent driver to be probed before the251child one.252 253State machine254=============255 256.. kernel-doc:: include/linux/device.h257 :functions: device_link_state258 259::260 261 .=============================.262 | |263 v |264 DORMANT <=> AVAILABLE <=> CONSUMER_PROBE => ACTIVE265 ^ |266 | |267 '============ SUPPLIER_UNBIND <============'268 269* The initial state of a device link is automatically determined by270 :c:func:`device_link_add()` based on the driver presence on the supplier271 and consumer. If the link is created before any devices are probed, it272 is set to ``DL_STATE_DORMANT``.273 274* When a supplier device is bound to a driver, links to its consumers275 progress to ``DL_STATE_AVAILABLE``.276 (Call to :c:func:`device_links_driver_bound()` from277 :c:func:`driver_bound()`.)278 279* Before a consumer device is probed, presence of supplier drivers is280 verified by checking the consumer device is not in the wait_for_suppliers281 list and by checking that links to suppliers are in ``DL_STATE_AVAILABLE``282 state. The state of the links is updated to ``DL_STATE_CONSUMER_PROBE``.283 (Call to :c:func:`device_links_check_suppliers()` from284 :c:func:`really_probe()`.)285 This prevents the supplier from unbinding.286 (Call to :c:func:`wait_for_device_probe()` from287 :c:func:`device_links_unbind_consumers()`.)288 289* If the probe fails, links to suppliers revert back to ``DL_STATE_AVAILABLE``.290 (Call to :c:func:`device_links_no_driver()` from :c:func:`really_probe()`.)291 292* If the probe succeeds, links to suppliers progress to ``DL_STATE_ACTIVE``.293 (Call to :c:func:`device_links_driver_bound()` from :c:func:`driver_bound()`.)294 295* When the consumer's driver is later on removed, links to suppliers revert296 back to ``DL_STATE_AVAILABLE``.297 (Call to :c:func:`__device_links_no_driver()` from298 :c:func:`device_links_driver_cleanup()`, which in turn is called from299 :c:func:`__device_release_driver()`.)300 301* Before a supplier's driver is removed, links to consumers that are not302 bound to a driver are updated to ``DL_STATE_SUPPLIER_UNBIND``.303 (Call to :c:func:`device_links_busy()` from304 :c:func:`__device_release_driver()`.)305 This prevents the consumers from binding.306 (Call to :c:func:`device_links_check_suppliers()` from307 :c:func:`really_probe()`.)308 Consumers that are bound are freed from their driver; consumers that are309 probing are waited for until they are done.310 (Call to :c:func:`device_links_unbind_consumers()` from311 :c:func:`__device_release_driver()`.)312 Once all links to consumers are in ``DL_STATE_SUPPLIER_UNBIND`` state,313 the supplier driver is released and the links revert to ``DL_STATE_DORMANT``.314 (Call to :c:func:`device_links_driver_cleanup()` from315 :c:func:`__device_release_driver()`.)316 317API318===319 320See device_link_add(), device_link_del() and device_link_remove().321