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