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