Documentation/driver-api/device_link.rst GitHub 원문 ↗

Linux 6.18.37 · Driver API

Device links

parent/child 관계를 넘어 supplier와 consumer 사이의 driver presence, PM ordering, runtime PM dependency를 표현하는 device link를 설명합니다.

Source pathDocumentation/driver-api/device_link.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
1 .. _device_link:
2
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
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
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
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
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
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).]
70
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
77 to deletion. Device links managed by the driver core are deleted automatically
78 by it.
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``
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.
92
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
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
106 Limitations
107 ===========
108
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()`.
123
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
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
165 suggest usage of a struct dev_pm_domain or struct generic_pm_domain,
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.
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
201 * A struct dev_pm_domain can be used to override the bus,
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
210 * A struct generic_pm_domain is a lot more heavyweight than a
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
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``
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
320 See device_link_add(), device_link_del() and device_link_remove().
321

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.