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