write in 30M

hc

2024-02-20 ea08eeccae9297f7aabd2ef7f0c2517ac4549acc

 kernel/Documentation/driver-api/device_link.rst
..
..
@@ -1,5 +1,4 @@
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>`
1
+.. _device_link:
3
2
 
4
3
 ============
5
4
 Device links
..
..
@@ -86,9 +85,10 @@
86
85
 
87
86
 Two other flags are specifically targeted at use cases where the device
88
87
 link is added from the consumer's ``->probe`` callback:  ``DL_FLAG_RPM_ACTIVE``
89
-can be specified to runtime resume the supplier upon addition of the
90
-device link.  ``DL_FLAG_AUTOREMOVE_CONSUMER`` causes the device link to be
91
-automatically purged when the consumer fails to probe or later unbinds.
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
92
 
93
93
 Similarly, when the device link is added from supplier's ``->probe`` callback,
94
94
 ``DL_FLAG_AUTOREMOVE_SUPPLIER`` causes the device link to be automatically
..
..
@@ -121,6 +121,20 @@
121
121
 to add them with the help of either :c:func:`device_link_del()` or
122
122
 :c:func:`device_link_remove()`.
123
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
+
124
138
 Sometimes drivers depend on optional resources.  They are able to operate
125
139
 in a degraded mode (reduced feature set or performance) when those resources
126
140
 are not present.  An example is an SPI controller that can use a DMA engine
..
..
@@ -148,7 +162,7 @@
148
162
   is the same as if the MMU was the parent of the master device.
149
163
 
150
164
   The fact that both devices share the same power domain would normally
151
-  suggest usage of a |struct dev_pm_domain| or |struct generic_pm_domain|,
165
+  suggest usage of a struct dev_pm_domain or struct generic_pm_domain,
152
166
   however these are not independent devices that happen to share a power
153
167
   switch, but rather the MMU device serves the busmaster device and is
154
168
   useless without it.  A device link creates a synthetic hierarchical
..
..
@@ -184,7 +198,7 @@
184
198
 Alternatives
185
199
 ============
186
200
 
187
-* A |struct dev_pm_domain| can be used to override the bus,
201
+* A struct dev_pm_domain can be used to override the bus,
188
202
   class or device type callbacks.  It is intended for devices sharing
189
203
   a single on/off switch, however it does not guarantee a specific
190
204
   suspend/resume ordering, this needs to be implemented separately.
..
..
@@ -193,7 +207,7 @@
193
207
   suspended.  Furthermore it cannot be used to enforce a specific shutdown
194
208
   ordering or a driver presence dependency.
195
209
 
196
-* A |struct generic_pm_domain| is a lot more heavyweight than a
210
+* A struct generic_pm_domain is a lot more heavyweight than a
197
211
   device link and does not allow for shutdown ordering or driver presence
198
212
   dependencies.  It also cannot be used on ACPI systems.
199
213
 
..
..
@@ -303,5 +317,4 @@
303
317
 API
304
318
 ===
305
319
 
306
-.. kernel-doc:: drivers/base/core.c
307
-   :functions: device_link_add device_link_del device_link_remove
320
+See device_link_add(), device_link_del() and device_link_remove().