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