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 LW |
88 | |
89 | Limitations | |
90 | =========== | |
91 | ||
92 | Driver authors should be aware that a driver presence dependency (i.e. when | |
93 | ``DL_FLAG_STATELESS`` is not specified on link addition) may cause probing of | |
94 | the consumer to be deferred indefinitely. This can become a problem if the | |
95 | consumer is required to probe before a certain initcall level is reached. | |
96 | Worse, if the supplier driver is blacklisted or missing, the consumer will | |
97 | never be probed. | |
98 | ||
99 | Sometimes drivers depend on optional resources. They are able to operate | |
100 | in a degraded mode (reduced feature set or performance) when those resources | |
101 | are not present. An example is an SPI controller that can use a DMA engine | |
102 | or work in PIO mode. The controller can determine presence of the optional | |
103 | resources at probe time but on non-presence there is no way to know whether | |
104 | they will become available in the near future (due to a supplier driver | |
105 | probing) or never. Consequently it cannot be determined whether to defer | |
106 | probing or not. It would be possible to notify drivers when optional | |
107 | resources become available after probing, but it would come at a high cost | |
108 | for drivers as switching between modes of operation at runtime based on the | |
109 | availability of such resources would be much more complex than a mechanism | |
110 | based on probe deferral. In any case optional resources are beyond the | |
111 | scope of device links. | |
112 | ||
113 | Examples | |
114 | ======== | |
115 | ||
116 | * An MMU device exists alongside a busmaster device, both are in the same | |
117 | power domain. The MMU implements DMA address translation for the busmaster | |
118 | device and shall be runtime resumed and kept active whenever and as long | |
119 | as the busmaster device is active. The busmaster device's driver shall | |
120 | not bind before the MMU is bound. To achieve this, a device link with | |
121 | runtime PM integration is added from the busmaster device (consumer) | |
122 | to the MMU device (supplier). The effect with regards to runtime PM | |
123 | is the same as if the MMU was the parent of the master device. | |
124 | ||
125 | The fact that both devices share the same power domain would normally | |
bd856262 RW |
126 | suggest usage of a |struct dev_pm_domain| or |struct generic_pm_domain|, |
127 | however these are not independent devices that happen to share a power | |
128 | switch, but rather the MMU device serves the busmaster device and is | |
129 | useless without it. A device link creates a synthetic hierarchical | |
130 | relationship between the devices and is thus more apt. | |
aad80040 LW |
131 | |
132 | * A Thunderbolt host controller comprises a number of PCIe hotplug ports | |
133 | and an NHI device to manage the PCIe switch. On resume from system sleep, | |
134 | the NHI device needs to re-establish PCI tunnels to attached devices | |
135 | before the hotplug ports can resume. If the hotplug ports were children | |
136 | of the NHI, this resume order would automatically be enforced by the | |
137 | PM core, but unfortunately they're aunts. The solution is to add | |
138 | device links from the hotplug ports (consumers) to the NHI device | |
139 | (supplier). A driver presence dependency is not necessary for this | |
140 | use case. | |
141 | ||
142 | * Discrete GPUs in hybrid graphics laptops often feature an HDA controller | |
143 | for HDMI/DP audio. In the device hierarchy the HDA controller is a sibling | |
144 | of the VGA device, yet both share the same power domain and the HDA | |
145 | controller is only ever needed when an HDMI/DP display is attached to the | |
146 | VGA device. A device link from the HDA controller (consumer) to the | |
147 | VGA device (supplier) aptly represents this relationship. | |
148 | ||
149 | * ACPI allows definition of a device start order by way of _DEP objects. | |
150 | A classical example is when ACPI power management methods on one device | |
151 | are implemented in terms of I\ :sup:`2`\ C accesses and require a specific | |
152 | I\ :sup:`2`\ C controller to be present and functional for the power | |
153 | management of the device in question to work. | |
154 | ||
155 | * In some SoCs a functional dependency exists from display, video codec and | |
156 | video processing IP cores on transparent memory access IP cores that handle | |
157 | burst access and compression/decompression. | |
158 | ||
159 | Alternatives | |
160 | ============ | |
161 | ||
bd856262 | 162 | * A |struct dev_pm_domain| can be used to override the bus, |
aad80040 LW |
163 | class or device type callbacks. It is intended for devices sharing |
164 | a single on/off switch, however it does not guarantee a specific | |
165 | suspend/resume ordering, this needs to be implemented separately. | |
166 | It also does not by itself track the runtime PM status of the involved | |
167 | devices and turn off the power switch only when all of them are runtime | |
168 | suspended. Furthermore it cannot be used to enforce a specific shutdown | |
169 | ordering or a driver presence dependency. | |
170 | ||
bd856262 | 171 | * A |struct generic_pm_domain| is a lot more heavyweight than a |
aad80040 LW |
172 | device link and does not allow for shutdown ordering or driver presence |
173 | dependencies. It also cannot be used on ACPI systems. | |
174 | ||
175 | Implementation | |
176 | ============== | |
177 | ||
178 | The device hierarchy, which -- as the name implies -- is a tree, | |
179 | becomes a directed acyclic graph once device links are added. | |
180 | ||
181 | Ordering of these devices during suspend/resume is determined by the | |
182 | dpm_list. During shutdown it is determined by the devices_kset. With | |
183 | no device links present, the two lists are a flattened, one-dimensional | |
184 | representations of the device tree such that a device is placed behind | |
185 | all its ancestors. That is achieved by traversing the ACPI namespace | |
186 | or OpenFirmware device tree top-down and appending devices to the lists | |
187 | as they are discovered. | |
188 | ||
189 | Once device links are added, the lists need to satisfy the additional | |
190 | constraint that a device is placed behind all its suppliers, recursively. | |
191 | To ensure this, upon addition of the device link the consumer and the | |
192 | entire sub-graph below it (all children and consumers of the consumer) | |
193 | are moved to the end of the list. (Call to :c:func:`device_reorder_to_tail()` | |
194 | from :c:func:`device_link_add()`.) | |
195 | ||
196 | To prevent introduction of dependency loops into the graph, it is | |
197 | verified upon device link addition that the supplier is not dependent | |
198 | on the consumer or any children or consumers of the consumer. | |
199 | (Call to :c:func:`device_is_dependent()` from :c:func:`device_link_add()`.) | |
200 | If that constraint is violated, :c:func:`device_link_add()` will return | |
201 | ``NULL`` and a ``WARNING`` will be logged. | |
202 | ||
203 | Notably this also prevents the addition of a device link from a parent | |
204 | device to a child. However the converse is allowed, i.e. a device link | |
205 | from a child to a parent. Since the driver core already guarantees | |
206 | correct suspend/resume and shutdown ordering between parent and child, | |
207 | such a device link only makes sense if a driver presence dependency is | |
208 | needed on top of that. In this case driver authors should weigh | |
209 | carefully if a device link is at all the right tool for the purpose. | |
210 | A more suitable approach might be to simply use deferred probing or | |
211 | add a device flag causing the parent driver to be probed before the | |
212 | child one. | |
213 | ||
214 | State machine | |
215 | ============= | |
216 | ||
217 | .. kernel-doc:: include/linux/device.h | |
218 | :functions: device_link_state | |
219 | ||
220 | :: | |
221 | ||
222 | .=============================. | |
223 | | | | |
224 | v | | |
225 | DORMANT <=> AVAILABLE <=> CONSUMER_PROBE => ACTIVE | |
226 | ^ | | |
227 | | | | |
228 | '============ SUPPLIER_UNBIND <============' | |
229 | ||
230 | * The initial state of a device link is automatically determined by | |
231 | :c:func:`device_link_add()` based on the driver presence on the supplier | |
232 | and consumer. If the link is created before any devices are probed, it | |
233 | is set to ``DL_STATE_DORMANT``. | |
234 | ||
235 | * When a supplier device is bound to a driver, links to its consumers | |
236 | progress to ``DL_STATE_AVAILABLE``. | |
237 | (Call to :c:func:`device_links_driver_bound()` from | |
238 | :c:func:`driver_bound()`.) | |
239 | ||
240 | * Before a consumer device is probed, presence of supplier drivers is | |
241 | verified by checking that links to suppliers are in ``DL_STATE_AVAILABLE`` | |
242 | state. The state of the links is updated to ``DL_STATE_CONSUMER_PROBE``. | |
243 | (Call to :c:func:`device_links_check_suppliers()` from | |
244 | :c:func:`really_probe()`.) | |
245 | This prevents the supplier from unbinding. | |
246 | (Call to :c:func:`wait_for_device_probe()` from | |
247 | :c:func:`device_links_unbind_consumers()`.) | |
248 | ||
249 | * If the probe fails, links to suppliers revert back to ``DL_STATE_AVAILABLE``. | |
250 | (Call to :c:func:`device_links_no_driver()` from :c:func:`really_probe()`.) | |
251 | ||
252 | * If the probe succeeds, links to suppliers progress to ``DL_STATE_ACTIVE``. | |
253 | (Call to :c:func:`device_links_driver_bound()` from :c:func:`driver_bound()`.) | |
254 | ||
255 | * When the consumer's driver is later on removed, links to suppliers revert | |
256 | back to ``DL_STATE_AVAILABLE``. | |
257 | (Call to :c:func:`__device_links_no_driver()` from | |
258 | :c:func:`device_links_driver_cleanup()`, which in turn is called from | |
259 | :c:func:`__device_release_driver()`.) | |
260 | ||
261 | * Before a supplier's driver is removed, links to consumers that are not | |
262 | bound to a driver are updated to ``DL_STATE_SUPPLIER_UNBIND``. | |
263 | (Call to :c:func:`device_links_busy()` from | |
264 | :c:func:`__device_release_driver()`.) | |
265 | This prevents the consumers from binding. | |
266 | (Call to :c:func:`device_links_check_suppliers()` from | |
267 | :c:func:`really_probe()`.) | |
268 | Consumers that are bound are freed from their driver; consumers that are | |
269 | probing are waited for until they are done. | |
270 | (Call to :c:func:`device_links_unbind_consumers()` from | |
271 | :c:func:`__device_release_driver()`.) | |
272 | Once all links to consumers are in ``DL_STATE_SUPPLIER_UNBIND`` state, | |
273 | the supplier driver is released and the links revert to ``DL_STATE_DORMANT``. | |
274 | (Call to :c:func:`device_links_driver_cleanup()` from | |
275 | :c:func:`__device_release_driver()`.) | |
276 | ||
277 | API | |
278 | === | |
279 | ||
280 | .. kernel-doc:: drivers/base/core.c | |
281 | :functions: device_link_add device_link_del |